Skip to content
Try For Free
Bizstim
Free tools
Pricing Contact Log in
Try For Free Book Demo
Home / API Reference / Clients
Resource

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".

FieldTypeDescription
idinteger
first_namestring, up to 50 characters
last_namestring, up to 50 characters
address1string, up to 100 characters, nullable
address2string, up to 100 characters, nullable
citystring, up to 50 characters, nullable
statestring, up to 50 characters, nullable
zipcodestring, up to 25 characters, nullable
countrystring, up to 50 characters, nullable
p_phonestring, up to 100 characters, nullable
s_phonestring, up to 100 characters, nullable
text_phonestring, up to 510 characters, nullableMobile number(s) for text messages, with the country code, comma-separated.
dobstring, up to 10 charactersDate of birth, YYYY-MM-DD; empty when none.
statusstring, 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_datestring, up to 10 characters, nullableAn 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_reasontextWhy the client was set inactive (HTML). Cleared when the status changes to active or prospect.
start_datestring, up to 25 charactersFirst day as a client, YYYY-MM-DD. Defaults to the day the client was added (account time zone).
notestext, nullableNotes shown on the client page (HTML).
timezonestring, up to 256 charactersThe client's own time zone (see Timezones): the app uses it for the current date and time while they are logged in.
send_welcome_messageinteger1 = 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_remindersinteger1 = gets an e-mail reminder before each scheduled session, 0 = not.
add_sessioninteger1 = can add sessions while logged in (added as pending until confirmed; online booking is not affected), 0 = cannot.
see_practs_informationinteger1 = can see the names and information of their assigned practitioners while logged in, 0 = cannot.
text_remindersinteger1 = gets text (SMS) messages at text_phone (session reminders, invoices, tasks), 0 = not.
use_recordsintegerRecords manager: 0 = no access, 1 = view only, 2 = view, add and edit, 3 = view, add, edit and delete.
session_cancelinteger1 = can cancel sessions while logged in, 0 = cannot.
aceintegerAvailable 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_costsinteger1 = service costs are hidden from the client while logged in, 0 = shown.
usernamestring, up to 50 characters, nullableLogin name, lower case and unique across every account. Empty or null when the client has no login.
emailstring, up to 510 characters, nullableOne 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

GET /api/v1/clients

Parameters

ParameterInDescription
limitqueryRecords per page, 1 to 1000 (default 100).
offsetqueryRecords to skip (default 0).
emailqueryOnly clients whose login holds this e-mail address (exact match; a login may list several addresses).
usernamequeryOnly the client with this username (exact match).
first_namequeryOnly clients with this first name (exact match, combine with last_name).
last_namequeryOnly 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"

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

GET /api/v1/clients/{id}

Parameters

ParameterInDescription
idpathThe 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"

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

POST /api/v1/clients

Request body

A JSON object (Content-Type: application/json) with these fields.

FieldTypeRequiredDescription
first_namestring, up to 50 charactersyesFirst name.
last_namestring, up to 50 charactersyesLast name.
statusstringyes"active", "inactive" or "prospect". Only active clients can log in.
countrystring, up to 50 charactersyesCountry.
statestring, up to 50 charactersyesState or province.
citystring, up to 50 charactersnoCity.
address1string, up to 100 charactersnoStreet address.
address2string, up to 100 charactersnoApartment, suite or unit.
zipcodestring, up to 25 charactersnoZip or postal code.
p_phonestring, up to 100 charactersnoPrimary phone.
s_phonestring, up to 100 charactersnoSecondary phone.
text_phonestring, up to 510 charactersnoMobile number(s) for text messages, with the country code, comma separated. Spaces, brackets and dashes are removed.
emailstring, up to 510 charactersnoOne e-mail address, or several separated by commas (e.g. the client and a parent). Stored in lower case.
dobdate, YYYY-MM-DDnoDate of birth.
start_datedate, YYYY-MM-DDnoFirst day as a client (default: today, account time zone).
inactive_datedate, YYYY-MM-DDnoThe client is set to inactive automatically on this date.
notesstringnoNotes shown on the client page (HTML allowed).
timezonestringnoA time zone from GET /api/v1/timezones (default: the account time zone).
usernamestring, 4 to 50 charactersnoLogin name, stored in lower case; needs password. Without one the client has no login (see send_welcome_message).
passwordstring, 4 to 72 characterswith usernameLogin password. Write only: it is never returned.
send_welcome_messagebooleannotrue 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_remindersbooleannoE-mail session reminders. Default for this and the permissions below: your client permission profile (Settings > Permissions).
text_remindersbooleannoText message reminders (sessions, invoices, tasks).
add_sessionbooleannoMay add sessions while logged in (added as pending).
session_cancelbooleannoMay cancel sessions.
see_practs_informationbooleannoMay see the practitioners' names and information.
acebooleannoException to the available credit filter.
hide_costsbooleannoHide service costs from the client.
use_recordsinteger, 0 to 3noRecords 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"
}'

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

PATCH /api/v1/clients/{id}

Parameters

ParameterInDescription
idpathThe record's id.

Request body

A JSON object (Content-Type: application/json) with these fields.

FieldTypeRequiredDescription
first_namestring, up to 50 charactersnoFirst name (cannot be emptied).
last_namestring, up to 50 charactersnoLast name (cannot be emptied).
statusstringno"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_reasonstringnoWhy the client is inactive (HTML allowed). Kept while the status is inactive; cleared otherwise.
countrystring, up to 50 charactersnoCountry. A client needs one: an update of a client that has none on file must send it.
statestring, up to 50 charactersnoState or province, needed as country.
citystring, up to 50 charactersnoCity.
address1string, up to 100 charactersnoStreet address.
address2string, up to 100 charactersnoApartment, suite or unit.
zipcodestring, up to 25 charactersnoZip or postal code.
p_phonestring, up to 100 charactersnoPrimary phone.
s_phonestring, up to 100 charactersnoSecondary phone.
text_phonestring, up to 510 charactersnoMobile number(s) for text messages, as on create.
emailstring, up to 510 charactersnoOne e-mail address or several, comma separated; "" removes them.
dobdate, YYYY-MM-DDnoDate of birth; "" clears it.
start_datedate, YYYY-MM-DDnoFirst day as a client; "" sets today.
inactive_datedate, YYYY-MM-DDnoAutomatic inactive date; "" clears it.
notesstringnoNotes (HTML allowed), replaced as sent.
timezonestringnoA time zone from GET /api/v1/timezones.
usernamestring, 4 to 50 charactersnoLogin name, stored in lower case. A client without a password needs password in the same request. "" removes the login (username and password).
passwordstring, 4 to 72 charactersnoNew login password (needs a username). Write only.
send_welcome_messagebooleannoStored setting only: an update never sends the welcome e-mail.
send_lesson_remindersbooleannoE-mail session reminders (always off for an inactive client).
text_remindersbooleannoText message reminders (always off for an inactive client).
add_sessionbooleannoMay add sessions while logged in.
session_cancelbooleannoMay cancel sessions.
see_practs_informationbooleannoMay see the practitioners' names and information.
acebooleannoException to the available credit filter.
hide_costsbooleannoHide service costs from the client.
use_recordsinteger, 0 to 3noRecords 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"
}'

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

DELETE /api/v1/clients/{id}

Parameters

ParameterInDescription
idpathThe 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"

Response

{
    "id": 42,
    "object": "client",
    "deleted": true
}