Skip to main content
GET
List contacts

Authorizations

Authorization
string
header
required

Pass Authorization: Bearer <credential>, where the credential is either:

  • an API key (sk_…), generated by an organization admin in Settings, for scripts and automation;
  • an access token from tth auth login (the TalkToHumans CLI), which any member of the workspace can use.

Both resolve to the same organization and user. A login token acts in the user's workspace: one with no workspace yet returns 403 workspace_setup_required, and one in several workspaces returns 403 forbidden (use an API key instead).

Query Parameters

account_id
string[]

LinkedIn account IDs returned by GET /v1/accounts.

Repeat the query parameter for multiple accounts. The backend also accepts comma-separated values. If an explicit account target is not accessible to this credential, the API returns 403 account_shared_access_required.

Pattern: ^[1-9][0-9]*$
contact_id
string

Filter by contact ID, including email and phone lookup results.

Pattern: ^[1-9][0-9]*$
query
string

Search by name, headline, company, role, about, experiences, notes, LinkedIn handle, or profile URL.

provider_participant_id
string

Return the contact with this exact LinkedIn provider participant ID, such as urn:li:fsd_profile:abc. TalkToHumans contacts page URLs carry it as their contact query parameter.

conversation_id
string

Return contacts who participate in the given TalkToHumans conversation.

view_id
string

Filter by a saved contact view. Accepts the view id or an unambiguous public_id from GET /v1/views. Uses the view's account and filters. An explicit account_id scope must include that account. Results keep the endpoint's normal ordering.

filters
string

JSON array of filters contacts must all match, in the same shape as a view's filters. Field keys name their record, such as member.full_name, company.industry, or conversation.reply_state. Custom fields use member.custom_fields.<name>. To find contacts by LinkedIn URL, filter member.linkedin_url = with a list of URLs. Requires exactly one account: pass one account_id when several are accessible.

sorts
string

JSON array of sorts, first entry first, in the same shape as a view's sorts. Requires exactly one account. Pages still follow cursor.

limit
integer
default:10

Page size. Defaults to 10. Values above 25 are clamped to 25.

Required range: 1 <= x <= 25
cursor
string

Opaque cursor from the previous response's pagination.next_cursor.

Response

Contacts matching the filters.

data
object
required