Skip to main content

​
Overview

Returns a contactId for use when creating bookings. If a contact with the given phone number already exists, it is returned. Otherwise, a new contact is created automatically. 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

HeaderRequiredValue
x-api-keyYesYour partner API key
Content-TypeYesapplication/json

​
Request Body

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

​
Field Reference

FieldTypeRequiredDescription
phonestringYesSaudi phone number in international format (e.g. +966500000000). No spaces.
namestringYesCustomer full name. Used when creating a new contact.
utmSourcestringNoTracking source tag. Defaults to PARTNER.

​
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"
  }'

​
Success Response

HTTP Status: 200 OK Existing contact: 
{
  "success": true,
  "data": {
    "id": "aaaaaaaa-0000-0000-0000-000000000001",
    "name": "Ahmed Ali",
    "phone": "+966500000000",
    "isNewContact": false
  }
}
Newly created contact: 
{
  "success": true,
  "data": {
    "id": "bbbbbbbb-0000-0000-0000-000000000002",
    "name": "Ahmed Ali",
    "phone": "+966500000000",
    "isNewContact": true
  }
}

​
Response Fields

FieldTypeDescription
idUUIDThe contactId to pass when creating a booking
namestringContact name
phonestringNormalized phone number
isNewContactbooleantrue if a new contact was created; false if an existing one was returned

​
Error Responses

HTTP StatusCodeDescription
400VALIDATION_ERRORInvalid phone format or missing required fields
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENMissing partner_contacts_read permission

​
Notes

  • Store the returned id as contactId in your booking request.
  • Phone numbers are normalized server-side — always use the international +966 format.
  • You still need a separate addressId for the service location when creating a booking.
  • GET /partners/contacts/:contactId — Retrieve a contact by ID
  • POST /partners/bookings — Create a booking using the returned contactId