Book an appointment. Creates the customer when one does not already match, assigns resources, and schedules reminders
https://app.softsolz.uk/api/v1/services/appointments/appointmentsRecent Requests
Kept only in this browserHeaders
AuthorizationstringrequiredBearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.
Idempotency-KeystringOptional idempotency key for safe retries.
Body Params
type_idintegerrequiredAppointment type to book.
starts_atstringrequiredStart of the appointment, in UTC.
timezonestringIANA timezone the booking was made in. Defaults to the workspace timezone.
customer_idintegerExisting customer to book for.
customerobjectCustomer details. When no matching customer exists one is created, matched on email then phone.
asset_idintegerThing the visit is about.
resource_idsarray of integersSpecific resources to assign. Omit to auto-assign a qualifying resource.
locationobjectOverrides the location derived from the type.
intake_dataobjectAnswers to the type intake fields.
custom_fieldsobjectYour own extra fields, keyed by the definitions in workspace settings.
titlestringShort label shown on the calendar.
notesstringInternal note recorded against the appointment.
Response
Response Body
idstringUnique identifier.public_refstringShort reference safe to show a customer.type_idstring | nullAppointment type this belongs to.plan_idstring | nullMulti-visit plan this belongs to, when part of one.stage_sequenceinteger | nullPosition within the plan stages, when part of one.customer_idstring | nullNull for group sessions, where people are listed as attendees instead.asset_idstring | nullThe thing the visit is about, for example a vehicle or a property.state_keystringCurrent workflow state.titlestring | nullShort label shown on the calendar.starts_atstringStart of the appointment, in UTC.ends_atstringEnd of the appointment, in UTC.window_ends_atstring | nullEnd of the arrival window when the type uses one.timezonestringIANA timezone, for example Europe/London.location_modestringWhere the appointment happens.locationobjectWhere the appointment happens.capacityintegerPlaces available. 1 is one-to-one; above 1 enables group booking.sourcestringHow the appointment was created.price_centsinteger | nullPrice in the smallest currency unit.currencystring | nullISO 4217 currency code.intake_dataobjectAnswers to the appointment type intake questions.custom_fieldsobjectYour own extra fields, keyed by the definitions in workspace settings.assignmentsarray of objectsResources working this appointment.attendeesarray of objectsPeople booked onto a group session.created_atstringWhen the record was created.updated_atstringRound-trip as expected_updated_at to guard against stale writes.Request
curl --request POST \ --url https://app.softsolz.uk/api/v1/services/appointments/appointments \ --header 'Authorization: Bearer sk_live_your_key' \ --header 'Content-Type: application/json' \ --data '{ "type_id": 7, "starts_at": "2027-03-01T10:00:00.000Z", "timezone": "Europe/London", "customer": { "display_name": "Priya Raman", "email": "priya@example.com" }, "location": { "line1": "14 Oak Street", "city": "Leeds" }}'Credentials
Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.
Response · 201
{ "data": { "id": "501", "public_ref": "AP-7F3K2M", "type_id": "7", "plan_id": "your-plan-id", "stage_sequence": 1, "customer_id": "your-customer-id", "asset_id": "your-asset-id", "state_key": "confirmed", "title": "your-title", "starts_at": "2027-03-01T10:00:00.000Z", "ends_at": "2027-03-01T11:00:00.000Z", "window_ends_at": "2026-01-01T09:00:00.000Z", "timezone": "Europe/London", "location_mode": "customer", "location": { "line1": "14 Oak Street", "city": "Leeds" }, "capacity": 1, "source": "api", "price_cents": 1, "currency": "your-currency", "intake_data": {}, "custom_fields": {}, "assignments": [ { "resource_id": 3, "role": "primary" } ], "attendees": [ {} ], "created_at": "2026-01-01T09:00:00.000Z", "updated_at": "2026-01-01T09:00:00.000Z" }}