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

# List contacts

> Use this endpoint to list, search, and filter LinkedIn contacts including network connections or imported contacts.




## OpenAPI

````yaml /openapi.yaml get /v1/contacts
openapi: 3.0.3
info:
  title: TalkToHumans Public API
  version: 1.0.0
  license:
    name: Proprietary
  description: >
    Read and organize the LinkedIn workspace data your team already manages in
    TalkToHumans: accounts, people, tags, notes, sequence state, conversations,
    and views.
servers:
  - url: https://api.talktohumans.app
    description: TalkToHumans API
security:
  - bearerAuth: []
tags:
  - name: Organization
    description: Workspace details for the current API key.
  - name: LinkedIn
    description: >-
      Accounts, contacts, companies, and conversations already synced into
      TalkToHumans.
  - name: Enrich
    description: Profile enrichment for LinkedIn people and companies.
  - name: Views
    description: Saved TalkToHumans views and lists.
paths:
  /v1/contacts:
    get:
      tags:
        - LinkedIn
      summary: List contacts
      description: >
        Use this endpoint to list, search, and filter LinkedIn contacts
        including network connections or imported contacts.
      operationId: listContacts
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: query
          in: query
          description: >-
            Search by name, headline, company, role, LinkedIn handle, or profile
            URL.
          schema:
            type: string
        - name: company_name
          in: query
          description: Filter by current or past company name.
          schema:
            type: string
        - name: headline
          in: query
          description: Filter by headline text.
          schema:
            type: string
        - name: search
          in: query
          description: >-
            Search broadly across profile details, tags, notes, locations, work
            history, education, and company data.
          schema:
            type: string
        - name: location
          in: query
          description: Filter by location text.
          schema:
            type: string
        - name: company_size
          in: query
          description: Filter by company size or employee count.
          schema:
            type: string
        - name: tag
          in: query
          description: Filter by tag name.
          schema:
            type: string
        - name: relationship_status
          in: query
          description: Filter by LinkedIn relationship state. Defaults to `any`.
          schema:
            type: string
            enum:
              - any
              - connected
              - not_connected
              - unknown
        - name: invitation_status
          in: query
          description: Filter by invitation state. Only `pending` is currently supported.
          schema:
            type: string
            enum:
              - pending
        - name: conversation_id
          in: query
          description: >-
            Return contacts who participate in the given TalkToHumans
            conversation.
          schema:
            type: string
        - name: view_id
          in: query
          description: >
            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.
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Contacts matching the filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListContactsEnvelope'
              example:
                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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    AccountId:
      name: account_id
      in: query
      description: >
        LinkedIn account IDs returned by `GET /v1/accounts`.


        Repeat the query parameter for multiple accounts. The backend also
        accepts comma-separated values.
      schema:
        type: array
        items:
          type: string
          pattern: ^[1-9][0-9]*$
      style: form
      explode: true
    Limit:
      name: limit
      in: query
      description: Page size. Defaults to 10. Values above 25 are clamped to 25.
      schema:
        type: integer
        minimum: 1
        default: 10
        maximum: 25
    Cursor:
      name: cursor
      in: query
      description: Opaque cursor from the previous response's `pagination.next_cursor`.
      schema:
        type: string
  schemas:
    ListContactsEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/ListContactsResponse'
    ListContactsResponse:
      type: object
      additionalProperties: false
      required:
        - contacts
        - pagination
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Error:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - unauthorized
            - forbidden
            - not_found
            - bad_request
            - internal_error
            - conflict
            - rate_limit_exceeded
            - billing_payment_failed
            - billing_subscription_incomplete
            - billing_subscription_expired
            - billing_grace_period
            - billing_feature_not_available
            - billing_insufficient_credits
            - billing_invalid
            - upstream_error
        message:
          type: string
          description: Human-readable error message.
        debug:
          type: string
          description: Development-only debug details.
    Contact:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CustomFieldValue'
      description: >
        LinkedIn contact. Registered custom field values may appear as
        additional top-level properties using

        each custom field's `key`, alongside the system fields documented below.
      required:
        - account_relationship_id
        - contact_id
        - provider_participant_id
        - account
        - name
        - relationship_status
        - tags
        - languages
        - experiences
        - educations
        - locations
        - app_url
      properties:
        account_relationship_id:
          type: string
        contact_id:
          type: string
          description: TalkToHumans contact ID.
        provider_participant_id:
          type: string
          description: LinkedIn participant ID.
        public_identifier:
          type: string
        account:
          $ref: '#/components/schemas/AccountSummary'
        name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        headline:
          type: string
        primary_role_title:
          type: string
        primary_company_name:
          type: string
        work_email:
          type: string
          description: Work email when email enrichment was found for this organization.
        phone:
          type: string
          description: Phone number when phone enrichment was found for this organization.
        linkedin_url:
          type: string
          format: uri
        avatar_url:
          type: string
          format: uri
        background_cover_url:
          type: string
          format: uri
        about:
          type: string
        profile_action_label:
          type: string
        profile_action_url:
          type: string
          format: uri
        follower_count:
          type: integer
          nullable: true
        connections_count:
          type: integer
          nullable: true
        relationship_status:
          $ref: '#/components/schemas/RelationshipStatus'
        connection_invitation:
          $ref: '#/components/schemas/ConnectionInvitation'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/APITag'
        notes_json:
          type: string
          description: Notes stored as JSON text.
        languages:
          type: array
          items:
            $ref: '#/components/schemas/Language'
        experiences:
          type: array
          items:
            $ref: '#/components/schemas/Experience'
        educations:
          type: array
          items:
            $ref: '#/components/schemas/Education'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        company:
          $ref: '#/components/schemas/Company'
        last_interaction_at:
          type: string
          format: date-time
          nullable: true
        sequence:
          $ref: '#/components/schemas/Sequence'
        app_url:
          type: string
          format: uri
    Pagination:
      type: object
      additionalProperties: false
      required:
        - limit
        - has_more
      properties:
        limit:
          type: integer
          format: int32
          example: 10
        has_more:
          type: boolean
        next_cursor:
          type: string
          description: Cursor for the next page. Omitted when there are no more results.
    CustomFieldValue:
      nullable: true
      description: >-
        Custom field value. Text fields return strings, number fields return
        numbers, boolean fields return booleans, and date fields return
        `YYYY-MM-DD` strings. Null appears only when a value is explicitly
        cleared or absent in a write response.
      oneOf:
        - type: string
        - type: number
        - type: boolean
    AccountSummary:
      type: object
      additionalProperties: false
      required:
        - account_id
        - display_name
        - provider_account_id
        - owner_user_id
      properties:
        account_id:
          type: string
          description: TalkToHumans account ID.
        display_name:
          type: string
        provider_account_id:
          type: string
          description: LinkedIn provider account ID.
        owner_user_id:
          type: string
          description: TalkToHumans user ID that owns the account.
    RelationshipStatus:
      type: string
      enum:
        - connected
        - not_connected
        - unknown
    ConnectionInvitation:
      type: object
      additionalProperties: false
      nullable: true
      required:
        - status
        - direction
      properties:
        status:
          type: string
          enum:
            - pending
        direction:
          type: string
          enum:
            - incoming
            - outgoing
            - unknown
        invite_id:
          type: string
        invite_state:
          type: string
        invite_type:
          type: string
        received_at:
          type: string
          format: date-time
          nullable: true
    APITag:
      type: object
      additionalProperties: false
      required:
        - name
        - color
      properties:
        name:
          type: string
        color:
          type: string
          enum:
            - green
            - orange
            - blue
            - red
            - purple
            - yellow
            - pink
            - grey
    Language:
      type: object
      additionalProperties: false
      required:
        - language
      properties:
        language:
          type: string
    Experience:
      type: object
      additionalProperties: false
      required:
        - experience_id
        - is_current
      properties:
        experience_id:
          type: string
        company_participant_id:
          type: string
        company_provider_participant_id:
          type: string
        company_name:
          type: string
        title:
          type: string
        employment_type:
          type: string
        location:
          type: string
        start_at:
          type: string
        end_at:
          type: string
        is_current:
          type: boolean
        description:
          type: string
    Education:
      type: object
      additionalProperties: false
      required:
        - education_id
      properties:
        education_id:
          type: string
        school_participant_id:
          type: string
        school_provider_participant_id:
          type: string
        school_name:
          type: string
        degree:
          type: string
        field_of_study:
          type: string
        start_at:
          type: string
        end_at:
          type: string
        description:
          type: string
    Location:
      type: object
      additionalProperties: false
      required:
        - is_primary
        - is_headquarter
      properties:
        linkedin_text:
          type: string
        display_text:
          type: string
        country_code:
          type: string
        region_code:
          type: string
        country:
          type: string
        country_full:
          type: string
        state:
          type: string
        city:
          type: string
        geographic_area:
          type: string
        is_primary:
          type: boolean
        is_headquarter:
          type: boolean
    Company:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CustomFieldValue'
      description: |
        A company.
      nullable: true
      required:
        - company_id
        - provider_participant_id
        - name
        - industries
        - locations
      properties:
        company_id:
          type: string
        provider_participant_id:
          type: string
        public_identifier:
          type: string
        name:
          type: string
        headline:
          type: string
        linkedin_url:
          type: string
          format: uri
        avatar_url:
          type: string
          format: uri
        background_cover_url:
          type: string
          format: uri
        headcount:
          type: string
        employee_count:
          type: integer
          nullable: true
        founding_date:
          type: string
        website_url:
          type: string
          format: uri
        follower_count:
          type: integer
          nullable: true
        about:
          type: string
        notes_json:
          type: string
          description: Notes stored as JSON text.
        industries:
          type: array
          items:
            $ref: '#/components/schemas/Industry'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        tags:
          type: array
          description: >-
            Workspace tags on the company. Present on the dedicated company
            resource.
          items:
            $ref: '#/components/schemas/APITag'
    Sequence:
      type: object
      additionalProperties: false
      nullable: true
      required:
        - sequence_id
        - status
        - stop_if_person_replies
        - steps
      properties:
        sequence_id:
          type: string
        status:
          type: string
        stop_if_person_replies:
          type: boolean
        reply_guard_after:
          type: string
          format: date-time
          nullable: true
        next_step_id:
          type: string
        next_step_scheduled_for:
          type: string
          format: date-time
          nullable: true
        steps:
          type: array
          items:
            $ref: '#/components/schemas/SequenceStep'
    Industry:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        title:
          type: string
        industry_urn:
          type: string
        provider_industry_id:
          type: string
        hierarchy:
          type: string
    SequenceStep:
      type: object
      additionalProperties: false
      required:
        - step_id
        - step_type
        - trigger_type
        - position
        - message_mode
        - state
      properties:
        step_id:
          type: string
        template_run_public_id:
          type: string
        step_type:
          type: string
        trigger_type:
          type: string
        position:
          type: integer
          format: int32
        scheduled_for:
          type: string
          format: date-time
          nullable: true
        message_mode:
          type: string
        state:
          type: string
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: bad_request
            message: Invalid request parameters
    Unauthorized:
      description: Missing, malformed, or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingAuthorization:
              value:
                code: unauthorized
                message: Authorization header is required
            invalidAuthorizationFormat:
              value:
                code: unauthorized
                message: Authorization header must use Bearer scheme
            invalidAPIKey:
              value:
                code: unauthorized
                message: Invalid API key
    Forbidden:
      description: >-
        API access is not enabled for the workspace, or the credential cannot
        access the requested workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              value:
                code: forbidden
                message: you don't have access to this organization
            featureUnavailable:
              value:
                code: billing_feature_not_available
                message: >-
                  Feature 'TalkToHumansAPI' is not available in your current
                  plan
            insufficientCredits:
              value:
                code: billing_insufficient_credits
                message: Insufficient credits
    RateLimited:
      description: >-
        Rate limit exceeded. Public routes allow 50 requests per 10 seconds per
        IP and endpoint.
      headers:
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limit_exceeded
            message: Rate limit exceeded
    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: internal_error
            message: An internal error occurred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Pass your API key as `Authorization: Bearer <api_key>`.'

````