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

# Import contact

> Imports a contact




## OpenAPI

````yaml /developers/openapi.yaml post /v1/contacts
openapi: 3.0.3
info:
  title: TalkToHumans Public API
  version: 1.0.0
  license:
    name: Proprietary
  description: >
    Read and organize the LinkedIn organization data your team already manages
    in TalkToHumans: accounts, contacts, tags, notes, sequence state,
    conversations, and views.
servers:
  - url: https://api.talktohumans.app
    description: TalkToHumans API
security:
  - bearerAuth: []
tags:
  - name: Organization
    description: Organization details for the current API key.
  - name: LinkedIn
    description: LinkedIn accounts, contacts, companies, and conversations.
  - name: Activity
    description: Activity for organization reporting.
  - name: Enrich
    description: Profile enrichment for LinkedIn contacts and companies.
  - name: Views
    description: Saved TalkToHumans views.
paths:
  /v1/contacts:
    post:
      tags:
        - LinkedIn
      summary: Import contact
      description: |
        Imports a contact
      operationId: importContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportContactRequest'
            example:
              account_id: '42'
              linkedin_url: https://www.linkedin.com/in/jane-doe/
      responses:
        '200':
          description: Contact was already attached to the LinkedIn account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportContactEnvelope'
              example:
                data:
                  contact:
                    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
                    linkedin_url: https://www.linkedin.com/in/jane-doe/
                    relationship_status: unknown
                    tags: []
                    languages: []
                    experiences: []
                    educations: []
                    locations: []
                    app_url: https://app.talktohumans.app/contacts
                  warnings: []
        '201':
          description: >-
            Contact imported and attached to the LinkedIn account for the first
            time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportContactEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountScopedForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
components:
  schemas:
    ImportContactRequest:
      type: object
      additionalProperties: false
      required:
        - account_id
        - linkedin_url
      properties:
        account_id:
          type: string
          description: LinkedIn account ID returned by `GET /v1/accounts`.
          pattern: ^[1-9][0-9]*$
        linkedin_url:
          type: string
          format: uri
          description: >-
            LinkedIn member profile URL under `linkedin.com/in/`. Query
            parameters and paths after the member identifier are ignored.
          pattern: ^https?://(www\.)?linkedin\.com/in/[^/?#]+(?:[/?#].*)?$
    ImportContactEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/ImportContactResponse'
    ImportContactResponse:
      type: object
      additionalProperties: false
      required:
        - contact
        - warnings
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        warnings:
          type: array
          description: >-
            Empty when the selected LinkedIn account is fresh; otherwise
            contains the minimal sync warning. The warning does not block
            contact import.
          items:
            $ref: '#/components/schemas/LinkedInWarning'
    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
            - account_shared_access_required
            - 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.
        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
    LinkedInWarning:
      type: object
      additionalProperties: false
      required:
        - code
        - account_id
        - message
      properties:
        code:
          type: string
          enum:
            - linkedin_sync_required
        account_id:
          type: string
          description: LinkedIn account ID that needs to sync.
        message:
          type: string
          enum:
            - >-
              For security, TalkToHumans does not run LinkedIn actions or sync
              LinkedIn data in the cloud. Open TalkToHumans with this LinkedIn
              account connected to refresh its data before relying on it or
              running actions.
    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
        industries:
          type: array
          items:
            $ref: '#/components/schemas/Industry'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        tags:
          type: array
          description: Tags
          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, invalid, or retired local 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
    AccountScopedForbidden:
      description: >-
        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.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            accountSharedAccessRequired:
              summary: Requested account is not accessible to this credential
              value:
                code: account_shared_access_required
                message: >-
                  This account is not shared-access enabled for API or MCP. Ask
                  an admin to enable shared access before using this account
                  from this credential.
            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
            apiKeyPrincipalInvalid:
              value:
                code: forbidden
                message: >-
                  This API key is no longer linked to an active organization
                  user. Ask an organization admin to regenerate it
    NotFound:
      description: Requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: not_found
            message: participant not found
    Conflict:
      description: Request conflicts with an existing resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: conflict
            message: custom field key already exists
    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
    BadGateway:
      description: Upstream provider request failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: upstream_error
            message: Enrichment provider request failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Pass API key as `Authorization: Bearer <api_key>`.'

````