---
title: "Import contacts"
method: POST
path: "/v3/contacts/import"
tags: ["Contacts"]
---

# Import contacts

`POST /v3/contacts/import`

<small>_Requires the `contacts:write` scope (or a broader one that includes it)._</small>

Use this endpoint when you need to add or update many contacts in one call — for example when syncing contacts from another system. Each item uses the same fields as the contact update model. Use options to control deduplication, list assignment, and other import behavior: which keys identify an existing contact (email plus any of LinkedIn URL, phone, name, company, or custom fields), whether matched contacts are overwritten or skipped, whether previously deleted contacts are restored, and which lists or sequence the imported contacts are added to. The response reports how many contacts were added, updated, skipped, or failed, with a per-item outcome.

## Request body

- object — Import contacts by providing an array of contact objects with optional import settings
  - `items` object[], required — Array of contact objects to import. Uses the same fields as the contact patch model.
    - `email` string, email — Primary email address
    - `firstName` string — First name
    - `lastName` string — Last name
    - `phone` string — Phone number
    - `phone2` string — Secondary phone number
    - `title` string — Job title
    - `company` string — Organization name
    - `companySize` 'Empty' | 'SelfEmployed' | 'Ten' | 'Fifty' | 'TwoHundred' | 'FiveHundred' | 'OneThousand' | 'FiveThousand' | 'TenThousand' | 'OverTenThousand' — Organization employee count range
    - `industry` string — Business sector
    - `city` string — City of residence
    - `state` string — State/province
    - `country` string — Country
    - `timeZoneId` string — Timezone identifier
    - `linkedInUrl` string, uri — LinkedIn profile URL
    - `linkedInSalesNavigatorUrl` string, uri — Sales Navigator URL
    - `linkedInRecruiterUrl` string, uri — Recruiter URL
    - `notes` string — Additional information
    - `isOptedOut` boolean, nullable — Set or clear the contact's opted-out flag (suppresses all communications when `true`).
    - `callStatus` 'none' | 'toCall' | 'called', nullable — Contact-level call status. Set via `PATCH /v3/contacts/{id}` (`callStatus` field). Pass `none` to clear.
    - `meetingStatus` 'none' | 'meetingBooked', nullable — Contact-level meeting status. Set via `PATCH /v3/contacts/{id}` (`meetingStatus` field). Pass `none` to clear.
    - `ownerUserId` integer, nullable — Change the owner of this contact. The new owner must be a member of the caller's team; otherwise the request fails with `404`.
    - `accountId` integer, nullable — ID of the contact account to link this contact to
    - `customFields` object[] — Custom fields to update. Fields can be identified by `id` or `name`. Unlike the response model which uses `key`/`value`, the patch model accepts `id`, `name`, and `value`.
      - `id` integer, nullable — Custom field ID
      - `name` string, nullable — Custom field name (alternative to id)
      - `value` string, nullable — Field content
  - `options` object — Import settings
    - `overwriteExisting` boolean — Whether to overwrite existing contacts that match
    - `skipExisting` boolean — Whether to skip existing contacts that match
    - `skipWithoutEmails` boolean — Whether to skip contacts that have no email address
    - `detectTimeZone` boolean — Whether to auto-detect timezone based on location data
    - `restoreDeleted` boolean — Whether to restore previously deleted contacts
    - `listIds` integer[] — List IDs to add imported contacts to
    - `sequenceId` integer, nullable — Sequence ID to enroll imported contacts in
    - `keys` object — Deduplication keys — fields used to identify existing contacts. By default, email is the primary key. Enable additional keys for multi-field matching.
      - `linkedInUrl` boolean — Use LinkedIn URL as a deduplication key
      - `phone` boolean — Use phone number as a deduplication key
      - `firstName` boolean — Use first name as a deduplication key
      - `lastName` boolean — Use last name as a deduplication key
      - `company` boolean — Use company name as a deduplication key
      - `customFieldIds` integer[] — Custom field IDs to use as deduplication keys

## Response `200`

Contacts import processed successfully

- object — Summary of a processed contacts import request with per-item results
  - `items` object[] — Per-item result for each contact in the import request (same order as input)
    - `id` integer, nullable — Contact ID (null if the contact was not created/found)
    - `status` 'created' | 'updated' | 'skipped' | 'failed' | 'restored' — Result status for this item
    - `error` string, nullable — Error message if the item failed
  - `added` integer — Number of contacts created
  - `updated` integer — Number of contacts updated
  - `skipped` integer — Number of contacts skipped
  - `failed` integer — Number of contacts that failed

## Other responses

- `400` — Validation failure on the request body, or a business rule rejection (e.g. import limit exceeded).
- `401` — Unauthorized. The response body is empty; check the `WWW-Authenticate` header for the expected scheme.
- `403` — User lacks required feature scope to import contacts
- `429` — Too Many Requests

---

[API](https://skmtc.net/reply/apis/reply-api.md) · [All operations](https://skmtc.net/reply/apis/reply-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/reply/reply-api/revisions/1c3d32eaf95e/schema)