---
title: "List contacts"
method: GET
path: "/v1/contacts"
tags: ["LinkedIn"]
---

# List contacts

`GET /v1/contacts`

## Request

- Base URL: `https://api.talktohumans.app`
- URL: `https://api.talktohumans.app/v1/contacts`
- Auth: HTTP bearer

Lists LinkedIn contacts.

## Query parameters

- `account_id` string[]
- `query` string
- `company_name` string
- `headline` string
- `search` string
- `location` string
- `company_size` string
- `tag` string
- `relationship_status` 'any' | 'connected' | 'not_connected' | 'unknown'
- `invitation_status` 'pending'
- `conversation_id` string
- `view_id` string
- `limit` integer
- `cursor` string

## Response `200`

Contacts matching the filters.

- ListContactsEnvelope
  - `data` ListContactsResponse, required
    - `contacts` Contact[], required
      - `account_relationship_id` string, required
      - `contact_id` string, required: TalkToHumans contact ID.
      - `provider_participant_id` string, required: LinkedIn participant ID.
      - `public_identifier` string
      - `account` AccountSummary, required
        - `account_id` string, required: TalkToHumans account ID.
        - `display_name` string, required
        - `provider_account_id` string, required: LinkedIn provider account ID.
        - `owner_user_id` string, required: TalkToHumans user ID that owns the account.
      - `name` string, required
      - `first_name` string
      - `last_name` string
      - `headline` string
      - `primary_role_title` string
      - `primary_company_name` string
      - `work_email` string: Work email when email enrichment was found for this organization.
      - `phone` string: Phone number when phone enrichment was found for this organization.
      - `linkedin_url` string, uri
      - `avatar_url` string, uri
      - `background_cover_url` string, uri
      - `about` string
      - `profile_action_label` string
      - `profile_action_url` string, uri
      - `follower_count` integer, nullable
      - `connections_count` integer, nullable
      - `relationship_status` 'connected' | 'not_connected' | 'unknown', required
      - `connection_invitation` ConnectionInvitation, nullable
        - `status` 'pending', required
        - `direction` 'incoming' | 'outgoing' | 'unknown', required
        - `invite_id` string
        - `invite_state` string
        - `invite_type` string
        - `received_at` string, date-time, nullable
      - `tags` APITag[], required
        - `name` string, required
        - `color` 'green' | 'orange' | 'blue' | 'red' | 'purple' | 'yellow' | 'pink' | 'grey', required
      - `notes_json` string: Notes.
      - `languages` Language[], required
        - `language` string, required
      - `experiences` Experience[], required
        - `experience_id` string, required
        - `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
        - `is_current` boolean, required
        - `description` string
      - `educations` Education[], required
        - `education_id` string, required
        - `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` Location[], required
        - `linkedin_text` string
        - `display_text` string
        - `country_code` string
        - `region_code` string
        - `country` string
        - `country_full` string
        - `state` string
        - `city` string
        - `geographic_area` string
        - `is_primary` boolean, required
        - `is_headquarter` boolean, required
      - `company` Company, nullable: A company.
        - `company_id` string, required
        - `provider_participant_id` string, required
        - `public_identifier` string
        - `name` string, required
        - `headline` string
        - `linkedin_url` string, uri
        - `avatar_url` string, uri
        - `background_cover_url` string, uri
        - `headcount` string
        - `employee_count` integer, nullable
        - `founding_date` string
        - `website_url` string, uri
        - `follower_count` integer, nullable
        - `about` string
        - `notes_json` string: Notes
        - `industries` Industry[], required
          - `name` string
          - `title` string
          - `industry_urn` string
          - `provider_industry_id` string
          - `hierarchy` string
        - `locations` Location[], required
          - `linkedin_text` string
          - `display_text` string
          - `country_code` string
          - `region_code` string
          - `country` string
          - `country_full` string
          - `state` string
          - `city` string
          - `geographic_area` string
          - `is_primary` boolean, required
          - `is_headquarter` boolean, required
        - `tags` APITag[]: Tags
          - `name` string, required
          - `color` 'green' | 'orange' | 'blue' | 'red' | 'purple' | 'yellow' | 'pink' | 'grey', required
      - `last_interaction_at` string, date-time, nullable
      - `sequence` Sequence, nullable
        - `sequence_id` string, required
        - `status` string, required
        - `stop_if_person_replies` boolean, required
        - `reply_guard_after` string, date-time, nullable
        - `next_step_id` string
        - `next_step_scheduled_for` string, date-time, nullable
        - `steps` SequenceStep[], required
          - `step_id` string, required
          - `template_run_public_id` string
          - `step_type` string, required
          - `trigger_type` string, required
          - `position` integer, required
          - `scheduled_for` string, date-time, nullable
          - `message_mode` string, required
          - `state` string, required
      - `app_url` string, uri, required
    - `pagination` Pagination, required
      - `limit` integer, required
      - `has_more` boolean, required
      - `next_cursor` string: Cursor for the next page. Omitted when there are no more results.

## Other responses

- `400`: Invalid request parameters.
- `401`: Missing, malformed, invalid, or retired local API key.
- `403`: API access is not enabled for the organization, the API key cannot resolve to an active organization user, or the credential cannot access the requested LinkedIn account.
- `429`: Rate limit exceeded. Public routes allow 50 requests per 10 seconds per IP and endpoint.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/talktohumans/apis/talktohumans-public-api.md) · [All operations](https://skmtc.dev/talktohumans/apis/talktohumans-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talktohumans/apis/talktohumans-public-api/revisions/4551ad2f26af?raw)