Skip to main content
GET
https://api.talktohumans.app
/
v1
/
contacts
Find contacts
curl --request GET \
  --url https://api.talktohumans.app/v1/contacts \
  --header 'Authorization: Bearer <token>'
{
  "data": {
    "contacts": [
      {
        "account_relationship_id": "<string>",
        "contact_id": "<string>",
        "provider_participant_id": "<string>",
        "account": {
          "account_id": "<string>",
          "display_name": "<string>",
          "provider_account_id": "<string>",
          "owner_user_id": "<string>"
        },
        "name": "<string>",
        "tags": [
          {
            "name": "<string>"
          }
        ],
        "languages": [
          {
            "language": "<string>"
          }
        ],
        "experiences": [
          {
            "experience_id": "<string>",
            "is_current": true,
            "company_participant_id": "<string>",
            "company_provider_participant_id": "<string>",
            "company_name": "<string>",
            "title": "<string>",
            "employment_type": "<string>",
            "location": "<string>",
            "start_at": "<string>",
            "end_at": "<string>",
            "description": "<string>"
          }
        ],
        "educations": [
          {
            "education_id": "<string>",
            "school_participant_id": "<string>",
            "school_provider_participant_id": "<string>",
            "school_name": "<string>",
            "degree": "<string>",
            "field_of_study": "<string>",
            "start_at": "<string>",
            "end_at": "<string>",
            "description": "<string>"
          }
        ],
        "locations": [
          {
            "is_primary": true,
            "is_headquarter": true,
            "linkedin_text": "<string>",
            "display_text": "<string>",
            "country_code": "<string>",
            "region_code": "<string>",
            "country": "<string>",
            "country_full": "<string>",
            "state": "<string>",
            "city": "<string>",
            "geographic_area": "<string>"
          }
        ],
        "app_url": "<string>",
        "public_identifier": "<string>",
        "first_name": "<string>",
        "last_name": "<string>",
        "headline": "<string>",
        "primary_role_title": "<string>",
        "primary_company_name": "<string>",
        "linkedin_url": "<string>",
        "avatar_url": "<string>",
        "background_cover_url": "<string>",
        "about": "<string>",
        "profile_action_label": "<string>",
        "profile_action_url": "<string>",
        "follower_count": 123,
        "connections_count": 123,
        "connection_invitation": {
          "invite_id": "<string>",
          "invite_state": "<string>",
          "invite_type": "<string>",
          "received_at": "2023-11-07T05:31:56Z"
        },
        "notes_json": "<string>",
        "company": {
          "company_id": "<string>",
          "provider_participant_id": "<string>",
          "name": "<string>",
          "industries": [
            {
              "name": "<string>",
              "title": "<string>",
              "industry_urn": "<string>",
              "provider_industry_id": "<string>",
              "hierarchy": "<string>"
            }
          ],
          "locations": [
            {
              "is_primary": true,
              "is_headquarter": true,
              "linkedin_text": "<string>",
              "display_text": "<string>",
              "country_code": "<string>",
              "region_code": "<string>",
              "country": "<string>",
              "country_full": "<string>",
              "state": "<string>",
              "city": "<string>",
              "geographic_area": "<string>"
            }
          ],
          "public_identifier": "<string>",
          "headline": "<string>",
          "linkedin_url": "<string>",
          "avatar_url": "<string>",
          "background_cover_url": "<string>",
          "headcount": "<string>",
          "employee_count": 123,
          "founding_date": "<string>",
          "website_url": "<string>",
          "follower_count": 123,
          "about": "<string>",
          "notes_json": "<string>"
        },
        "last_interaction_at": "2023-11-07T05:31:56Z",
        "sequence": {
          "sequence_id": "<string>",
          "status": "<string>",
          "stop_if_person_replies": true,
          "steps": [
            {
              "step_id": "<string>",
              "step_type": "<string>",
              "trigger_type": "<string>",
              "position": 123,
              "message_mode": "<string>",
              "state": "<string>",
              "template_run_public_id": "<string>",
              "scheduled_for": "2023-11-07T05:31:56Z"
            }
          ],
          "reply_guard_after": "2023-11-07T05:31:56Z",
          "next_step_id": "<string>",
          "next_step_scheduled_for": "2023-11-07T05:31:56Z"
        }
      }
    ],
    "pagination": {
      "limit": 10,
      "has_more": true,
      "next_cursor": "<string>"
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://talktohumans.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Pass your API key as Authorization: Bearer <api_key>.

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.

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

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

​
company_name
string

Filter by current or past company name.

​
headline
string

Filter by headline text.

​
search
string

Search broadly across profile details, tags, notes, locations, work history, education, and company data.

​
location
string

Filter by location text.

​
company_size
string

Filter by company size or employee count.

​
tag
string

Filter by tag name.

​
relationship_status
enum<string>

Filter by LinkedIn relationship state. Defaults to any.

Available options:
any,
connected,
not_connected,
unknown
​
invitation_status
enum<string>

Filter by invitation state. Only pending is currently supported.

Available options:
pending
​
conversation_id
string

Return contacts who participate in the given TalkToHumans conversation.

​
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