Skip to main content
The splose API follows a REST architectural style, offering JSON-encoded responses, standard HTTP response codes, easily understandable resource-oriented URLs, and robust authentication mechanisms. When making requests, please note the following:
  • 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-Agent header. Requests without it will be rejected.”

Server

  • https://api.splose.com/v1
  • https://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.
Requesting a single archived object by its 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
Always include the 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 accept id_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 the id_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 by id.
  • 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:
  1. Pass include_archived=true with update_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 by archived: true, or by isArchived on invoices and a deletedAt value on credit notes and support items.
  2. Set update_gt a few minutes before the time your previous sync started, not to the latest updatedAt you received. update_gt excludes the value you pass, and updatedAt is 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 by id.
  3. Keep the same update_gt and follow links.nextPage until a page holds fewer than 100 objects.
A cancelled appointment is not archived. It is returned by default, with each patient’s 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 status in appointmentPatients, such as arrived, did not arrive, completed, or one patient cancelled from a group appointment. Retrieve these with status_update_gt, which, unlike update_gt, includes the value you pass. For a cancellation, statusUpdatedAt is 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 from status_update_gt. Retrieve appointments in full periodically to pick these up.
  • Patients: values in customFields.
  • Payments and credit notes: entries in creditAllocations.
Some records are deleted rather than archived, such as a patient removed from a group appointment. A deletion doesn’t appear in any later response. The following changes also don’t update updatedAt at the moment, so update_gt doesn’t return them. Until they do, retrieve these endpoints in full periodically.

Known issues

  • waitlists and screeners ignore include_archived and always return archived entries. Use archived in the response to tell them apart.
  • waitlists: the isActive filter is inverted. isActive=true returns closed entries and isActive=false returns open ones. Use archived in the response instead.
  • custom-field and payment-methods don’t support update_gt or update_lt. Retrieve them in full.
  • payments responses don’t include updatedAt.
  • cases responses don’t mark archived cases. With include_archived=true, archived and active cases look the same.
  • Requesting a single object by an id that 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 me endpoint.
    • add ids query parameter on patient endpoint to filter patients by id.
  • 2026-07-24
    • add cancellation-reason endpoint.
    • add free-slots endpoint 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.
  • 2026-06-29
    • add practitionerId query parameter on appointment endpoint to filter appointments by practitionerId.
    • add practitionerId query parameter on busy-time endpoint to filter busy times by practitionerId.
  • 2026-04-22
    • add connections into practitioner response.
    • add associatedServiceIds into location response.
  • 2026-03-27
    • add busy-time endpoint.
    • add busy-time-type endpoint.
    • deprecate busyTimePractitionerIds and isUnavailableBlock on appointment endpoint.
    • migration: phasing out “busy times” from the appointment endpoint to a dedicated busy-time endpoint.
  • 2025-06-20
    • add credit-note endpoint.
  • 2025-05-12
    • Breaking change: move caseId into appointmentPatient field for appointment response.
  • 2025-03-13:
    • add custom-filed endpoint.
    • add endpoint to update patient.
    • add endpoint to update custom field in patient.
  • 2025-02-14:
    • add endpoint to create contact.
    • add email field to practitioner response.
  • 2025-01-31:
    • add endpoint to create patient.
    • Add endpoint to create appoitment.
  • 2024-12-13:
    • add endpoint to patient to upload file for patient.
    • allow update more fields for appointment.
  • 2024-11-27:
    • add name to contact response.
  • 2024-11-22:
    • add cancellationRate to appointment response.
  • 2024-09-30:
    • add contact endpoint.
    • add invoiceRecipientId to patient response.
  • 2024-09-03:
    • add PUT method to appointment and support-item endpoints.
    • add status_update_lt and status_update_gt parameter to appointment endpoint.
  • 2024-06-25:
    • add case, patient-form, screener and waitlist endpoints.
    • add customFields to patient response.
    • add statusUpdatedAt to appointment response.
  • 2024-04-29: add payment-method and payment endpoints.
  • 2024-02-28: add availability endpoint.