Skip to content

Contacts

Create a contact

Creates a contact in the workspace. Each phone number can only be saved once per workspace. Contacts cannot be edited after creation; delete and re-create instead.

POST/api/v1/contacts
  • Bearer API key
  • Scope: write
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Body

application/json
  • namestringrequired

    Contact name.

    Constraints
    1–100 characters after trimming.
    Example
    Jordan Lee
  • phonestringrequired

    Phone number with country code. Spaces, dashes, dots, brackets and a leading + are removed.

    Constraints
    After cleaning: 8–15 digits, not starting with 0 (pattern ^[1-9][0-9]{7,14}$).
    Example
    +15550100123
  • tagstringoptional

    Optional free-text tag.

    Constraints
    At most 60 characters.
    Example
    wholesale
  • opted_inbooleanoptional

    Whether the contact agreed to receive messages.

    Default
    false
    Example
    true

Response

201 Createdapplication/json

  • iduuid

    Contact id.

  • namestring

    Contact name.

  • phonestring

    Phone number with country code, digits only (no +).

  • tagstring

    Free-text tag (may be empty).

  • opted_ininteger

    1 if the contact agreed to receive messages, otherwise 0.

  • created_atinteger

    Creation time in Unix seconds.

  • avatar_urlstringmay be absent

    Profile picture URL, when one has been downloaded.

Status codes

  • 201Created. The new contact. Note that opted_in comes back as 0 or 1.
  • 400Bad request. Validation failed: provide a name (1–100 characters), tag must be at most 60 characters, provide an international phone number with country code (8–15 digits, no leading 0) or invalid body.
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 402Payment required. Only when subscriptions are enforced and the workspace has no active subscription. The body includes code: "payment_required".
  • 403Forbidden. The API key has the read scope, which only allows GET requests (API key is read-only). A key in another workspace gets API key belongs to a different workspace.
  • 409Conflict. A contact with this phone number already exists in the workspace.