Find or Create Contact

Overview

Registers a customer contact and optionally creates a service address. Returns id (use as contactId) and addressId for booking and timeslot requests. Call this endpoint before POST /partners/bookings.

Endpoint

POST /partners/contacts

Authentication

Requires a valid API Key with the partner_contacts_read permission.

Request Headers

Header	Required	Value
`x-api-key`	Yes	Your partner API key
`Content-Type`	Yes	`application/json`

Request Body

Minimal (contact only):

{
  "phone": "+966500000000",
  "name": "Ahmed Ali"
}

With address (recommended before booking):

{
  "phone": "+966500000000",
  "name": "Ahmed Ali",
  "latitude": "24.7136",
  "longitude": "46.6753",
  "cityName": "Riyadh",
  "districtName": "Al Olaya",
  "streetName": "King Fahd Road"
}

Field Reference

Field	Type	Required	Description
`phone`	string	Yes	Saudi phone number in international format (e.g. `+966500000000`). No spaces.
`name`	string	Yes	Customer full name.
`latitude`	string	No	Address latitude (e.g. `"24.7136"`). Must be sent together with `longitude`.
`longitude`	string	No	Address longitude (e.g. `"46.6753"`). Must be sent together with `latitude`.
`cityName`	string	No	City name for the service address.
`districtName`	string	No	District / neighborhood name for the service address.
`streetName`	string	No	Street name for the service address.

utmSource is assigned automatically from your partner account name — do not send it in the request body.

Example Request

curl -X POST "https://apiv3.thecleanlife.dev/v1/partners/contacts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+966500000000",
    "name": "Ahmed Ali",
    "latitude": "24.7136",
    "longitude": "46.6753",
    "cityName": "Riyadh",
    "districtName": "Al Olaya",
    "streetName": "King Fahd Road"
  }'

Success Response

HTTP Status: 200 OK Contact without address:

{
  "success": true,
  "data": {
    "id": "aaaaaaaa-0000-0000-0000-000000000001",
    "name": "Ahmed Ali",
    "phone": "+966500000000",
    "addressId": null,
    "isNewContact": true
  }
}

Contact with address created:

{
  "success": true,
  "data": {
    "id": "bbbbbbbb-0000-0000-0000-000000000002",
    "name": "Ahmed Ali",
    "phone": "+966500000000",
    "addressId": "cccccccc-0000-0000-0000-000000000003",
    "isNewContact": true
  }
}

Response Fields

Field	Type	Description
`id`	UUID	Contact ID — pass as `contactId` in `POST /partners/bookings`
`name`	string	Contact name
`phone`	string	Normalized phone number
`addressId`	UUID \| null	Service address ID when an address was created or matched; `null` if no address fields were sent
`isNewContact`	boolean	`true` when a new contact record was created

Error Responses

HTTP Status	Code	Description
`400`	`VALIDATION_ERROR`	Invalid phone format, invalid coordinates, or missing required fields
`401`	`UNAUTHORIZED`	Invalid or missing API key
`403`	`FORBIDDEN`	Missing `partner_contacts_read` permission

Notes

Store the returned id as contactId and addressId in your booking request.
When you send latitude and longitude together with address text fields, use the returned addressId directly in POST /partners/bookings and GET /partners/timeslots/available.
latitude and longitude must both be provided to set coordinates; sending only one is ignored for location matching.
Phone numbers are normalized server-side — always use the international +966 format.

POST /partners/bookings — Create a booking using the returned id as contactId and addressId
GET /partners/services?addressId=... — List services available at the returned address
GET /partners/timeslots/available — Check timeslots using addressId

Contacts

Bookings

Service Catalog

Overview

Endpoint

Authentication

Request Headers

Request Body

Field Reference

Example Request

Success Response

Response Fields

Error Responses

Notes

​Overview

​Endpoint

​Authentication

​Request Headers

​Request Body

​Field Reference

​Example Request

​Success Response

​Response Fields

​Error Responses

​Notes

​Related Endpoints

Overview

Endpoint

Authentication

Request Headers

Request Body

Field Reference

Example Request

Success Response

Response Fields

Error Responses

Notes

Related Endpoints