API reference
Contacts API reference descriptions are provided in English to preserve the exact published contract.
Record the customer's instruction for an action taken on their behalf How much of this account's audience you may lawfully message List contacts or find one by identifier Resolve or create a contact by identifier List open contact identity conflicts Resolve an identity conflict by merging or dismissing it List reversible contact merge history Get contact merge recovery detail Reverse a contact merge within its 30-day window Fetch a contact Update a contact's profile and attributes Full consent history Record a consent event Merge another contact into this one List suppression history for a contact Add a suppression Remove a suppression List audience segments Create and materialize an audience segment Preview typed segment membership without mutation Get a contact segment Update and rematerialize a segment Delete an unused segment List materialized segment members and provenance Refresh dynamic segment membership Get the durable service-window state for a sender/contact pair List account suppressions with filters Suppress a contact by SID or by identifier Lift suppressions for a contact addressed by SID or identifier Record the customer's instruction for an action taken on their behalf POST /v1/accounts/{AC}/authorizations
postV1AccountsByAcAuthorizationsIdempotency-Key required 201
Meta's Tech Provider terms allow a provider to act only on the customer's instruction. This records one: who gave it, for which task, in their own words. It is written to the append-only audit chain rather than a table of its own, because what an authorisation needs is exactly what that chain already guarantees — attributable, timestamped, and not quietly editable afterwards by either side.
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID
Request body (3 fields) Request body Name Type Required Description instructionstring (max 2000 chars) yes resourceRefstring (max 64 chars) yes task"DISPLAY_NAME_SUBMISSION" | "OFFICIAL_BUSINESS_ACCOUNT_APPLICATION" | "TEMPLATE_SUBMISSION" | "TEMPLATE_APPEAL" yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
How much of this account's audience you may lawfully message GET /v1/accounts/{AC}/consent-coverage
getV1AccountsByAcConsentCoverage200
Contacts counted by consent purpose and current status, with the number suppressed. Admission already refuses a marketing send without evidence; this is the same evidence read forward, so a business can see the size of the audience it may actually reach before it builds a campaign around one it may not.
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List contacts or find one by identifier GET /v1/accounts/{AC}/contacts
getV1AccountsByAcContactsPaginated 200
List contacts, or find one by phone number or WhatsApp user ID with the identifier filters.
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description qquery · string (max 128 chars) identifierquery · string (max 256 chars) identifierTypequery · "phone_e164" | "bsuid" | "username" scopeRefquery · string (max 64 chars) limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes Account SID
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Resolve or create a contact by identifier POST /v1/accounts/{AC}/contacts
postV1AccountsByAcContactsIdempotency-Key required 200 201
Find the contact with this identifier, or create it. Calling it twice with the same number returns the same contact.
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID
Request body (6 fields) Request body Name Type Required Description attributesobject defaultCountrystring (pattern ^[A-Za-z]{2}$) displayNamestring (max 128 chars) identifiersobject[] yes localestring (max 16 chars) timezonestring (max 64 chars)
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List open contact identity conflicts GET /v1/accounts/{AC}/contacts/conflicts
getV1AccountsByAcContactsConflictsPaginated 200
An identifier that Meta or an import attached to a second contact in this account. Resolve by merging or dismissing.
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes Account SID
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Resolve an identity conflict by merging or dismissing it POST /v1/accounts/{AC}/contacts/conflicts/{ID}/resolve
postV1AccountsByAcContactsConflictsByIdResolveIdempotency-Key required 200
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes IDpath · string (uuid) yes
Request body (1 fields) Request body Name Type Required Description action"merge" | "dismiss" yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List reversible contact merge history GET /v1/accounts/{AC}/contacts/merges
getV1AccountsByAcContactsMergesPaginated 200
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes Account SID
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Get contact merge recovery detail GET /v1/accounts/{AC}/contacts/merges/{ID}
getV1AccountsByAcContactsMergesById200
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes IDpath · string (uuid) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Reverse a contact merge within its 30-day window POST /v1/accounts/{AC}/contacts/merges/{ID}/revert
postV1AccountsByAcContactsMergesByIdRevertIdempotency-Key required 200
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes IDpath · string (uuid) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Fetch a contact GET /v1/accounts/{AC}/contacts/{CT}
getV1AccountsByAcContactsByCt200
Fetch one contact with its identifiers, attributes and consent summary.
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes CTpath · string (CT… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Update a contact's profile and attributes PATCH /v1/accounts/{AC}/contacts/{CT}
patchV1AccountsByAcContactsByCtIdempotency-Key required 200
Update a contact's name, locale, time zone or attributes. Send `expectedUpdatedAt` to refuse the change if someone else edited the contact first.
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes CTpath · string (CT… SID) yes
Request body (5 fields) Request body Name Type Required Description attributesobject displayNamenull | string (max 128 chars) expectedUpdatedAtstring (date-time) localenull | string (max 16 chars) timezonenull | string (max 64 chars)
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Full consent history GET /v1/accounts/{AC}/contacts/{CT}/consents
getV1AccountsByAcContactsByCtConsentsPaginated 200
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes CTpath · string (CT… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Record a consent event POST /v1/accounts/{AC}/contacts/{CT}/consents
postV1AccountsByAcContactsByCtConsentsIdempotency-Key required 201
Record that a contact opted in or out for a purpose. Consent history is append-only: a new record supersedes, never overwrites.
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes CTpath · string (CT… SID) yes
Request body (17 fields) Request body Name Type Required Description evidenceobject evidence.applicationstring (max 128 chars) evidence.campaignRefstring (max 128 chars) evidence.capturedAtstring (date-time) evidence.proofRefstring (max 512 chars) evidence.reOptInboolean evidence.reasonstring (max 1000 chars) evidence.sourcePagestring (max 2048 chars) evidence.supersedesConsentSidstring (CV… SID) evidence.withdrawnAtstring (date-time) evidence.wordingstring (max 4096 chars) evidence.wordingVersionstring (max 128 chars) evidenceRefstring (max 512 chars) expiresAtstring (date-time) purpose"TRANSACTIONAL" | "AUTHENTICATION" | "MARKETING" | "SUPPORT" yes source"API" | "IMPORT" | "KEYWORD" | "FORM" | "PROVIDER" | "DASHBOARD" yes status"OPTED_IN" | "OPTED_OUT" | "UNKNOWN" | "REVOKED" | "EXPIRED" yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Merge another contact into this one POST /v1/accounts/{AC}/contacts/{CT}/merge
postV1AccountsByAcContactsByCtMergeIdempotency-Key required 200
The named contact becomes MERGED with merged_into set; identifiers, consents, suppressions, conversation windows (max of both) and pending dispatch move to the surviving contact. Reversible for 30 days.
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes CTpath · string (CT… SID) yes
Request body (2 fields) Request body Name Type Required Description mergeContactSidstring (CT… SID) yes reasonstring (max 256 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List suppression history for a contact GET /v1/accounts/{AC}/contacts/{CT}/suppressions
getV1AccountsByAcContactsByCtSuppressionsPaginated 200
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes CTpath · string (CT… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Add a suppression POST /v1/accounts/{AC}/contacts/{CT}/suppressions
postV1AccountsByAcContactsByCtSuppressionsIdempotency-Key required 201
Stop messages to a contact, for marketing only or for everything. Suppressed contacts are refused at send time.
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes CTpath · string (CT… SID) yes
Request body (6 fields) Request body Name Type Required Description expiresAtstring (date-time) mirrorToProviderboolean reason"CUSTOMER_OPT_OUT" | "PROVIDER_MARKETING_OPT_OUT" | "KEYWORD_OPT_OUT" | "COMPLAINT" | "LEGAL_SUPPRESSION" | "TENANT_BLOCKLIST" | "RISK_BLOCK" yes scope"MARKETING" | "ALL" yes senderSidstring (WA… SID) sourcestring (max 64 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Remove a suppression DELETE /v1/accounts/{AC}/contacts/{CT}/suppressions/{SU}
deleteV1AccountsByAcContactsByCtSuppressionsBySu200
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description reasonquery · string (max 500 chars) ACpath · string (AC… SID) yes CTpath · string (CT… SID) yes SUpath · string (SU… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List audience segments GET /v1/accounts/{AC}/segments
getV1AccountsByAcSegmentsPaginated 200
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes Account SID
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Create and materialize an audience segment POST /v1/accounts/{AC}/segments
postV1AccountsByAcSegmentsIdempotency-Key required 201
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID
Request body (11 fields) Request body Name Type Required Description contactSidsstring (CT… SID)[] filtersobject filters.attributesobject filters.consentobject filters.createdAfterstring (date-time) filters.displayNameContainsstring (max 128 chars) filters.localeInstring (max 35 chars)[] filters.suppressedboolean filters.timezoneInstring (max 128 chars)[] kind"DYNAMIC" yes namestring (max 128 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Preview typed segment membership without mutation POST /v1/accounts/{AC}/segments/preview
postV1AccountsByAcSegmentsPreviewIdempotency-Key required 200
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID
Request body (10 fields) Request body Name Type Required Description contactSidsstring (CT… SID)[] filtersobject filters.attributesobject filters.consentobject filters.createdAfterstring (date-time) filters.displayNameContainsstring (max 128 chars) filters.localeInstring (max 35 chars)[] filters.suppressedboolean filters.timezoneInstring (max 128 chars)[] kind"DYNAMIC" yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Get a contact segment GET /v1/accounts/{AC}/segments/{SG}
getV1AccountsByAcSegmentsBySg200
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID SGpath · string (SG… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Update and rematerialize a segment PATCH /v1/accounts/{AC}/segments/{SG}
patchV1AccountsByAcSegmentsBySgIdempotency-Key required 200
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID SGpath · string (SG… SID) yes
Request body (11 fields) Request body Name Type Required Description contactSidsstring (CT… SID)[] filtersobject filters.attributesobject filters.consentobject filters.createdAfterstring (date-time) filters.displayNameContainsstring (max 128 chars) filters.localeInstring (max 35 chars)[] filters.suppressedboolean filters.timezoneInstring (max 128 chars)[] kind"DYNAMIC" yes namestring (max 128 chars)
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Delete an unused segment DELETE /v1/accounts/{AC}/segments/{SG}
deleteV1AccountsByAcSegmentsBySg200
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID SGpath · string (SG… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List materialized segment members and provenance GET /v1/accounts/{AC}/segments/{SG}/members
getV1AccountsByAcSegmentsBySgMembersPaginated 200
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes Account SID SGpath · string (SG… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Refresh dynamic segment membership POST /v1/accounts/{AC}/segments/{SG}/refresh
postV1AccountsByAcSegmentsBySgRefreshIdempotency-Key required 200
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID SGpath · string (SG… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Get the durable service-window state for a sender/contact pair GET /v1/accounts/{AC}/senders/{WA}/contacts/{CT}/window
getV1AccountsByAcSendersByWaContactsByCtWindow200
Required scope: `senders:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes WApath · string (WA… SID) yes CTpath · string (CT… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List account suppressions with filters GET /v1/accounts/{AC}/suppressions
getV1AccountsByAcSuppressionsPaginated 200
Account-wide by default; filter by contact, identifier, reason or scope. `active=false` returns the full history including lifted and expired rows.
Required scope: `contacts:read`.
Parameters
Parameters Name Type Required Description contactSidquery · string (CT… SID) identifierquery · string (max 256 chars) identifierTypequery · "phone_e164" | "bsuid" | "username" scopeRefquery · string (max 64 chars) reasonquery · string (max 64 chars) scopequery · "MARKETING" | "ALL" activequery · boolean limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes Account SID
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Suppress a contact by SID or by identifier POST /v1/accounts/{AC}/suppressions
postV1AccountsByAcSuppressionsIdempotency-Key required 201
Addressed with exactly one of `contactSid` or `identifier`. An identifier that this account has never seen resolves-or-creates the contact, so a suppression captured before the first message still holds when that message is attempted.
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID
Request body (10 fields) Request body Name Type Required Description contactSidstring (CT… SID) expiresAtstring (date-time) identifierstring (max 256 chars) identifierType"phone_e164" | "bsuid" | "username" mirrorToProviderboolean reason"CUSTOMER_OPT_OUT" | "PROVIDER_MARKETING_OPT_OUT" | "KEYWORD_OPT_OUT" | "COMPLAINT" | "LEGAL_SUPPRESSION" | "TENANT_BLOCKLIST" | "RISK_BLOCK" yes scope"MARKETING" | "ALL" yes scopeRefstring (max 64 chars) senderSidstring (WA… SID) sourcestring (max 64 chars)
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Lift suppressions for a contact addressed by SID or identifier DELETE /v1/accounts/{AC}/suppressions
deleteV1AccountsByAcSuppressions200
Removal is a state change, never a delete of history: each affected row keeps its record and emits `suppression.removed`. Narrow with `suppressionSid` or `scope`.
Required scope: `contacts:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes Account SID
Request body (7 fields) Request body Name Type Required Description contactSidstring (CT… SID) identifierstring (max 256 chars) identifierType"phone_e164" | "bsuid" | "username" reasonstring (max 500 chars) scope"MARKETING" | "ALL" scopeRefstring (max 64 chars) suppressionSidstring (SU… SID)
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .