List contacts - TalkToHumans

GET

https://api.talktohumans.app

contacts

List contacts

curl --request GET \
  --url https://api.talktohumans.app/v1/contacts \
  --header 'Authorization: Bearer <token>'

{
  "data": {
    "contacts": [
      {
        "account_relationship_id": "1042",
        "contact_id": "123",
        "provider_participant_id": "urn:li:fsd_profile:abc",
        "public_identifier": "jane-doe",
        "account": {
          "account_id": "42",
          "display_name": "Jane Doe",
          "provider_account_id": "ACoAA000000",
          "owner_user_id": "7"
        },
        "name": "Jane Doe",
        "first_name": "Jane",
        "last_name": "Doe",
        "headline": "Founder at Acme",
        "primary_role_title": "Founder",
        "primary_company_name": "Acme",
        "work_email": "jane@acme.example",
        "phone": "+14155550123",
        "linkedin_url": "https://www.linkedin.com/in/jane-doe/",
        "avatar_url": "https://media.licdn.com/dms/image/example/profile-displayphoto.jpg",
        "background_cover_url": "https://media.licdn.com/dms/image/example/profile-cover.jpg",
        "relationship_status": "connected",
        "Deal stage": "Qualified",
        "Lead score": 91,
        "Next follow-up": "2026-07-01",
        "VIP": true,
        "tags": [
          {
            "name": "Hot lead",
            "color": "red"
          }
        ],
        "languages": [
          {
            "language": "English"
          }
        ],
        "experiences": [
          {
            "experience_id": "exp_2f8c1b",
            "company_participant_id": "linkedin:participant:urn:li:fsd_company:123",
            "company_provider_participant_id": "urn:li:fsd_company:123",
            "company_name": "Acme",
            "title": "Founder",
            "employment_type": "Full-time",
            "location": "San Francisco Bay Area",
            "start_at": "2021-01",
            "is_current": true,
            "description": "Building business software for sales teams."
          }
        ],
        "educations": [
          {
            "education_id": "edu_91ac42",
            "school_participant_id": "linkedin:participant:urn:li:fsd_company:987",
            "school_provider_participant_id": "urn:li:fsd_company:987",
            "school_name": "Stanford University",
            "degree": "MBA",
            "field_of_study": "Business Administration",
            "start_at": "2014",
            "end_at": "2016"
          }
        ],
        "locations": [
          {
            "linkedin_text": "San Francisco Bay Area",
            "display_text": "San Francisco, California, United States",
            "country_code": "US",
            "region_code": "US-CA",
            "country": "United States",
            "country_full": "United States",
            "state": "California",
            "city": "San Francisco",
            "geographic_area": "San Francisco Bay Area",
            "is_primary": true,
            "is_headquarter": false
          }
        ],
        "company": {
          "company_id": "linkedin:participant:urn:li:fsd_company:123",
          "provider_participant_id": "urn:li:fsd_company:123",
          "public_identifier": "acme",
          "name": "Acme",
          "linkedin_url": "https://www.linkedin.com/company/acme/",
          "avatar_url": "https://media.licdn.com/dms/image/example/company-logo.jpg",
          "background_cover_url": "https://media.licdn.com/dms/image/example/company-cover.jpg",
          "headline": "Software Development",
          "headcount": "51-200",
          "employee_count": 120,
          "website_url": "https://acme.example",
          "follower_count": 12000,
          "about": "Acme builds business software.",
          "industries": [
            {
              "name": "Software Development",
              "title": "Software Development",
              "industry_urn": "urn:li:industry:4",
              "provider_industry_id": "4",
              "hierarchy": "Technology > Software"
            }
          ],
          "locations": [
            {
              "linkedin_text": "San Francisco, CA",
              "display_text": "San Francisco, California, United States",
              "country_code": "US",
              "region_code": "US-CA",
              "country": "United States",
              "country_full": "United States",
              "state": "California",
              "city": "San Francisco",
              "geographic_area": "San Francisco Bay Area",
              "is_primary": true,
              "is_headquarter": true
            }
          ]
        },
        "app_url": "https://app.talktohumans.app/contacts"
      }
    ],
    "pagination": {
      "limit": 10,
      "has_more": false
    }
  }
}

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.

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.

view_id

string

Return only contacts that belong to a saved TalkToHumans view (list). Accepts the view id or public_id returned by GET /v1/views. Works for views created in the app and views created with POST /v1/views. Results are scoped to the view's LinkedIn account.

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

Show child attributes

Update contactUse this endpoint to update a specific contact.

List contacts

curl --request GET \
  --url https://api.talktohumans.app/v1/contacts \
  --header 'Authorization: Bearer <token>'

{
  "data": {
    "contacts": [
      {
        "account_relationship_id": "1042",
        "contact_id": "123",
        "provider_participant_id": "urn:li:fsd_profile:abc",
        "public_identifier": "jane-doe",
        "account": {
          "account_id": "42",
          "display_name": "Jane Doe",
          "provider_account_id": "ACoAA000000",
          "owner_user_id": "7"
        },
        "name": "Jane Doe",
        "first_name": "Jane",
        "last_name": "Doe",
        "headline": "Founder at Acme",
        "primary_role_title": "Founder",
        "primary_company_name": "Acme",
        "work_email": "jane@acme.example",
        "phone": "+14155550123",
        "linkedin_url": "https://www.linkedin.com/in/jane-doe/",
        "avatar_url": "https://media.licdn.com/dms/image/example/profile-displayphoto.jpg",
        "background_cover_url": "https://media.licdn.com/dms/image/example/profile-cover.jpg",
        "relationship_status": "connected",
        "Deal stage": "Qualified",
        "Lead score": 91,
        "Next follow-up": "2026-07-01",
        "VIP": true,
        "tags": [
          {
            "name": "Hot lead",
            "color": "red"
          }
        ],
        "languages": [
          {
            "language": "English"
          }
        ],
        "experiences": [
          {
            "experience_id": "exp_2f8c1b",
            "company_participant_id": "linkedin:participant:urn:li:fsd_company:123",
            "company_provider_participant_id": "urn:li:fsd_company:123",
            "company_name": "Acme",
            "title": "Founder",
            "employment_type": "Full-time",
            "location": "San Francisco Bay Area",
            "start_at": "2021-01",
            "is_current": true,
            "description": "Building business software for sales teams."
          }
        ],
        "educations": [
          {
            "education_id": "edu_91ac42",
            "school_participant_id": "linkedin:participant:urn:li:fsd_company:987",
            "school_provider_participant_id": "urn:li:fsd_company:987",
            "school_name": "Stanford University",
            "degree": "MBA",
            "field_of_study": "Business Administration",
            "start_at": "2014",
            "end_at": "2016"
          }
        ],
        "locations": [
          {
            "linkedin_text": "San Francisco Bay Area",
            "display_text": "San Francisco, California, United States",
            "country_code": "US",
            "region_code": "US-CA",
            "country": "United States",
            "country_full": "United States",
            "state": "California",
            "city": "San Francisco",
            "geographic_area": "San Francisco Bay Area",
            "is_primary": true,
            "is_headquarter": false
          }
        ],
        "company": {
          "company_id": "linkedin:participant:urn:li:fsd_company:123",
          "provider_participant_id": "urn:li:fsd_company:123",
          "public_identifier": "acme",
          "name": "Acme",
          "linkedin_url": "https://www.linkedin.com/company/acme/",
          "avatar_url": "https://media.licdn.com/dms/image/example/company-logo.jpg",
          "background_cover_url": "https://media.licdn.com/dms/image/example/company-cover.jpg",
          "headline": "Software Development",
          "headcount": "51-200",
          "employee_count": 120,
          "website_url": "https://acme.example",
          "follower_count": 12000,
          "about": "Acme builds business software.",
          "industries": [
            {
              "name": "Software Development",
              "title": "Software Development",
              "industry_urn": "urn:li:industry:4",
              "provider_industry_id": "4",
              "hierarchy": "Technology > Software"
            }
          ],
          "locations": [
            {
              "linkedin_text": "San Francisco, CA",
              "display_text": "San Francisco, California, United States",
              "country_code": "US",
              "region_code": "US-CA",
              "country": "United States",
              "country_full": "United States",
              "state": "California",
              "city": "San Francisco",
              "geographic_area": "San Francisco Bay Area",
              "is_primary": true,
              "is_headquarter": true
            }
          ]
        },
        "app_url": "https://app.talktohumans.app/contacts"
      }
    ],
    "pagination": {
      "limit": 10,
      "has_more": false
    }
  }
}