Skip to main content
API Reference

Contacts

The person object — create, create-or-update (upsert), search, look up by your own id, update and delete contacts, the phone/email/WhatsApp uniqueness rule, consent flags, and the facts your agents remember about each contact.

Overview

A contact is one person you talk to — on a call, on WhatsApp, or by email. It is identified by a phone number, an email address or a WhatsApp business-scoped user id (BSUID), and optionally belongs to a company through company_id.

Deals, notes and tasks attach to a contact, and the timeline rolls up its activity.

Syncing contacts with another system? Use create-or-update to write, ?external_id= to look one up by your own id, ?updated_after= to read what changed, and the contact.* webhooks to hear about changes as they happen. The whole flow is in Connect your CRM.

Authentication

Authorization: Bearer cm_your_api_key
OperationScope
List, count, get, read memorycontacts:read
Create, update, delete, erase memorycontacts:write
Create-or-updatecontacts:write and contacts:read (it returns the contact it matched)

The contact object

{
  "id": "4411…",
  "tenant_id": "a0b1…",
  "company_id": "5c6d…",
  "phone": "+919876543210",
  "email": "[email protected]",
  "name": "Asha Menon",
  "external_ids": { "shopify": "gid://shopify/Customer/991" },
  "whatsapp_opt_in": true,
  "email_opt_in": false,
  "sms_opt_in": false,
  "consent_source": "checkout_form",
  "consent_updated_at": "2026-08-04T10:00:00Z",
  "whatsapp_bsuid": null,
  "whatsapp_parent_bsuid": null,
  "whatsapp_username": null,
  "lifecycle_stage": "customer",
  "lead_source": "web_form",
  "owner_user_id": null,
  "tags": ["vip", "renewal"],
  "metadata": null,
  "created_at": "2026-08-04T10:00:00Z",
  "updated_at": "2026-08-16T09:00:00Z"
}
FieldTypeNotes
phonestring | nullUnique per tenant when set
emailstring | nullUnique per tenant when set
whatsapp_bsuidstring | nullWhatsApp business-scoped user id, for a user who hides their phone number. Unique per tenant when set
whatsapp_parent_bsuidstring | nullThe parent BSUID, when WhatsApp supplies one
whatsapp_usernamestring | nullWhatsApp username, stored lower-case without a leading @
whatsapp_opt_in, email_opt_in, sms_opt_inbooleanConsent per channel. Default false
consent_sourcestring | nullWhere consent was captured, in your own words
consent_updated_atdatetime | nullServer-managed. Stamped when any opt-in flag or consent_source changes
external_idsobject | nullYour own ids for this person in other systems, one per system: {"hubspot": "123"} is system hubspot, id 123. Create-or-update matches on them and ?external_id= finds a contact by one
lifecycle_stagestring | nullsubscriber, lead, qualified, opportunity, customer or churned
lead_sourcestring | nullSame values as a lead's source
owner_user_idUUID | nullThe teammate who owns the contact
tagsstring[]Your labels, in the order added. Up to 20, each at most 40 characters. See tags
metadataobject | nullFree-form JSON attached by the platform
updated_atdatetimeWhen the contact last changed. ?updated_after= filters on it

GET/api/v1/contacts

Newest first unless you pass sort.

