Contact Data API

The CRM-grade contact and account store — create, import, filter, and organize the people and companies your agent works.

Base URL: https://api.reply.io/v3
Official reference: docs.reply.io/api-reference/contacts/list-all-contacts
OpenAPI: contact-data.openapi.yaml
Markdown twin: contact-data.md
Scopes: contacts:readcontacts:writecontacts:operate

What it does

The Contact Data API is the system of record. Every other module reads from it or writes to it: Prospect Search deposits people here, Contact Enrichment fills in their fields, sequences pull from it, and the suppression blacklist protects it. The surface covers five resource groups — contacts (create, update, delete, bulk delete, import, filter, list), contact lists (create, add, move, share), custom fields (define and manage your own schema), accounts (company records with bulk create and contact linking), and account lists. Per contact, the API also exposes notes, activity history, engagement statuses, current sequence membership, owner changes, bounce/reply flags, and a direct move-to-sequence operation.

The problem it solves

An agent without a durable store re-discovers the same people every run, emails prospects it already burned, and loses every piece of research it produced. Bolting a database onto an outreach tool means building dedupe, list management, field schemas, and sync — then keeping it consistent with what the sequencer actually sent. The Contact Data API is that store, already wired into the platform: import a contact once and its bounce state, reply state, sequence history, and notes accumulate on the same record every module sees.

How an agent starts using it

Create one record with POST /v3/contacts, or load a batch with the Import contacts operation and file it into a list via the Contact Lists endpoints (contacts:write, plus contacts:operate for add/move). Define custom fields first if your pipeline produces data the standard schema lacks. From there, read paths do the daily work: Filter contacts to build segments, Get activities and Get sequences for a contact to check history before outreach, and Filter accounts for company-level targeting. The IDs this API returns are the currency every other Reply.io endpoint accepts.

Typical agent tasks

Create a contact with title, company, and custom-field data before sequencing it
Bulk import a scored prospect list and drop it into a named contact list
Filter contacts by owner, status, or custom field to build a re-engagement segment
Attach a research note and fill custom fields with personalization data
Group contacts under a company account and organize accounts into account lists
Check a contact's activity history and sequence membership before reaching out

Inputs

Name	Type	Required	Description
`email`	string	yes	Contact email address — the primary identity key (create).
`profileFields`	object	no	Standard fields — firstName, lastName, company, title, phone, LinkedIn URL — plus values for any custom fields you have defined.
`contacts`	Contact[]	no	A batch of contacts for the Import contacts operation — one request instead of one call per contact.
`filter`	FilterExpression	no	Field conditions for the Filter contacts and Filter accounts operations.
`listId`	string	no	Target contact list or account list for add/move operations.

Outputs

Name	Type	Description
`id`	integer	Numeric contact or account identifier used by sequences, lists, direct outreach, and every other module — the same integer that appears in paths like /v3/contacts/{contactId}/send-direct-email.
`statuses`	ContactStatus[]	Per-sequence engagement state — from the Get a contact's statuses operation.
`activities`	Activity[]	Recorded touches and events for a contact — from Get activities for a contact.
`lists`	List[]	The contact lists a contact belongs to — from Get contact's lists.

Authentication

API key as Bearer token. Send Authorization: Bearer <API_KEY> on every request. Get an API key in the Reply.io app under Settings → API Key — authentication reference.

Rate limits

100 requests/minute and 3,000 requests/hour per user (shared across all of the user's API clients). Prefer Import contacts over per-contact create loops for large loads — a batch counts as one request. On 429, honor the Retry-After header.

Example

Request — POST /v3/contacts

curl -X POST https://api.reply.io/v3/contacts \
  -H "Authorization: Bearer $REPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "company": "Acme",
    "title": "VP of Engineering"
  }'

Response — 201

{
  "id": 90514382,
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "createdAt": "2026-07-04T09:15:00Z"
}

Error — 403

{
  "type": "https://docs.reply.io/api-reference/authentication",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the required scope: contacts:write."
}

Related APIs

Modules are designed to chain — combining them is the point.

Prospect Search API

Search Reply Data — 1B+ contacts and 60M+ companies — by ICP filters like job title, seniority, department, industry, and location, and turn the matches into a prospect list.

Coming soon

Contact Enrichment API

Fill the gaps in a contact record — find missing emails and phone numbers, enrich by email or LinkedIn URL, and populate AI custom fields.

Coming soon

Sequence API

Create, populate, and control multichannel outreach sequences — email, LinkedIn, and calls in one campaign object.

Suppression & Blacklist API

Do-not-contact rules by domain, email, and exception — compliance guardrails enforced platform-wide, with bulk operations.

docs.reply.io ↗

Frequently asked questions

Should an agent loop Create a contact or use Import contacts for bulk loads?

Import contacts. One request carries a whole batch, which is one hit against the 100 req/min limit instead of hundreds; large imports are processed in the background rather than inline. Reserve Create a contact for single records; verify arrival with List all contacts or Filter contacts.

Where does personalization data live?

In custom fields. Define a field once with Create a custom field (contacts:write), then write per-contact values on create or update. Anything your research pipeline produces — pain points, tech stack, trigger events — becomes a merge variable that sequence templates can reference.

What is the difference between an account and a contact?

A contact is a person; an account is the company they belong to. Accounts have their own CRUD, bulk create, filtering, and owner assignment, and contacts link to them via the bulk add/remove contact operations. Account lists group accounts the same way contact lists group contacts — useful for ABM-style targeting.

Start here: get an API key and make your first call, or explore workflows that combine this module with others.