ARE YOU USING SOMEONE ELSE'S SOFTWARE?
We'll give you 1-FREE month to switch to Bizstim!
Bizstim Business Software BOOK DEMO
TERMS & CONDITIONS:
  • at least 1 month with the other company
  • provide a screenshot of your billing history
  • purchase a paid subscription with us
  • when verified we'll add 1-FREE month to your account
  • you can stack our 3 months at 50%-OFF offer
  • not available to returning accounts

API Documentation

  1. Home
  2. API Docs
  3. API Index
  4. Clients
Clients › POST Methods
TABLE OF CONTENTS POST: Add Client(s) POST: Client Sales Inquiry

POST: ADD CLIENTS

Type: POST
Method: clients
Parameter: none
URL Examples:
https://www.bizstim.com/api/clients
ELEMENT TYPE DESCRIPTION
header array required

Make sure you review the mandatory structure for the header array as listed below. You MUST follow the "header" format or the import will not succeed.
data array required

Each new client record you want to add must be in an array of its own. Furthermore, each element in the array must coincide with an element from the header array.

The example shown here has a header with an array of 20 elements. This means the data array must also have 20 elements in each client array. You may add a single client using this method.		 
{
    "status": "success",
    "response": "The records were imported successfully."
}
HTTP Response:
ELEMENT TYPE DESCRIPTION
status string success or failure
response string

Possible responses are:

  • No data provided
  • No header array found
  • Trial accounts may only add 3 clients per run or 30 clients an hour
  • There was an error with 1 or more of the records. Please check the records to determine which accounts were impacted
  • The records were imported successfully

Example JSON POST Arrays

Columns 0 to 15 within the HEADER array are required! These elements must be present.

Columns 16 and so on ... within the HEADER array are optional custom fields or tags.

For custom fields you need to supply the custom ID followed by an understore "_". The text that follows the underscore is a description for you and has no bearing on the operation. You can find custom field ID's at: SETTINGS > CUSTOM FIELDS from the main menu when logged in as the administrator or staff user.

In our JSON example do not add the square bracket information. For example: [COLUMN_P_OPTIONAL]. That is there as a descriptor for the purpose of this API documentation.

[COLUMN_S_OPTIONAL] is an example of applying tags to the clients record. Tags are used to identify 1 or more characteristics of the client. Tags can be anything you like that helps you with grouping your clients for marketing, sales, services and so on.

To identify a tag it can be the tag ID or the tag name. If the tag name does not already exist the system will create a tag with that name. Please make sure you correctly spell your tags as mispellings will result in extra tags being created.

The JSON example shows you how the HEADER array must be organized and additional options available with respect to custom field data and tag assignments.

Also notice, for the DATA array each new client record has its own array. The DATA array is an array of client arrays. If you don't wish to provide information for a given column, for example, you do not have a secondary phone number, make sure to leave an empty string. This makes sure the total number of elements within each client array is equal to the total number of elements within the HEADER array.

The following elements are required for the DATA array:

  • first name
  • last name
  • state
  • country
  • status

These elements cannot be empty strings and must have data.

If you do not want to track the client's name, perhaps they are a minor, you can add a descriptor that is not the name. For example, use "New York" "Library" or "Central District" "Student" or "Student ID" "987654321." There is no condition the first_name and last_name is unique!

For trial accounts you may only import a total of 3 clients per operation. There is also a 10 operation limit per hour. Therefore trial accounts are only capable of adding 30 clients per hour to the database.

For Enterprise accounts you may import 1000 clients per operation with a limit of 1000 operations per hour.

You must name your arrays HEADER and DATA!

{
    "header":[
        "first name",
        "last name",
        "address 1",
        "address 2",
        "city",
        "state",
        "zipcode",
        "country",
        "primary phone",
        "secondary phone",
        "mobile phone",
        "e-mail",
        "DOB",
        "status",
        "start date",
        "notes",
        "[COLUMN_P_OPTIONAL - Remove brackets when live]105_custom_id_for_student_id",
        "[COLUMN_Q_OPTIONAL - Remove brackets when live]198_where_does_student_eat_lunch",
        "[COLUMN_R_OPTIONAL - Remove brackets when live]255_student_grade_level",
        "[COLUMN_S_OPTIONAL - Remove brackets when live]tags",
        ...
    ],
    "data":[
        [
            "John",
            "Smith",
            "1 Main St. East",
            "Apt. 54",
            "Bevery Hills",
            "California",
            "90210",
            "USA",
            "205-555-7777",
            "",
            "205-555-7777",
            "jsmith@bevhills.com",
            "1973-04-28",
            "active",
            "2023-05-14",
            "Any notes can go here",
            "2021154446",
            "Lunch in school",
            "Grade 6",
            "Class of 2026, Middleschool Examination, 23, District 9 sponsored"
        ],
        [
            ...
        ]
    ]
}