ParameterTypeRequiredConstraints
qstringNoAt most 320 characters. Case-insensitive substring match against phone, email, name, whatsapp_username or whatsapp_bsuid
company_idUUIDNoOnly contacts linked to this company
lifecycle_stagestringNosubscriber, lead, qualified, opportunity, customer or churned
owner_user_idUUIDNoOnly contacts owned by this teammate
lead_sourcestringNoOnly contacts from this source (same values as a lead's source)
tagstring (repeatable)NoOnly contacts carrying any of these tags, e.g. ?tag=vip&tag=renewal. Exact match. At most 20
external_idstringNosystem:id, e.g. hubspot:123. At most 320 characters. Only the contact carrying that id in external_ids. The split is on the first colon, so the id itself may contain colons. Anything not shaped system:id is 422
sortstringNonewest (default), oldest, name, updated, or score — highest lead score first, unscored contacts last
updated_afterdatetimeNoISO 8601, e.g. 2026-11-17T06:30:00Z (no offset is read as UTC). Only records whose updated_at is later than this. The result is then ordered oldest change first (updated_at ascending, then id) and sort is ignored. See incremental sync
limitintegerNo1 <= limit <= 200, default 50
offsetintegerNo0 <= offset <= 100000, default 0
curl "https://api.callmissed.com/api/v1/contacts?q=acme.com&limit=50" \
  -H "Authorization: Bearer cm_your_api_key"

Returns an array of contact objects. Each also carries score and score_grade — the contact's lead score — or null when it has never been scored.

Look one contact up by your own id (an empty array means you have not sent it yet):

curl "https://api.callmissed.com/api/v1/contacts?external_id=hubspot:123" \
  -H "Authorization: Bearer cm_your_api_key"

Read what changed since your last sync, oldest change first:

curl "https://api.callmissed.com/api/v1/contacts?updated_after=2026-11-17T06:30:00Z&limit=200" \
  -H "Authorization: Bearer cm_your_api_key"

A deleted contact is not in this list. Deletions reach you only as the contact.deleted webhook.

GET/api/v1/contacts/count

Takes the same q, company_id, lifecycle_stage, owner_user_id, lead_source, tag and external_id filters as the list (not updated_after) and returns {"total": 1234} — how many contacts match.

POST/api/v1/contacts

At least one of phone, email or whatsapp_bsuid is required — 422 a contact requires a phone, an email or a WhatsApp BSUID otherwise.

FieldTypeRequiredConstraints
phonestringConditionalAt most 32 characters. Unique per tenant
emailstringConditionalAt most 320 characters. Unique per tenant
whatsapp_bsuidstringConditionalA 2-letter upper-case country code, a period, an optional ENT., then 1–128 letters/digits, e.g. US.13491208655302741918. Unique per tenant
whatsapp_parent_bsuidstringNoSame format as whatsapp_bsuid
whatsapp_usernamestringNo3–35 of a-z, 0-9, ., _, with at least one letter; may not start with www or ., end with ., or contain ... A leading @ is stripped and the value is lower-cased
namestringNoAt most 255 characters
company_idUUIDNoMust be a company in your tenant
external_idsobjectNoYour own ids, one per system, e.g. {"hubspot": "123"}
lifecycle_stagestringNosubscriber, lead, qualified, opportunity, customer or churned
lead_sourcestringNoSame values as a lead's source
owner_user_idUUIDNoMust be a user in your tenant
whatsapp_opt_inbooleanNoDefault false
email_opt_inbooleanNoDefault false
sms_opt_inbooleanNoDefault false
consent_sourcestringNoAt most 64 characters
tagsstring[]NoUp to 20, each at most 40 characters. Trimmed; blanks and repeats dropped
curl -X POST https://api.callmissed.com/api/v1/contacts \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "email": "[email protected]",
    "name": "Asha Menon",
    "company_id": "5c6d…",
    "whatsapp_opt_in": true,
    "consent_source": "checkout_form"
  }'

Returns 201 with the contact object.

phone, email and whatsapp_bsuid are natural keys. Reusing any of them returns 409 A contact with this phone, email or WhatsApp BSUID already exists. When you are syncing from another system, call create-or-update instead: it finds the existing contact for you. Otherwise search with ?q= before creating, or use duplicate detection and merge to clean up after the fact.

POST/api/v1/contacts/upsert

Create-or-update in one call. Scopes contacts:write and contacts:read, both required, because the call returns the contact it matched. The contact that already carries the same external id, phone or email is updated; when there is none, a new contact is created. Use it for every write from another system, so a retry or a second sync run does not create the person twice.

The body is the create body plus match_on:

