---
title: "Import contact"
method: POST
path: "/v1/contacts"
tags: ["LinkedIn"]
---

# Import contact

`POST /v1/contacts`

## Request

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

Imports a contact

## Request body

- ImportContactRequest
  - `account_id` string, required: LinkedIn account ID returned by `GET /v1/accounts`.
  - `linkedin_url` string, uri, required: LinkedIn member profile URL under `linkedin.com/in/`. Query parameters and paths after the member identifier are ignored.

## Response `200`

Contact was already attached to the LinkedIn account.

- ImportContactEnvelope
  - `data` ImportContactResponse, required
    - `contact` Contact, required: 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.
      - `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
    - `warnings` LinkedInWarning[], required: Empty when the selected LinkedIn account is fresh; otherwise contains the minimal sync warning. The warning does not block contact import.
      - `code` 'linkedin_sync_required', required
      - `account_id` string, required: LinkedIn account ID that needs to sync.
      - `message` '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.', required

## Other responses

- `201`: Contact imported and attached to the LinkedIn account for the first time.
- `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.
- `404`: Requested resource was not found.
- `409`: Request conflicts with an existing resource.
- `429`: Rate limit exceeded. Public routes allow 50 requests per 10 seconds per IP and endpoint.
- `500`: Unexpected server error.
- `502`: Upstream provider request failed.

---

[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)