TextKitDocs

Create or update a contact

One contact per phone number.

POST/v1/contacts

Body Parameters

  • phone_numberstringrequired

    E.164, US or Canada

  • namestring

    Display name. Defaults to first + last name. At most 120 characters.

  • tagsarray of string

    At most 20 items.

  • fieldsobject

    Up to 20 string values (account id, plan, location...), usable in segments and as {{field:key}} merge fields

  • notesstring

    At most 2000 characters.

  • first_namestring

    At most 80 characters.

  • last_namestring

    At most 80 characters.

  • emailstring

    At most 254 characters.

  • companystring

    At most 120 characters.

  • statestring

    At most 40 characters. Example: TN.

  • sourcestring

    Where the contact came from. Defaults to "api". At most 60 characters.

  • opt_inobject

    Import only (POST /v1/contacts/import). Stored as consent evidence; never lifts an opt-out.

  • opt_in.statusboolean

    true = opted in; false = unsubscribed (recorded as an opt-out)

  • opt_in.atstring

    When they opted in: ISO timestamp, date, or epoch ms

  • opt_in.sourcestring

    web_form, keyword, paper, checkout or verbal are stored as proof; anything else is kept as a note

  • opt_in.campaign_idstring

    The registration the opt-in is for. A marketing or mixed registration needs at, a recognised source, and page_url for a web form, or the row is skipped Example: reg_a1B2c3D4e5F6.

  • opt_in.page_urlstring (uri)

    The page a web-form opt-in was collected on

Details

Creates the contact (201) or updates the one that already has this number (200). Values you leave out are kept and tags are added, never removed; use PATCH to replace them.

Responses

  • 200Contact

    The existing contact, updated

  • 201Contact

    The new contact

  • 400Error

    Invalid request

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429Error

    Rate limit or quota exceeded

Response Fields (200)

  • idstring

    Example: ct_a1B2c3D4e5F6.

  • objectcontact
  • phone_numberstring

    Example: +14155550132.

  • namestring

    Nullable.

  • tagsarray of string

    Free-form labels; they double as broadcast audiences

  • fieldsobject
  • notesstring

    Nullable.

  • first_namestring

    Nullable.

  • last_namestring

    Nullable.

  • emailstring

    Nullable.

  • companystring

    Nullable.

  • statestring

    Nullable.

  • sourcestring

    Nullable.

  • import_idstring

    The last import that touched this contact Nullable.

  • opt_inobject

    Nullable.

  • opt_in.sourcestring

    Nullable.

  • opt_in.collected_atstring (date-time)

    Nullable.

  • created_atstring (date-time)
  • updated_atstring (date-time)
  • consent_statusopted_out, opted_in, no_record

    Only on retrieve

  • topicsarray of TopicSubscription

    Only on retrieve

  • segmentsarray of object

    Only on retrieve

  • segments[].idstring
  • segments[].namestring

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 400

    Invalid request

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429

    Rate limit or quota exceeded