TextKitDocs

List contacts

GET/v1/contacts

Query Parameters

Results are paged. When has_more is true, pass next_cursor from the response as cursor to fetch the next page.

  • limitinteger

    Default 25. Maximum 100.

  • cursorstring
  • tagstring

    Only contacts carrying this tag

  • phone_numberstring

    Find the contact with this number (0 or 1 results)

  • segment_idstring

    Only contacts in this saved segment, evaluated now

  • list_idstring

    Only contacts in this list

  • qstring

    Matches name, email, company, or digits of the number

Responses

  • 200Page of Contact

    Contacts, newest first

  • 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

The body is a page: data (the array), has_more, and next_cursor (null on the last page). Each item in data:

  • 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.

  • 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