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

Locations

The places sessions happen, with their contact details and the practitioners who work there.

The location object

Every location record carries these fields in this order, after object, which is always "location".

FieldTypeDescription
idinteger
location_statusinteger1 = active, 0 = inactive. Only the Smart Learn location is ever inactive, while the Smart Learn module is off. Deleted locations are not returned.
location_namestring, up to 255 characters
location_addressstring, up to 100 characters, nullable
location_zipcodestring, up to 25 characters, nullable
location_citystring, up to 50 characters, nullable
location_statestring, up to 50 characters, nullableLower case when the location was created; an update stores it as sent.
location_countrystring, up to 50 characters, nullableLower case when the location was created; an update stores it as sent.
location_p_phonestring, up to 25 characters, nullable
location_s_phonestring, up to 25 characters, nullable
location_emailstring, up to 100 characters, nullableLower case.
online_bookinginteger1 = clients can choose it on the online booking page, 0 = not offered there.
practstextComma-separated ids of the practitioners clients can book at this location online (see Practitioners); empty when none.

Example

{
    "object": "location",
    "id": 42,
    "location_status": 1,
    "location_name": "Example name",
    "location_address": "12 Main Street",
    "location_zipcode": "M5V 2T6",
    "location_city": "Toronto",
    "location_state": "ON",
    "location_country": "Canada",
    "location_p_phone": "416-555-0100",
    "location_s_phone": "416-555-0100",
    "location_email": "office@example.com",
    "online_booking": 1,
    "practs": "7,8"
}

List locations

GET /api/v1/locations

Parameters

ParameterInDescription
limitqueryRecords per page, 1 to 1000 (default 100).
offsetqueryRecords to skip (default 0).

Returns

A list envelope of location records (see Pagination).

Request

curl "https://www.bizstim.com/api/v1/locations" \
  -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": "location",
            "id": 42,
            "location_status": 1,
            "location_name": "Example name",
            "location_address": "12 Main Street",
            "location_zipcode": "M5V 2T6",
            "location_city": "Toronto",
            "location_state": "ON",
            "location_country": "Canada",
            "location_p_phone": "416-555-0100",
            "location_s_phone": "416-555-0100",
            "location_email": "office@example.com",
            "online_booking": 1,
            "practs": "7,8"
        },
        {
            "object": "location",
            "id": 43,
            "location_status": 1,
            "location_name": "Example name",
            "location_address": "12 Main Street",
            "location_zipcode": "M5V 2T6",
            "location_city": "Toronto",
            "location_state": "ON",
            "location_country": "Canada",
            "location_p_phone": "416-555-0100",
            "location_s_phone": "416-555-0100",
            "location_email": "office@example.com",
            "online_booking": 1,
            "practs": "7,8"
        }
    ]
}

Retrieve a location

GET /api/v1/locations/{id}

Parameters

ParameterInDescription
idpathThe record's id.

Returns

One location record, or 404 not_found when no record with that id exists on your account.

Request

curl "https://www.bizstim.com/api/v1/locations/42" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
    "object": "location",
    "id": 42,
    "location_status": 1,
    "location_name": "Example name",
    "location_address": "12 Main Street",
    "location_zipcode": "M5V 2T6",
    "location_city": "Toronto",
    "location_state": "ON",
    "location_country": "Canada",
    "location_p_phone": "416-555-0100",
    "location_s_phone": "416-555-0100",
    "location_email": "office@example.com",
    "online_booking": 1,
    "practs": "7,8"
}

Create a location

POST /api/v1/locations

Request body

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

FieldTypeRequiredDescription
location_namestring, up to 255yesThe name shown wherever a session is booked, e.g. "Online" or "Main office". HTML is cleaned on save.
location_addressstring, up to 100noStreet address.
location_zipcodestring, up to 25noZip or postal code.
location_citystring, up to 50noCity.
location_statestring, up to 50noState or province, stored in lower case on create (as the app's add page does).
location_countrystring, up to 50noCountry, stored in lower case on create (as the app's add page does).
location_p_phonestring, up to 25noPrimary phone.
location_s_phonestring, up to 25noSecondary phone.
location_emailstring, one e-mail address, up to 100 charactersnoStored in lower case.
online_bookingbooleannoClients can choose it on the online booking page. Default false.
practsarray of integersnoThe practitioners who work here: active practitioners with online booking on (the app's location form lists the same). The comma-separated string the record returns is accepted too. Default none.

Returns

201 with the new location record (location_status 1, active). Only location_name is required: a location for online or in-home sessions needs no address. 400 invalid_request names the field to fix.

Request

curl -X POST "https://www.bizstim.com/api/v1/locations" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "location_name": "Main office",
    "location_address": "12 Main St",
    "practs": [
        354
    ]
}'

Response (201)

{
    "object": "location",
    "id": 42,
    "location_status": 1,
    "location_name": "Example name",
    "location_address": "12 Main Street",
    "location_zipcode": "M5V 2T6",
    "location_city": "Toronto",
    "location_state": "ON",
    "location_country": "Canada",
    "location_p_phone": "416-555-0100",
    "location_s_phone": "416-555-0100",
    "location_email": "office@example.com",
    "online_booking": 1,
    "practs": "7,8"
}

Update a location

PATCH /api/v1/locations/{id}

Parameters

ParameterInDescription
idpathThe record's id.

Request body

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

FieldTypeRequiredDescription
location_namestring, up to 255noThe name (cannot be emptied).
location_addressstring, up to 100noStreet address ("" clears it).
location_zipcodestring, up to 25noZip or postal code.
location_citystring, up to 50noCity.
location_statestring, up to 50noState or province, stored as sent.
location_countrystring, up to 50noCountry, stored as sent.
location_p_phonestring, up to 25noPrimary phone.
location_s_phonestring, up to 25noSecondary phone.
location_emailstring, one e-mail address, up to 100 charactersnoStored in lower case ("" clears it).
online_bookingbooleannoClients can choose it on the online booking page.
practsarray of integersnoThe whole list of practitioners who work here ([] removes them all).

Returns

200 with the updated location record. Fields left out keep their values, the practitioners included; practs replaces the whole list (a practitioner already on the location may stay in it). location_status is read-only: use DELETE. 400 invalid_request names the field to fix; 404 not_found (deleted locations too); 409 conflict for the Smart Learn location.

Request

curl -X PATCH "https://www.bizstim.com/api/v1/locations/42" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "location_city": "Hamilton",
    "online_booking": true
}'

Response

{
    "object": "location",
    "id": 42,
    "location_status": 1,
    "location_name": "Example name",
    "location_address": "12 Main Street",
    "location_zipcode": "M5V 2T6",
    "location_city": "Toronto",
    "location_state": "ON",
    "location_country": "Canada",
    "location_p_phone": "416-555-0100",
    "location_s_phone": "416-555-0100",
    "location_email": "office@example.com",
    "online_booking": 1,
    "practs": "7,8"
}

Delete a location

DELETE /api/v1/locations/{id}

Parameters

ParameterInDescription
idpathThe record's id.

Returns

200 with {"id", "object": "location", "deleted": true}. As in the app, the location is marked deleted: sessions booked there keep it, and the API no longer returns it. 404 not_found; 409 conflict for the Smart Learn location.

Request

curl -X DELETE "https://www.bizstim.com/api/v1/locations/42" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

Response

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