Clients
The people your business serves: contact details, status, settings and the login record.
The client object
Every client record carries these fields in this order, after object, which is always "client".
| Field | Type | Description |
|---|---|---|
id | integer | |
first_name | string, up to 50 characters | |
last_name | string, up to 50 characters | |
address1 | string, up to 100 characters, nullable | |
address2 | string, up to 100 characters, nullable | |
city | string, up to 50 characters, nullable | |
state | string, up to 50 characters, nullable | |
zipcode | string, up to 25 characters, nullable | |
country | string, up to 50 characters, nullable | |
p_phone | string, up to 100 characters, nullable | |
s_phone | string, up to 100 characters, nullable | |
text_phone | string, up to 510 characters, nullable | Mobile number(s) for text messages, with the country code, comma-separated. |
dob | string, up to 10 characters | Date of birth, YYYY-MM-DD; empty when none. |
status | string, up to 25 characters | "active", "inactive" or "prospect". Only active clients can log in. A client holding an open plan stays active: a change to "inactive" or "prospect" answers 409 until the plan is ended. |
inactive_date | string, up to 10 characters, nullable | An active client is set to inactive automatically on this date, YYYY-MM-DD (account time zone); the date is then cleared. Empty when none. A client holding an open plan cannot be given one (409), and a date set before the plan started waits until the plan ends. |
inactive_reason | text | Why the client was set inactive (HTML). Cleared when the status changes to active or prospect. |
start_date | string, up to 25 characters | First day as a client, YYYY-MM-DD. Defaults to the day the client was added (account time zone). |
notes | text, nullable | Notes shown on the client page (HTML). |
timezone | string, up to 256 characters | The client's own time zone (see Timezones): the app uses it for the current date and time while they are logged in. |
send_welcome_message | integer | 1 = Send Welcome Email is checked on the client page, 0 = not. A stored setting: it does not show whether the e-mail was sent. |
send_lesson_reminders | integer | 1 = gets an e-mail reminder before each scheduled session, 0 = not. |
add_session | integer | 1 = can add sessions while logged in (added as pending until confirmed; online booking is not affected), 0 = cannot. |
see_practs_information | integer | 1 = can see the names and information of their assigned practitioners while logged in, 0 = cannot. |
text_reminders | integer | 1 = gets text (SMS) messages at text_phone (session reminders, invoices, tasks), 0 = not. |
use_records | integer | Records manager: 0 = no access, 1 = view only, 2 = view, add and edit, 3 = view, add, edit and delete. |
session_cancel | integer | 1 = can cancel sessions while logged in, 0 = cannot. |
ace | integer | Available Credit Exception. 1 = when the available credit filter is on, clients and practitioners can still add sessions for this client without enough credit; 0 = the filter applies. |
hide_costs | integer | 1 = service costs are hidden from the client while logged in, 0 = shown. |
username | string, up to 50 characters, nullable | Login name, lower case and unique across every account. Empty or null when the client has no login. |
email | string, up to 510 characters, nullable | One e-mail address or several (e.g. the client and a parent), comma-separated, lower case. |
Example
{
"object": "client",
"id": 42,
"first_name": "Jane",
"last_name": "Doe",
"address1": "12 Main Street",
"address2": "Suite 4",
"city": "Toronto",
"state": "ON",
"zipcode": "M5V 2T6",
"country": "Canada",
"p_phone": "416-555-0100",
"s_phone": "416-555-0101",
"text_phone": "416-555-0102",
"dob": "1990-05-20",
"status": "active",
"inactive_date": "2026-01-15",
"inactive_reason": "An example reason.",
"start_date": "2026-01-15",
"notes": "Prefers afternoon appointments.",
"timezone": "America/Toronto",
"send_welcome_message": 1,
"send_lesson_reminders": 1,
"add_session": 1,
"see_practs_information": 1,
"text_reminders": 1,
"use_records": 1,
"session_cancel": 1,
"ace": 1,
"hide_costs": 1,
"username": "jane.doe",
"email": "jane.doe@example.com"
} List clients
Parameters
| Parameter | In | Description |
|---|---|---|
limit | query | Records per page, 1 to 1000 (default 100). |
offset | query | Records to skip (default 0). |
email | query | Only clients whose login holds this e-mail address (exact match; a login may list several addresses). |
username | query | Only the client with this username (exact match). |
first_name | query | Only clients with this first name (exact match, combine with last_name). |
last_name | query | Only clients with this last name (exact match). |
Returns
A list envelope of client records (see Pagination).
Request
curl "https://www.bizstim.com/api/v1/clients" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Accept: application/json"<?php
$ch = curl_init('https://www.bizstim.com/api/v1/clients');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-KEY: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch('https://www.bizstim.com/api/v1/clients', {
headers: { 'X-API-KEY': 'YOUR_API_KEY', 'Accept': 'application/json' }
});
const data = await response.json();Response
{
"object": "list",
"total": 2,
"limit": 100,
"offset": 0,
"has_more": false,
"data": [
{
"object": "client",
"id": 42,
"first_name": "Jane",
"last_name": "Doe",
"address1": "12 Main Street",
"address2": "Suite 4",
"city": "Toronto",
"state": "ON",
"zipcode": "M5V 2T6",
"country": "Canada",
"p_phone": "416-555-0100",
"s_phone": "416-555-0101",
"text_phone": "416-555-0102",
"dob": "1990-05-20",
"status": "active",
"inactive_date": "2026-01-15",
"inactive_reason": "An example reason.",
"start_date": "2026-01-15",
"notes": "Prefers afternoon appointments.",
"timezone": "America/Toronto",
"send_welcome_message": 1,
"send_lesson_reminders": 1,
"add_session": 1,
"see_practs_information": 1,
"text_reminders": 1,
"use_records": 1,
"session_cancel": 1,
"ace": 1,
"hide_costs": 1,
"username": "jane.doe",
"email": "jane.doe@example.com"
},
{
"object": "client",
"id": 43,
"first_name": "Jane",
"last_name": "Doe",
"address1": "12 Main Street",
"address2": "Suite 4",
"city": "Toronto",
"state": "ON",
"zipcode": "M5V 2T6",
"country": "Canada",
"p_phone": "416-555-0100",
"s_phone": "416-555-0101",
"text_phone": "416-555-0102",
"dob": "1990-05-20",
"status": "active",
"inactive_date": "2026-01-15",
"inactive_reason": "An example reason.",
"start_date": "2026-01-15",
"notes": "Prefers afternoon appointments.",
"timezone": "America/Toronto",
"send_welcome_message": 1,
"send_lesson_reminders": 1,
"add_session": 1,
"see_practs_information": 1,
"text_reminders": 1,
"use_records": 1,
"session_cancel": 1,
"ace": 1,
"hide_costs": 1,
"username": "jane.doe",
"email": "jane.doe@example.com"
}
]
} Retrieve a client
Parameters
| Parameter | In | Description |
|---|---|---|
id | path | The record's id. |
Returns
One client record, or 404 not_found when no record with that id exists on your account.
Request
curl "https://www.bizstim.com/api/v1/clients/42" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Accept: application/json"<?php
$ch = curl_init('https://www.bizstim.com/api/v1/clients/42');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-KEY: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch('https://www.bizstim.com/api/v1/clients/42', {
headers: { 'X-API-KEY': 'YOUR_API_KEY', 'Accept': 'application/json' }
});
const data = await response.json();Response
{
"object": "client",
"id": 42,
"first_name": "Jane",
"last_name": "Doe",
"address1": "12 Main Street",
"address2": "Suite 4",
"city": "Toronto",
"state": "ON",
"zipcode": "M5V 2T6",
"country": "Canada",
"p_phone": "416-555-0100",
"s_phone": "416-555-0101",
"text_phone": "416-555-0102",
"dob": "1990-05-20",
"status": "active",
"inactive_date": "2026-01-15",
"inactive_reason": "An example reason.",
"start_date": "2026-01-15",
"notes": "Prefers afternoon appointments.",
"timezone": "America/Toronto",
"send_welcome_message": 1,
"send_lesson_reminders": 1,
"add_session": 1,
"see_practs_information": 1,
"text_reminders": 1,
"use_records": 1,
"session_cancel": 1,
"ace": 1,
"hide_costs": 1,
"username": "jane.doe",
"email": "jane.doe@example.com"
} Create a client
Request body
A JSON object (Content-Type: application/json) with these fields.
| Field | Type | Required | Description |
|---|---|---|---|
first_name | string, up to 50 characters | yes | First name. |
last_name | string, up to 50 characters | yes | Last name. |
status | string | yes | "active", "inactive" or "prospect". Only active clients can log in. |
country | string, up to 50 characters | yes | Country. |
state | string, up to 50 characters | yes | State or province. |
city | string, up to 50 characters | no | City. |
address1 | string, up to 100 characters | no | Street address. |
address2 | string, up to 100 characters | no | Apartment, suite or unit. |
zipcode | string, up to 25 characters | no | Zip or postal code. |
p_phone | string, up to 100 characters | no | Primary phone. |
s_phone | string, up to 100 characters | no | Secondary phone. |
text_phone | string, up to 510 characters | no | Mobile number(s) for text messages, with the country code, comma separated. Spaces, brackets and dashes are removed. |
email | string, up to 510 characters | no | One e-mail address, or several separated by commas (e.g. the client and a parent). Stored in lower case. |
dob | date, YYYY-MM-DD | no | Date of birth. |
start_date | date, YYYY-MM-DD | no | First day as a client (default: today, account time zone). |
inactive_date | date, YYYY-MM-DD | no | The client is set to inactive automatically on this date. |
notes | string | no | Notes shown on the client page (HTML allowed). |
timezone | string | no | A time zone from GET /api/v1/timezones (default: the account time zone). |
username | string, 4 to 50 characters | no | Login name, stored in lower case; needs password. Without one the client has no login (see send_welcome_message). |
password | string, 4 to 72 characters | with username | Login password. Write only: it is never returned. |
send_welcome_message | boolean | no | true e-mails the welcome message with the login details, as the app's add page does: for an active client with an email address only (an active client without one answers 400). Without a username, one and a password are created and the e-mail carries them. Default false. |
send_lesson_reminders | boolean | no | E-mail session reminders. Default for this and the permissions below: your client permission profile (Settings > Permissions). |
text_reminders | boolean | no | Text message reminders (sessions, invoices, tasks). |
add_session | boolean | no | May add sessions while logged in (added as pending). |
session_cancel | boolean | no | May cancel sessions. |
see_practs_information | boolean | no | May see the practitioners' names and information. |
ace | boolean | no | Exception to the available credit filter. |
hide_costs | boolean | no | Hide service costs from the client. |
use_records | integer, 0 to 3 | no | Records manager access: 0 none, 1 view, 2 view, add and edit, 3 also delete. |
Returns
201 with the new client record. Assigned practitioners, services, agents and tags are set in the app. 400 invalid_request names the field to fix; 409 conflict when the username is already taken (usernames are unique across every account; the check ignores case).
Request
curl -X POST "https://www.bizstim.com/api/v1/clients" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Jane",
"last_name": "Doe",
"status": "active",
"country": "Canada",
"state": "Ontario",
"city": "Toronto",
"email": "jane.doe@example.com"
}'<?php
$ch = curl_init('https://www.bizstim.com/api/v1/clients');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => '{
"first_name": "Jane",
"last_name": "Doe",
"status": "active",
"country": "Canada",
"state": "Ontario",
"city": "Toronto",
"email": "jane.doe@example.com"
}',
CURLOPT_HTTPHEADER => ['X-API-KEY: YOUR_API_KEY', 'Accept: application/json', 'Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch('https://www.bizstim.com/api/v1/clients', {
method: 'POST',
headers: { 'X-API-KEY': 'YOUR_API_KEY', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({
"first_name": "Jane",
"last_name": "Doe",
"status": "active",
"country": "Canada",
"state": "Ontario",
"city": "Toronto",
"email": "jane.doe@example.com"
})
});
const data = await response.json();Response (201)
{
"object": "client",
"id": 42,
"first_name": "Jane",
"last_name": "Doe",
"address1": "12 Main Street",
"address2": "Suite 4",
"city": "Toronto",
"state": "ON",
"zipcode": "M5V 2T6",
"country": "Canada",
"p_phone": "416-555-0100",
"s_phone": "416-555-0101",
"text_phone": "416-555-0102",
"dob": "1990-05-20",
"status": "active",
"inactive_date": "2026-01-15",
"inactive_reason": "An example reason.",
"start_date": "2026-01-15",
"notes": "Prefers afternoon appointments.",
"timezone": "America/Toronto",
"send_welcome_message": 1,
"send_lesson_reminders": 1,
"add_session": 1,
"see_practs_information": 1,
"text_reminders": 1,
"use_records": 1,
"session_cancel": 1,
"ace": 1,
"hide_costs": 1,
"username": "jane.doe",
"email": "jane.doe@example.com"
} Update a client
Parameters
| Parameter | In | Description |
|---|---|---|
id | path | The record's id. |
Request body
A JSON object (Content-Type: application/json) with these fields.
| Field | Type | Required | Description |
|---|---|---|---|
first_name | string, up to 50 characters | no | First name (cannot be emptied). |
last_name | string, up to 50 characters | no | Last name (cannot be emptied). |
status | string | no | "active", "inactive" or "prospect", as the client page's Status control: inactive turns e-mail and text reminders off and records the date, the reason and who made the change; active or prospect clears that record. |
inactive_reason | string | no | Why the client is inactive (HTML allowed). Kept while the status is inactive; cleared otherwise. |
country | string, up to 50 characters | no | Country. A client needs one: an update of a client that has none on file must send it. |
state | string, up to 50 characters | no | State or province, needed as country. |
city | string, up to 50 characters | no | City. |
address1 | string, up to 100 characters | no | Street address. |
address2 | string, up to 100 characters | no | Apartment, suite or unit. |
zipcode | string, up to 25 characters | no | Zip or postal code. |
p_phone | string, up to 100 characters | no | Primary phone. |
s_phone | string, up to 100 characters | no | Secondary phone. |
text_phone | string, up to 510 characters | no | Mobile number(s) for text messages, as on create. |
email | string, up to 510 characters | no | One e-mail address or several, comma separated; "" removes them. |
dob | date, YYYY-MM-DD | no | Date of birth; "" clears it. |
start_date | date, YYYY-MM-DD | no | First day as a client; "" sets today. |
inactive_date | date, YYYY-MM-DD | no | Automatic inactive date; "" clears it. |
notes | string | no | Notes (HTML allowed), replaced as sent. |
timezone | string | no | A time zone from GET /api/v1/timezones. |
username | string, 4 to 50 characters | no | Login name, stored in lower case. A client without a password needs password in the same request. "" removes the login (username and password). |
password | string, 4 to 72 characters | no | New login password (needs a username). Write only. |
send_welcome_message | boolean | no | Stored setting only: an update never sends the welcome e-mail. |
send_lesson_reminders | boolean | no | E-mail session reminders (always off for an inactive client). |
text_reminders | boolean | no | Text message reminders (always off for an inactive client). |
add_session | boolean | no | May add sessions while logged in. |
session_cancel | boolean | no | May cancel sessions. |
see_practs_information | boolean | no | May see the practitioners' names and information. |
ace | boolean | no | Exception to the available credit filter. |
hide_costs | boolean | no | Hide service costs from the client. |
use_records | integer, 0 to 3 | no | Records manager access, as on create. |
Returns
200 with the updated client record. Fields left out keep their values (assigned practitioners, services, agents, tags and availability, which the API does not change, are kept too). 400 invalid_request names the field to fix; 404 not_found; 409 conflict when the username is already taken (usernames are unique across every account; the check ignores case) or the app refused the change.
Request
curl -X PATCH "https://www.bizstim.com/api/v1/clients/42" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"status": "inactive",
"inactive_reason": "Moved away.",
"p_phone": "416-555-0100"
}'<?php
$ch = curl_init('https://www.bizstim.com/api/v1/clients/42');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_POSTFIELDS => '{
"status": "inactive",
"inactive_reason": "Moved away.",
"p_phone": "416-555-0100"
}',
CURLOPT_HTTPHEADER => ['X-API-KEY: YOUR_API_KEY', 'Accept: application/json', 'Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch('https://www.bizstim.com/api/v1/clients/42', {
method: 'PATCH',
headers: { 'X-API-KEY': 'YOUR_API_KEY', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({
"status": "inactive",
"inactive_reason": "Moved away.",
"p_phone": "416-555-0100"
})
});
const data = await response.json();Response
{
"object": "client",
"id": 42,
"first_name": "Jane",
"last_name": "Doe",
"address1": "12 Main Street",
"address2": "Suite 4",
"city": "Toronto",
"state": "ON",
"zipcode": "M5V 2T6",
"country": "Canada",
"p_phone": "416-555-0100",
"s_phone": "416-555-0101",
"text_phone": "416-555-0102",
"dob": "1990-05-20",
"status": "active",
"inactive_date": "2026-01-15",
"inactive_reason": "An example reason.",
"start_date": "2026-01-15",
"notes": "Prefers afternoon appointments.",
"timezone": "America/Toronto",
"send_welcome_message": 1,
"send_lesson_reminders": 1,
"add_session": 1,
"see_practs_information": 1,
"text_reminders": 1,
"use_records": 1,
"session_cancel": 1,
"ace": 1,
"hide_costs": 1,
"username": "jane.doe",
"email": "jane.doe@example.com"
} Delete a client
Parameters
| Parameter | In | Description |
|---|---|---|
id | path | The record's id. |
Returns
200 with {"id", "object": "client", "deleted": true}: the client, the login and the client's settings, notes, tags, assignments and invoices are removed for good. 404 not_found; 409 conflict when the client has sessions (deleted sessions included), payments, records or a paid Smart Learn subscription on file: set the status to inactive instead.
Request
curl -X DELETE "https://www.bizstim.com/api/v1/clients/42" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Accept: application/json"<?php
$ch = curl_init('https://www.bizstim.com/api/v1/clients/42');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['X-API-KEY: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch('https://www.bizstim.com/api/v1/clients/42', {
method: 'DELETE',
headers: { 'X-API-KEY': 'YOUR_API_KEY', 'Accept': 'application/json' }
});
const data = await response.json();Response
{
"id": 42,
"object": "client",
"deleted": true
}