FieldTypeRequiredConstraints
match_onstring[]No1 to 3 of external_id, phone, email, in order of preference. Default ["external_id", "phone", "email"]
external_idsobjectConditionalSystem name to id, e.g. {"hubspot": "123"}. At most 20 systems. A system name is 1–64 characters with no colon; an id is a string or an integer of 1–255 characters and is stored as a string
phonestringConditionalAt most 32 characters
emailstringConditionalAt most 320 characters
every other create fieldNoSame types and bounds as create. On a match, only the fields you send are written

The body must carry a value for at least one key named in match_on (422 otherwise). A key with no value in the body is skipped.

curl -X POST https://api.callmissed.com/api/v1/contacts/upsert \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": { "hubspot": "123" },
    "phone": "+919876543210",
    "email": "[email protected]",
    "name": "Asha Menon",
    "whatsapp_opt_in": true,
    "consent_source": "hubspot_sync",
    "tags": ["vip"]
  }'

201 when a contact was created, 200 when one was updated. The response is the contact object plus two fields:

{
  "id": "44110c7e-2a51-4c0f-9d3b-6f1e2a7b8c90",
  "tenant_id": "a0b1c2d3-4455-6677-8899-aabbccddeeff",
  "company_id": null,
  "phone": "+919876543210",
  "email": "[email protected]",
  "name": "Asha Menon",
  "external_ids": { "hubspot": "123" },
  "whatsapp_opt_in": true,
  "email_opt_in": false,
  "sms_opt_in": false,
  "consent_source": "hubspot_sync",
  "consent_updated_at": "2026-11-17T06:31:10.412000Z",
  "whatsapp_bsuid": null,
  "whatsapp_parent_bsuid": null,
  "whatsapp_username": null,
  "lifecycle_stage": null,
  "lead_source": null,
  "owner_user_id": null,
  "tags": ["vip"],
  "metadata": null,
  "created_at": "2026-11-17T06:31:10.412000Z",
  "updated_at": "2026-11-17T06:31:10.412000Z",
  "created": true,
  "matched_on": null
}
FieldTypeMeaning
createdbooleantrue = a new contact was created (201). false = an existing contact was updated (200)
matched_onstring | nullWhich key found the existing contact: external_id, phone or email — the first one in your match_on order that matched. null when created is true

How a contact is matched

KeyTwo values are the same when
external_idThe contact's external_ids holds the same id for the same system, for any system you sent
phoneThe last ten digits are equal, and the country codes agree when both numbers carry one. +91 98200 12345 and 098200 12345 match; +91 98200 12345 and +1 982 001 2345 do not
emailEqual after trimming spaces and lower-casing

Every key in match_on that has a value is looked up. One contact found: it is updated. None: a contact is created. More than one different contact found (your id is on one contact and the phone on another): nothing is written and you get 409 ambiguous_match.

What an update writes

  • Only the fields present in the body. A field you leave out keeps its stored value; tags, when sent, replaces the whole list.
  • The stored phone or email is kept as written when it was the matching key, so 098200 12345 in your system does not rewrite +919820012345 here.
  • external_ids are merged into the stored ones: systems you do not send are kept.
  • A contact found by phone or email that already carries a different id for one of your systems is another record in that system: nothing is written and you get 409 external_id_conflict.

Two upserts of the same record sent at the same moment do not create two contacts: the second waits for the first, then updates the contact it created. A retry after a timeout is therefore safe.

Upsert errors

409 bodies from this endpoint are objects, so read detail.code:

