Create Contact

Creates a new contact in the workspace — or updates an existing one if a contact with the same phone number already exists (see "Upsert behavior" below).

Validation: name and phoneNumber are required — both return a 400 if empty. phoneNumber is normalized to a consistent format server-side (the curl example below sends "966501234567" and gets back "+966501234567").

Upsert-by-phone-number behavior: this endpoint looks up an existing contact in the workspace with the exact same phone number.

If found: updates that contact's name, marks it isAnonymous = false, and applies the other fields from this request. It does not create a duplicate or return a 409 Conflict — a second POST with the same phone number silently becomes an update.

If not found: creates a brand-new contact.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Responses

🟢200OK

application/json

Returns the created (or updated, if the phone number already existed) contact — wrapped under an id key. Despite the key name, the value is the full contact object, not an ID string. This is a known quirk in the API (the server-side variable was named Id but actually holds the whole DTO).

Bodyapplication/json

curl --location 'https://api.voxa.sa/v1/contacts' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Ahmed Al-Otaibi", "phoneNumber": "966501234567", "email": "ahmed@example.com", "company": "Acme Co", "customFields": { "source": "landing-page" } }'

{ "id": { "workspaceId": "d307b8...............", "name": "Ahmed Noshy", "phoneNumber": "+966501234567", "contactType": 1, "email": "Noshy@Hatif.io", "company": "Hatif", "position": null, "customFields": { "source": "landing-page" }, "notes": [], "customProperties": [], "lastModificationTime": "2026-06-19T13:55:18.2983548+00:00", "lastModifierId": null, "creationTime": "2026-06-09T08:05:17.467676", "creatorId": null, "id": "3a21bd..............." } }

Create Contact

Request

Responses