POST: CLIENT SALES INQUIRY

Type: POST
Method: clientinquiry
Parameters:
a = 0 or 1 save client as 'prospect' in database
b = 1, 2, or 3 inquiry e-mail recipient identifier
c = username or e-mail inquiry e-mail recipient username or defined e-mail
URL Examples:
https://www.bizstim.com/api/clientinquiry
https://www.bizstim.com/api/clientinquiry/{a}
https://www.bizstim.com/api/clientinquiry/{a}/{b}
https://www.bizstim.com/api/clientinquiry/{a}/{b}/{c}
ELEMENT TYPE DESCRIPTION
first_name string required
last_name string required
city string required
state string required
country string required
email string required
p_phone string optional
message string required 
{
    "status": "success",
    "code": 1,
    "response": "E-mail success. Client previously added to database."
}
HTTP Response:
ELEMENT TYPE DESCRIPTION
status string success or failure
code integer

The code is the return response from the API and identifies what happened with respect to the client being added to the database, and an e-mail sent to the receiver.

0 e-mail sent | client not added to the database
1 e-mail sent | client already in database
2 e-mail sent | failure adding client to database
3 e-mail sent | client added to the database
4 e-mail send error | [database outcome message]
5 validation errors

We recommend you use the return code to craft your own messages for the initiator of the client inquiry.   The return response is best suited for internal communications; e-mails or logs to track success and failures.  

response string

Possible responses are:

  • E-mail success.
  • E-mail success. Client previously added to database.
  • E-mail success. Error adding client to database.
  • E-mail success. Client added to database.
  • E-mail send error. Client previously added to the database.
  • E-mail send error. Error adding client to database.
  • E-mail send error. Client added to database.
  • E-mail send error. Client was not added to database.
  • An unordered list (ul) of validation errors

Information on Parameters

Parameter 1 Do you want to create a client record within the CRM software and assign them as a prospect?   Options are 0 : do not create a client record, 1 : create a client record, or {blank} (do not provide a parameter): do not create a client record.   If you do not provide a 0 or 1 for this parameter, you may not provide additional parameters.   In this case, only an e-mail will be sent to the admin.   The software will use the e-mail address stored for the admin user, NOT the business e-mail.   You may define an e-mail address using parameter 3.
Parameter 2 Who receives via e-mail the client inquiry?   Options are 1 : admin, 2 : staff, or 3 : defined e-mail.   To set a parameter 2, you must have a parameter 1.  
Parameter 3 If parameter 2 = 2 , provide the username of the staff user.   If parameter 2 = 3 , provide an e-mail address you want the client inquiry sent to.   The e-maill address must be constructed in a specific way.   For example: sending an e-mail to sales@mysite.com must be written as sales_mysite~com .   Replace the @ symbol with an _ (underscore), and replace the . (dot) symbol with a ~ (tilda).   The software will convert the e-mail address and check to ensure it is properly formatted.   If the e-mail is incorrectly formatted, the admin user will be notified instead.
When you specify a staff user to receive the e-mails, the staff user must be of ' active ' status, have permission to manage clients, manage the sales manager , and have an e-mail address on record.   If the staff user does not meet these requirements, the software will send the inquiry e-mail to the admin user.  

Possible API URL's

  1. https://www.bizstim.com/api/clientinquiry
    https://www.bizstim.com/api/clientinquiry/0
    https://www.bizstim.com/api/clientinquiry/0/1
    send e-mail to admin
  2. https://www.bizstim.com/api/clientinquiry/1
    https://www.bizstim.com/api/clientinquiry/1/1
    send e-mail to admin and create client record in db
  3. https://www.bizstim.com/api/clientinquiry/0/2/johngreen
    send e-mail to staff with username = johngreen
  4. https://www.bizstim.com/api/clientinquiry/1/2/johngreen
    send e-mail to staff with username = johngreen and create client record in db
  5. https://www.bizstim.com/api/clientinquiry/0/3/sales_mysite~com
    send e-mail to a defined e-mail of sales@mysite.com
  6. https://www.bizstim.com/api/clientinquiry/1/3/sales_mysite~com
    send e-mail to a defined e-mail of sales@mysite.com and create client record in db

Integration Information

When a new client is added to the database, their message is added to the sales manager.   You can access the sales manager by navigating to CLIENTS > SALES MANAGER.   From the table, choose the client you want to review and select Adv. Sales Manager from the dropdown menu.   The client inquiry message will appear in the list of messages.