{
  "detail": {
    "code": "ambiguous_match",
    "message": "More than one contact matches this record. Merge them, or send match_on with only the key that identifies it.",
    "ids": ["44110c7e-2a51-4c0f-9d3b-6f1e2a7b8c90", "9922aa01-77b4-4e2c-8a10-0c5d6e7f8a9b"]
  }
}
StatusdetailWhat to do next
409code: "ambiguous_match", ids = the matching contacts (up to 10)They are the same person: merge ids, then retry. They are different people: retry with "match_on": ["external_id"]
409code: "external_id_conflict", ids = the one contact foundThe phone or email belongs to a contact already linked to another record in your system. Fix the link on your side, or retry with "match_on": ["external_id"] to create or update by id alone
409"A contact with this phone, email or WhatsApp BSUID already exists" (a plain string)A key you left out of match_on is already on another contact. Add that key to match_on, or drop the field from the body
422nothing to match on: send a value for one of …Send external_ids, phone or email for a key in match_on
422No contact matched, and a new contact requires a phone, an email or a WhatsApp BSUIDNothing matched your external_ids, and an id alone cannot create a contact. Add phone, email or whatsapp_bsuid
422A field-level validation messageexternal_ids is not an object, has more than 20 systems, a system name with a colon, or an empty or non-string/integer id; or a field is outside its create bounds
403API key missing required scope: contacts:write (or contacts:read)The key needs both scopes. Add the missing one
404Company not found, or an owner not foundcompany_id is not one of your companies, or owner_user_id is not a user in your tenant

GETPATCHDELETE/api/v1/contacts/{contact_id}

PATCH accepts the same fields, all optional, with the same bounds. Only the fields you send are changed. Send "company_id": null to un-link the contact from its company. tags replaces the whole list (null or [] clears it); to add or remove one tag across many contacts without touching their other tags, use bulk tags.

DELETE returns 204. Deals and conversations that pointed at the contact are kept, with their contact link cleared. The contact's memory is erased with it.

404 Contact not found for an unknown or another tenant's id. 404 Company not found when company_id is not one of your companies.

PATCH replaces external_ids with the object you send. To add one id and keep the rest, use create-or-update, which merges.

Webhooks

Subscribe a webhook to contact.created, contact.updated and contact.deleted (an API key needs contacts:read to subscribe) to be told about every change, whoever made it: your API calls, a teammate in the console, an agent during a call or chat, or an import. Created and updated events carry the contact object above; a deleted event carries id and external_ids, plus merged_into when the contact was folded into another by a merge.


Contact memory

Your AI agents can remember durable facts about a contact across conversations. These endpoints let you see exactly what is stored and erase any of it.

GET/api/v1/contacts/{contact_id}/memory

Scope contacts:read.

{
  "contact_id": "4411…",
  "facts": [
    {
      "key": "3f9a1c2b7d4e5f60",
      "fact": "Prefers to be contacted in Hindi",
      "confidence": 0.9,
      "source_conversation_id": "c0d1…",
      "created_at": "2026-08-10T09:00:00+00:00",
      "updated_at": "2026-08-16T12:00:00+00:00",
      "seen_count": 3,
      "injected": true
    }
  ],
  "max_facts": 50,
  "updated_at": "2026-08-16T12:00:00Z"
}
FieldTypeNotes
factsarrayRanked in the order the agent sees them. Empty (not 404) when nothing has been learned yet
facts[].keystringStable handle for deleting this one fact
facts[].seen_countintegerHow many separate conversations confirmed the fact
facts[].injectedbooleanWhether the fact is among those the agent is currently given
max_factsintegerHow many facts can be stored per contact

DELETE/api/v1/contacts/{contact_id}/memory

Scope contacts:write. Erases every fact about the contact. Returns 204, and is idempotent — erasing a contact with no memory is also 204.

DELETE/api/v1/contacts/{contact_id}/memory/{fact_key}

Scope contacts:write. Erases one fact, addressed by its key (1–64 characters) from the GET response. Returns 204, or 404 Fact not found when the key matches nothing.


Errors

StatusWhen
403Key is missing contacts:read / contacts:write
404Contact, linked company, or memory fact not in your tenant
409A contact with this phone, email or WhatsApp BSUID already exists; on create-or-update also ambiguous_match and external_id_conflict, see upsert errors
422No phone, email or BSUID on create, an external_id filter not shaped system:id, an updated_after that is not a date-time, nothing to match on in an upsert, a malformed BSUID or WhatsApp username, more than 20 tags or a tag over 40 characters, or a field over its length limit

Nothing on this page consumes credits.

On this page