Create a contact
POST/contacts
Creates a contact from a phone number or a BSUID. The phone is normalized to E.164 and
stored without the +; without a country code, send defaultCountry.
With ?upsert=true, a contact that already exists is updated instead of answering
409 — and then the answer is 200, optIn is ignored and tagIds replaces the
tags. Send optIn with the consent evidence to create the contact already able to
receive marketing.
An API key limited to some numbers gets 403: this operation covers the whole base.
Request
Responses
- 200
- 201
- 401
- 402
- 403
- 409
- 422
- 429
Existing contact updated (only with upsert=true).
Contact created.
Missing, malformed, unknown or revoked token (authentication), or a suspended
account (tenant_inactive).
No entitlement (payment_required). The body carries the reason in reason and the
way out in action: what to do (kind) and the dashboard page where it is done (url).
The resource does not belong to your account (forbidden), or the path is on the
mirror's block list (forbidden_endpoint), or your API key is limited to some numbers and
the operation covers the whole account (forbidden).
contact_exists (the phone or BSUID already belongs to another contact, with contactId) or contact_limit_reached (the plan reached its contact cap, with limit and plan).
Payload failed validation (invalid_request, detailed in issues) or was
rejected by Meta (meta_error, with the original body in meta).
Rate limit exceeded (rate_limit).
Response Headers
Seconds to wait before retrying.
Which rate limit category applied — send, media or default.
Which bucket the other headers describe — key (the API key), session (the dashboard) or account (the account ceiling).
Request ceiling for this category in the current window.
Requests left in the current window.