Contacts - ThinnestAI

POST /api/v1/contacts
Authorization: Bearer ta_live_…
Content-Type: application/json

{
  "phone": "+91 98765 43210",
  "name": "Asha Rao",
  "email": "asha@example.com",
  "externalId": "LSQ-42",
  "tags": ["hot lead", "sky towers"],
  "language": "Hindi",
  "consent": { "status": "granted", "source": "99acres enquiry form, 17 Sep" }
}

{
  "id": "cust_9f2c1a44-…",
  "phone": "919876543210",
  "name": "Asha Rao",
  "email": "asha@example.com",
  "externalId": "LSQ-42",
  "tags": ["hot-lead", "sky-towers"],
  "language": "Hindi",
  "note": null,
  "consent": { "status": "granted", "source": "99acres enquiry form, 17 Sep", "recordedAt": "2026-09-17T09:40:00Z" },
  "source": "api",
  "acquiredFrom": null,
  "createdAt": "2026-09-17T09:40:00Z"
}

Endpoints

Method	Path	What
`GET`	`/contacts`	List, newest first. Filter with `tag`, `externalId` or `phone`
`POST`	`/contacts`	Create — or update the person already on that number
`GET`	`/contacts/{id}`	One contact
`PATCH`	`/contacts/{id}`	Change any subset of the fields
`DELETE`	`/contacts/{id}`	Erase them: the contact, their conversations and transcripts, their calls, any queued call and their campaign rows

A POST on a number you already have updates that person and answers 200; a new person answers 201. A CRM that syncs the same lead twice must not double your list, so the number is the identity.

Fields

string

required

Required on create. E.164 with or without the +; spaces are fine. Normalised the way the importer normalises, so +91 98765 43210 and 9876543210 are one person.

string | null

Up to 120 characters.

string | null

Lower-cased.

string | null

Your CRM’s id for this person, unique in your workspace. GET /contacts?externalId= finds them by it; the same id on a second person is a 409.

string[]

Up to 20, normalised the way the console normalises them: lower case, spaces to hyphens. Replaces the list.

string | null

Which language to write to them in — one the console offers — or null.

string | null

Free text, up to 2,000 characters.

{ "status": "granted" | "withdrawn" | "unknown", "source": "…" }.source is required for granted and withdrawn — where they agreed or refused, in a sentence. It is recorded with the time, because “where did they consent” is what a regulator asks and “the CRM said so” is not an answer. Sending a contact is not consent; only granted with a source is.A contact marked withdrawn is never rung, messaged or included in a campaign, whichever channel they said it on.

Responses

object

The contact. 201 for a new one, 200 for one the POST updated.

object

A field that does not follow the rules above.

object

Not one of your contacts.

object

Another contact already has that externalId (or, on a PATCH, that phone).

Place a call — a call to a number that is not yet a contact creates one, with the name and source you send.
Report an event — also creates the contact if needed, and can enrol them in a sequence.

​Endpoints

​Fields

​Responses

​Related

Endpoints

Fields

Responses

Related