> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reply.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Import contacts
> _Requires the `contacts:write` scope (or a broader one that includes it)._
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.
## OpenAPI
````yaml /api-reference/bundled.yaml post /v3/contacts/import
openapi: 3.1.0
info:
version: 3.0.0
title: Reply API
description: API for managing email sequences, contacts, and automation workflows
servers:
- url: https://api.reply.io
security:
- bearerAuth: []
tags:
- name: User Account
description: Account information and authentication verification
- name: Accounts
description: Manage accounts (companies/organizations)
- name: AI SDR Insights
description: Read AI SDR insights for sequence contacts
- name: AI SDR Intent Signals
description: >-
Read Reply industry IDs and technology slugs used in AI SDR intent-signal
configuration (typeahead)
- name: AI SDR Sequences
description: >-
Manage AI SDR sequences and their AI SDR-specific settings — create, read
settings, partial update, autopilot enable/disable/force-start, approval
mode, generated step types, and playbook/knowledge-base connections
- name: AI SDR Web Search
description: Find contacts via AI-driven web search and review past searches
- name: Attachments
description: >-
Upload file attachments used across email templates, sequence steps, and
direct emails
- name: Account Lists
description: Manage account lists and account membership
- name: Background Jobs
description: >-
Track and cancel asynchronous background operations (e.g., email
validation)
- name: Custom Fields
description: Manage custom contact fields
- name: Direct Outreach
description: >-
Send one-off outreach directly to a contact outside of any sequence —
direct emails and LinkedIn connection requests, messages, InMails, and
voice messages
- name: Contact Blacklist Rules
description: Manage blacklist rules for domains, emails, and email exceptions
- name: Contact Enrichment
description: >-
Enrich contacts with emails, phone numbers, LinkedIn data, and AI-filled
custom fields
- name: Contact Lists
description: Manage contact lists and contact membership
- name: Contacts
description: Manage individual contacts
- name: Email Accounts
description: Manage email accounts used for sending and receiving
- name: Email Templates
description: Manage email templates and template folders
- name: Email Validations
description: Estimate and schedule asynchronous email validation jobs
- name: Holiday Calendars
description: Manage holiday calendars for scheduling
- name: Inbox
description: >-
Manage inbox threads and per-team thread categories — list/filter, read
state, replies, category assignment, and meeting-intent flagging
- name: LinkedIn Accounts
description: Manage LinkedIn accounts for outreach
- name: Live Data
description: >-
Find new contacts via Live Data searches and read typeahead values for the
Live Data / Autopilot filter sidebar
- name: AI SDR Knowledge Bases
description: >-
Manage AI SDR knowledge bases — collections of documents, links, reply
handlers, and reengagement cards that inform the agent's responses
- name: AI SDR Offers
description: >-
Manage AI SDR offers — bundles of company-context inputs (ICP, pain
points, value propositions, etc.) used to personalize outreach
- name: AI SDR Pending Approvals
description: >-
Review, send, regenerate, and provide feedback on AI-generated messages
awaiting human approval
- name: AI SDR Playbooks
description: >-
Manage AI SDR playbooks — tone, voice, and style guides applied during
personalized message generation
- name: Reports
description: >-
Generate and access performance reports across email, calls, tasks,
LinkedIn, and team performance
- name: Schedules
description: Manage email send schedules and timing
- name: Settings
description: Manage team and user settings
- name: Sequence Contacts
description: Manage contacts within sequences
- name: Sequence Email Accounts
description: Manage email accounts linked to sequences
- name: Sequence Folders
description: Organize sequences into folders
- name: Sequence LinkedIn Accounts
description: Manage LinkedIn accounts linked to sequences
- name: AI SDR Sequence Preview
description: >-
Read and regenerate per-contact previews of the messages a sequence will
send, and provide feedback on preview messages
- name: Sequence Steps
description: Manage individual steps in sequences
- name: Sequence Templates
description: Manage sequence templates
- name: Sequences
description: Manage email automation sequences
- name: AI SDR Strategist
description: Trigger AI Strategist runs
- name: Tasks
description: Manage tasks and to-do items
- name: Webhooks
description: Manage webhook subscriptions and inspect delivery history
paths:
/v3/contacts/import:
post:
tags:
- Contacts
summary: Import contacts
description: >-
_Requires the `contacts:write` scope (or a broader one that
includes it)._
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.
operationId: ImportContacts
requestBody:
required: true
content:
application/json:
schema:
type: object
title: Contacts Import Request
description: >-
Import contacts by providing an array of contact objects with
optional import settings
required:
- items
properties:
items:
type: array
minItems: 1
description: >-
Array of contact objects to import. Uses the same fields as
the contact patch model.
items:
type: object
title: Contact Patch Request
description: >-
Request model for updating an existing contact.
All fields are optional — only include the fields you want
to change (PATCH semantics).
properties:
email:
type: string
format: email
description: Primary email address
firstName:
type: string
description: First name
lastName:
type: string
description: Last name
phone:
type: string
description: Phone number
phone2:
type: string
description: Secondary phone number
title:
type: string
description: Job title
company:
type: string
description: Organization name
companySize:
type: string
enum:
- Empty
- SelfEmployed
- Ten
- Fifty
- TwoHundred
- FiveHundred
- OneThousand
- FiveThousand
- TenThousand
- OverTenThousand
description: Organization employee count range
industry:
type: string
description: Business sector
city:
type: string
description: City of residence
state:
type: string
description: State/province
country:
type: string
description: Country
timeZoneId:
type: string
description: Timezone identifier
linkedInUrl:
type: string
format: uri
description: LinkedIn profile URL
linkedInSalesNavigatorUrl:
type: string
format: uri
description: Sales Navigator URL
linkedInRecruiterUrl:
type: string
format: uri
description: Recruiter URL
notes:
type: string
description: Additional information
isOptedOut:
type: boolean
nullable: true
description: >-
Set or clear the contact's opted-out flag (suppresses
all communications when `true`).
callStatus:
type: string
nullable: true
allOf:
- type: string
title: Contact Call Status
description: >-
Contact-level call status. Set via `PATCH
/v3/contacts/{id}` (`callStatus` field). Pass
`none` to clear.
enum:
- none
- toCall
- called
description: Contact-level call status. Pass `none` to clear.
meetingStatus:
type: string
nullable: true
allOf:
- type: string
title: Contact Meeting Status
description: >-
Contact-level meeting status. Set via `PATCH
/v3/contacts/{id}` (`meetingStatus` field). Pass
`none` to clear.
enum:
- none
- meetingBooked
description: Contact-level meeting status. Pass `none` to clear.
ownerUserId:
type: integer
nullable: true
description: >-
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:
type: integer
nullable: true
description: ID of the contact account to link this contact to
customFields:
type: array
description: >-
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`.
items:
type: object
properties:
id:
type: integer
nullable: true
description: Custom field ID
name:
type: string
nullable: true
description: Custom field name (alternative to id)
value:
type: string
nullable: true
description: Field content
example:
firstName: Jane
company: New Company Inc
ownerUserId: 55
customFields:
- id: 1
value: Updated Value
- name: leadSource
value: Referral
options:
type: object
description: Import settings
properties:
overwriteExisting:
type: boolean
default: false
description: Whether to overwrite existing contacts that match
skipExisting:
type: boolean
default: false
description: Whether to skip existing contacts that match
skipWithoutEmails:
type: boolean
default: false
description: Whether to skip contacts that have no email address
detectTimeZone:
type: boolean
default: false
description: Whether to auto-detect timezone based on location data
restoreDeleted:
type: boolean
default: false
description: Whether to restore previously deleted contacts
listIds:
type: array
items:
type: integer
description: List IDs to add imported contacts to
sequenceId:
type: integer
nullable: true
description: Sequence ID to enroll imported contacts in
keys:
type: object
description: >-
Deduplication keys — fields used to identify existing
contacts.
By default, email is the primary key. Enable additional
keys for multi-field matching.
properties:
linkedInUrl:
type: boolean
default: false
description: Use LinkedIn URL as a deduplication key
phone:
type: boolean
default: false
description: Use phone number as a deduplication key
firstName:
type: boolean
default: false
description: Use first name as a deduplication key
lastName:
type: boolean
default: false
description: Use last name as a deduplication key
company:
type: boolean
default: false
description: Use company name as a deduplication key
customFieldIds:
type: array
items:
type: integer
description: Custom field IDs to use as deduplication keys
example:
items:
- email: john@example.com
firstName: John
lastName: Doe
company: Acme
- email: jane@example.com
firstName: Jane
lastName: Smith
company: Globex
options:
overwriteExisting: false
skipExisting: true
detectTimeZone: true
listIds:
- 10
- 20
responses:
'200':
description: Contacts import processed successfully
content:
application/json:
schema:
type: object
title: Contacts Import Response
description: >-
Summary of a processed contacts import request with per-item
results
properties:
items:
type: array
description: >-
Per-item result for each contact in the import request
(same order as input)
items:
type: object
properties:
id:
type: integer
nullable: true
description: >-
Contact ID (null if the contact was not
created/found)
status:
type: string
enum:
- created
- updated
- skipped
- failed
- restored
description: Result status for this item
error:
type: string
nullable: true
description: Error message if the item failed
added:
type: integer
description: Number of contacts created
updated:
type: integer
description: Number of contacts updated
skipped:
type: integer
description: Number of contacts skipped
failed:
type: integer
description: Number of contacts that failed
example:
items:
- id: 12345
status: created
error: null
- id: 12346
status: updated
error: null
- id: null
status: failed
error: Email is required
added: 1
updated: 1
skipped: 0
failed: 1
'400':
description: |-
Validation failure on the request body, or a business rule rejection
(e.g. import limit exceeded).
content:
application/problem+json:
schema:
oneOf:
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
errors:
type: array
description: >-
List of field-level validation errors. Always
non-empty when this
envelope is returned. Each entry pins a single
offending field
via JSON Pointer plus a sanitized detail
string.
items:
type: object
title: Validation Error
description: A single field-level validation error.
properties:
pointer:
type: string
description: >-
JSON Pointer (RFC 6901) to the offending
field — e.g.
`/steps/0/subject`.
* An empty string (`""`) means the error
applies to the whole
request body (e.g. body is missing or unparseable).
* For route or query parameter failures
the pointer is the parameter
name (e.g. `id`, `top`).
example: /steps/0/subject
detail:
type: string
description: >-
Sanitized, human-readable explanation of
this field's error. One of a
small set of templates — `"Field is
required."`, `"Value has an
invalid type."`, `"Value has an invalid
format."`, `"Request body is
not valid JSON."`, `"The request body is
required and cannot be
empty."` — or a FluentValidator message
on body endpoints.
example: Field is required.
title: Validation Problem
description: >-
Input-validation error response at 400. Returned when
the request body
fails binding, FluentValidator rules, or when
route/query parameter
attribute validation (`[Range]`, `[Required]`) fails.
Route, query, and
body errors are combined into a single `errors[]`
array — clients should
not assume one error per request.
- example:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /name
detail: Field is required.
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the
form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling;
use `detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a
given resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced
error slug.
Emitted for most 4xx responses (business 400, 403,
404, 409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Bad Request
status: 400
detail: Pagination parameters are invalid.
code: sequence.invalidPagination
examples:
validation_failed:
summary: Body validation failure (FluentValidator)
value:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /items
detail: '''items'' must not be empty.'
business_limit_exceeded:
summary: Import limit exceeded
value:
title: Bad Request
status: 400
detail: Maximum 1000 items per import request.
code: contact.limitExceeded
'401':
description: >-
Unauthorized. The response body is empty; check the
`WWW-Authenticate` header for the expected scheme.
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- example:
title: Unauthorized
status: 401
detail: Authentication credentials are missing or invalid.
'403':
description: User lacks required feature scope to import contacts
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Forbidden
status: 403
detail: You do not have permission to access this resource.
code: sequence.forbidden
example:
title: Forbidden
status: 403
detail: Feature scopes [AddProspect] are denied for userId 123.
code: contact.forbidden
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 1
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
example:
title: Too Many Requests
status: 429
detail: Rate limit exceeded. Retry after 60 seconds.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate every request with a Bearer token. Pass your Reply API key
in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from the Reply dashboard: **Settings → API Key**.
````