- Query Efficiency: Be considerate of system resources and avoid making unoptimized requests. We reserve the right to terminate API access if your average request latency exceeds 1 second over the course of 5 minutes.
- User-Agent Header: All API calls must include a valid
User-Agentheader. Requests without it will be rejected.”
Server
https://api.splose.com/v1https://api-uk.splose.com/v1(UK users)
Authentication
API Key Authentication
The splose API employs API keys for request authentication. Workspace owners can apply for and manage API keys through the splose dashboard. It’s crucial to safeguard the API key, as it grants the same permissions as the associated user.Bearer Authentication
Authentication for API access is achieved via Bearer Authentication. Include the API key in the request header using the format:Authorization: Bearer your_api_key.
Secure Communication
All API requests must be conducted over HTTPS. Requests made over plain HTTP will not succeed. Additionally, unauthenticated API requests will result in failure.Rate limit
There are limits to the number of API calls that your application can make with one API key.- Minute Limit: 60 calls per minute
Error
splose uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with splose’s servers. Error types:- 400 - Bad request: the request failed due to missing or invalid parameters.
- 401 - Unauthorized: No valid API key provided.
- 403 - Forbidden: The request is blocked by WAF.
- 404 - Not Found: The requested resource doesn’t exist.
- 429 - Too Many Requests: Too many requests hit the API too quickly.
- 500 - Internal Server Error : Something went wrong on splose’s end.
id returns it, with archived: true where the response has that field.
Datetime
All datetime values provided in request parameters and responses are in Coordinated Universal Time (UTC). The accepted datetime formats are outlined below:- 2023-07-01
- 2023-07-01T00:00:00Z
- 2023-07-01T00:00:00.000Z
Z in a datetime. A datetime without one isn’t guaranteed to be read as UTC.
Pagination
Pagination for Multiple Objects
For list endpoints that acceptid_gt and id_lt, each response holds up to 100 objects, ordered by id.
When a page holds 100 objects, the response includes a links field with URLs for the next and previous pages. A page with fewer than 100 objects is the last page, and has no links.
Manual Positioning
You have the option to manually specify theid_gt or id_lt value as a request parameter. This allows you to retrieve objects starting from a specific position. If neither of these values is provided, the initial page of objects will be returned by default.
-
id_gt: Request for next page of objects with id greater than the specified value. -
id_lt: Request for previous page of objects with id less than the specified value.
Realtime feed
Retrieving the complete dataset on every sync isn’t efficient for large workspaces. Instead, retrieve everything once, then on each sync request only the objects updated since the previous one, and replace your copy of each object byid.
-
update_gt: Request for objects updated after the specified datetime. -
update_lt: Request for objects updated before the specified datetime.
Syncing changes
On each sync:-
Pass
include_archived=truewithupdate_gt. Archived objects are left out by default, so without it an object archived since your previous sync never comes through. An archived object is marked byarchived: true, or byisArchivedon invoices and adeletedAtvalue on credit notes and support items. -
Set
update_gta few minutes before the time your previous sync started, not to the latestupdatedAtyou received.update_gtexcludes the value you pass, andupdatedAtis stored to the second, so an exact value can skip objects updated in the same second or while your previous sync was paging. Objects in the overlap come back twice; replace them byid. -
Keep the same
update_gtand followlinks.nextPageuntil a page holds fewer than 100 objects.
status set to Cancelled.
Changes that don’t update updatedAt
updatedAt changes when the object itself changes. It doesn’t change when only nested data in the response changes:
-
Appointments: a patient’s
statusinappointmentPatients, such as arrived, did not arrive, completed, or one patient cancelled from a group appointment. Retrieve these withstatus_update_gt, which, unlikeupdate_gt, includes the value you pass. For a cancellation,statusUpdatedAtis the cancellation time recorded in splose, which can be earlier than when the cancellation was entered. A cancellation backdated before your previous sync doesn’t come back fromstatus_update_gt. Retrieve appointments in full periodically to pick these up. -
Patients: values in
customFields. -
Payments and credit notes: entries in
creditAllocations.
updatedAt at the moment, so update_gt doesn’t return them. Until they do, retrieve these endpoints in full periodically.
Known issues
-
waitlistsandscreenersignoreinclude_archivedand always return archived entries. Usearchivedin the response to tell them apart. -
waitlists: theisActivefilter is inverted.isActive=truereturns closed entries andisActive=falsereturns open ones. Usearchivedin the response instead. -
custom-fieldandpayment-methodsdon’t supportupdate_gtorupdate_lt. Retrieve them in full. -
paymentsresponses don’t includeupdatedAt. -
casesresponses don’t mark archived cases. Withinclude_archived=true, archived and active cases look the same. -
Requesting a single object by an
idthat doesn’t exist returns 200 with a zero-length body instead of 404. Treat an empty response as not found; it will become a 404.
Changelog
-
2026-07-28
- add
meendpoint. - add
idsquery parameter onpatientendpoint to filter patients by id.
- add
-
2026-07-24
- add
cancellation-reasonendpoint. - add
free-slotsendpoint to search for bookable free slots. - add cancel endpoint for a single appointment.
- add cancel endpoint for a patient’s participation in a group appointment.
- add arrival endpoint to mark a single appointment’s patient as arrived.
- add arrival endpoint to mark a patient’s arrival in a group appointment.
- add
-
2026-06-29
- add
practitionerIdquery parameter onappointmentendpoint to filter appointments by practitionerId. - add
practitionerIdquery parameter onbusy-timeendpoint to filter busy times by practitionerId.
- add
-
2026-04-22
- add
connectionsinto practitioner response. - add
associatedServiceIdsinto location response.
- add
-
2026-03-27
- add
busy-timeendpoint. - add
busy-time-typeendpoint. - deprecate
busyTimePractitionerIdsandisUnavailableBlockonappointmentendpoint. - migration: phasing out “busy times” from the
appointmentendpoint to a dedicatedbusy-timeendpoint.
- add
-
2025-06-20
- add
credit-noteendpoint.
- add
-
2025-05-12
- Breaking change: move
caseIdintoappointmentPatientfield forappointmentresponse.
- Breaking change: move
-
2025-03-13:
- add
custom-filedendpoint. - add endpoint to update
patient. - add endpoint to update custom field in
patient.
- add
-
2025-02-14:
- add endpoint to create
contact. - add
emailfield to practitioner response.
- add endpoint to create
-
2025-01-31:
- add endpoint to create
patient. - Add endpoint to create
appoitment.
- add endpoint to create
-
2024-12-13:
- add endpoint to
patientto upload file for patient. - allow update more fields for appointment.
- add endpoint to
-
2024-11-27:
- add
nameto contact response.
- add
-
2024-11-22:
- add
cancellationRateto appointment response.
- add
-
2024-09-30:
- add
contactendpoint. - add
invoiceRecipientIdto patient response.
- add
-
2024-09-03:
- add PUT method to
appointmentandsupport-itemendpoints. - add
status_update_ltandstatus_update_gtparameter toappointmentendpoint.
- add PUT method to
-
2024-06-25:
- add
case,patient-form,screenerandwaitlistendpoints. - add
customFieldsto patient response. - add
statusUpdatedAtto appointment response.
- add
-
2024-04-29: add
payment-methodandpaymentendpoints. -
2024-02-28: add
availabilityendpoint.