Request Models

Complete reference for all request bodies used in the Partner API.

Create Booking

Used by: POST /partners/bookings

Field	Type	Required	Validation	Description
`contactId`	UUID	Yes	Valid UUID v4	Customer contact ID (from `POST /partners/contacts`, field `id`)
`addressId`	string	Yes	Non-empty	Service address ID (from `POST /partners/contacts`, field `addressId`)
`serviceId`	UUID	Yes	Valid UUID v4	Service ID from `GET /partners/services?addressId=...`. Category is resolved automatically.
`timeslot`	object	Yes	Valid object	Appointment timeslot
`timeslot.startAt`	string	Yes	Non-empty	Start time (`HH:MM` or `HH:MM:SS`) in Riyadh local time
`timeslot.endAt`	string	Yes	Non-empty	End time (`HH:MM` or `HH:MM:SS`) in Riyadh local time
`date`	string	Yes	ISO 8601 date	Service date (`YYYY-MM-DD`)
`externalReference`	string	No	Max 150 chars	Your unique reference ID for this booking

Used by: POST /partners/contacts

Field	Type	Required	Validation	Description
`phone`	string	Yes	Saudi phone number, no spaces	Customer phone (e.g. `+966500000000`)
`name`	string	Yes	Non-empty	Customer full name
`latitude`	string	No	Valid latitude	Address latitude; must be sent with `longitude`
`longitude`	string	No	Valid longitude	Address longitude; must be sent with `latitude`
`cityName`	string	No	Non-empty when provided	City name for the service address
`districtName`	string	No	Non-empty when provided	District / neighborhood name
`streetName`	string	No	Non-empty when provided	Street name for the service address

utmSource is not accepted in the request body. It is assigned automatically from your partner account name.

Used by: PATCH /partners/bookings/:bookingId/cancel

Field	Type	Required	Validation	Description
`reasonId`	UUID	Yes	Valid UUID v4	Cancellation reason ID from `GET /partners/bookings/cancellation-reasons`
`notes`	string	No	—	Notes about the cancellation

Used by: POST /partners/bookings/:bookingId/confirm-payment All fields are optional.

Field	Type	Required	Validation	Description
`paymentReference`	string	No	Max: 255 chars	Your payment transaction ID for reconciliation

Used by: GET /partners/services

Parameter	Type	Required	Validation	Description
`addressId`	UUID	Yes	Valid UUID v4	Service address ID from `POST /partners/contacts`
`page`	integer	No	Min: 1; default: 1	Page number (categories)
`limit`	integer	No	Min: 1; Max: 100; default: 20	Categories per page

Used by other list endpoints (e.g. booking history).

Parameter	Type	Required	Validation	Description
`page`	integer	No	Min: 1; default: 1	Page number
`limit`	integer	No	Min: 1; Max: 100; default: 20	Results per page
`sortBy`	string	No	—	Field to sort by
`sortOrder`	string	No	`ASC`, `DESC`, `asc`, `desc`	Sort direction

Used by: GET /partners/timeslots/available

Parameter	Type	Required	Validation	Description
`addressId`	UUID	Yes	Valid UUID v4	Customer’s service address ID
`serviceId`	UUID	Yes	Valid UUID v4	Service ID from the catalog
`date`	string	Yes	ISO 8601 date	Desired service date