Contacts · Ready Docs

#Contacts

One contact per phone number. Errors in this section carry their code in code.

Details

tags comes back as a JSON-encoded string, for example "[\"vip\",\"hot\"]". Parse it with JSON.parse(contact.tags). When you send tags, send a real array.
Contacts have more fields than shown here. Ignore fields you don't recognize; new ones may be added.
Suppression fields (opt_out_locked, dnd_sms and others) are explained under Opt-outs.

#List contacts

GET/contacts

Your contacts, most recently updated first, with filters.

Cost Free

Query parameters

searchstringOptional: Partial, case-insensitive match on name, email, company or phone.
Details
Name means first or last name. Phone numbers match in any format. Without tag, at most the 5,000 best matches are considered, so narrow broad searches.
tagstringOptional: Exact tag name, case-sensitive: VIP isn't vip.
statusstringOptional: For example opted_out.
dndintegerOptional: 1: only contacts with texting turned off.
limitintegerOptionalDefault 50Max 1000: Page size.
offsetintegerOptionalDefault 0: Rows to skip: a whole number, 0 or more.
sortenumOptional: Default: most recently updated first. For a full export use date_added.
Details
A contact edited while you page jumps to the front of the default order. Unknown values fall back to the default.
date_added
name_asc , name_desc
phone_asc , phone_desc
status_asc , status_desc
score_high , score_low
lastact_asc , lastact_desc
source_asc , source_desc
assignee_asc , assignee_desc

More parameters (7)

stagestringOptional: Pipeline stage.
sourcestringOptional: Where the contact came from.
companystringOptional: Company name.
statestringOptional: US state.
assigned_tostringOptional: A team member id, or unassigned.
score_min, score_maxintegerOptional: Lead score range.
include_spamintegerOptional: Contacts marked spam are left out unless you send 1.

Returns

data[]object[]: Contacts.
totalinteger: Matching contacts, for display only. Stop paging on a page shorter than limit (or empty).
Details
It can be an estimate, up to 2 minutes old, and can show 1 when nothing matches.

Errors

HTTP	Code	When
400	`invalid_offset`	Not a whole number, 0 or more (in `error_code`).

GET /contacts

curl "https://api.tryready.com/contacts?tag=vip&limit=100&sort=date_added" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/contacts?tag=vip&limit=100&sort=date_added', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/contacts",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    params={
        "tag": "vip",
        "limit": 100,
        "sort": "date_added"
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": [
    {
      "id": 101,
      "first_name": "Ada",
      "last_name": "Lovelace",
      "phone": "+12125550199",
      "email": "ada@example.com",
      "tags": "[\"vip\"]",
      "pipeline_stage": "new_lead",
      "source": "manual",
      "status": "active",
      "score": 50,
      "dnd_sms": 0,
      "opt_out_locked": 0,
      "opt_out_at": null,
      "timezone": "America/New_York",
      "custom_fields": null,
      "created_at": "2026-10-01T21:04:51.779Z",
      "updated_at": "2026-10-01T21:04:51.779Z",
      "last_message_at": null
    }
  ],
  "total": 438
}

#Get a contact

GET/contacts/:id

One contact by id.

Cost Free

Path parameters

idintegerRequired: The contact id.

Returns

dataobject: The contact.

Errors

HTTP	Code	When
404	`CONTACT_NOT_FOUND`	Not on your account, or a non-numeric id.

GET /contacts/:id

curl "https://api.tryready.com/contacts/101" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/contacts/101', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/contacts/101",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "id": 101,
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "+12125550199",
    "email": "ada@example.com",
    "tags": "[\"vip\"]",
    "pipeline_stage": "new_lead",
    "source": "manual",
    "status": "active",
    "score": 50,
    "dnd_sms": 0,
    "opt_out_locked": 0,
    "opt_out_at": null,
    "timezone": "America/New_York",
    "custom_fields": null,
    "created_at": "2026-10-01T21:04:51.779Z",
    "updated_at": "2026-10-01T21:04:51.779Z",
    "last_message_at": null
  }
}

{
  "success": false,
  "code": "CONTACT_NOT_FOUND",
  "error": "We couldn't find this contact. It may have been deleted, so refresh Contacts to see the current list."
}

#Create a contact

POST/contacts

Adds a contact. Returns 201 with the new contact.

Cost Free; scrubbing runs if it's on (scrub rate)

Note. Retrying a timed-out create is safe: an existing number (any format) returns 409 CONTACT_EXISTS.

Details

Idempotency-Key isn't used here. A new contact is scrubbed and fires the contact_created webhook.

Body parameters

phonestringRequired: E.164 recommended (+12125550199). Any common US format is accepted; stored as E.164.
first_namestringOptional
last_namestringOptional
emailstringOptional
tagsstring[]Optional: An array of strings.
company_namestringOptional
pipeline_stagestringOptionalDefault new_lead: Free text; use the stage ids from your pipeline.
sourcestringOptionalDefault manual
timezonestringOptional: IANA name such as America/Chicago. If omitted, set from a US number's area code.

More parameters (6)

websitestringOptional
address1, address2, city, state, postal_code, countrystringOptional: Address fields.
date_of_birthstringOptional
genderstringOptional
assigned_tointegerOptional: A team member id.
dnd_sms, dnd_email, dnd_callsintegerOptional: 1 to turn off texting, email or calls. Turning texting off is an opt-out that can't be undone over the API.

Returns

dataobject: The new contact. Defaults: status: "active", score: 50.

Errors

HTTP	Code	When
400	no code	No phone number.
400	`INVALID_PHONE`	The number can't be read. Details Its message mentions a 10-digit US number, but E.164 numbers from other countries are accepted.
400	`invalid_field`	Wrong type, such as non-list `tags`.
400	`ASSIGNEE_NOT_ON_ACCOUNT`	`assigned_to` isn't on your account.
403	`permission_denied`	Key lacks `edit_contacts`.
403	`test_key_not_allowed`	Called with a test key.
409	`CONTACT_EXISTS`	Number exists. Find it with `GET /contacts?search=<phone>`.

POST /contacts

curl -X POST "https://api.tryready.com/contacts" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+12125550199",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "tags": [
      "vip"
    ]
  }'

const res = await fetch('https://api.tryready.com/contacts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phone": "+12125550199",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "tags": [
      "vip"
    ]
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/contacts",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "phone": "+12125550199",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
        "tags": ["vip"]
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "id": 101,
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "+12125550199",
    "email": "ada@example.com",
    "tags": "[\"vip\"]",
    "pipeline_stage": "new_lead",
    "source": "manual",
    "status": "active",
    "score": 50,
    "dnd_sms": 0,
    "opt_out_locked": 0,
    "opt_out_at": null,
    "timezone": "America/New_York",
    "custom_fields": null,
    "created_at": "2026-10-01T21:04:51.779Z",
    "updated_at": "2026-10-01T21:04:51.779Z",
    "last_message_at": null
  }
}

{
  "success": false,
  "code": "CONTACT_EXISTS",
  "error": "A contact with this phone number already exists. Search Contacts for the number to open it."
}

#Update a contact

PUT/contacts/:id

Changes only the fields you send. Use PUT: PATCH isn't supported.

Cost Free

Important. Unknown fields are ignored with a 200, so check the returned contact.

Path parameters

idintegerRequired: The contact id.

Body parameters

first_name, last_name, emailstringOptional
tagsstring[]Optional: An array that replaces the whole list.
Details
A plain string, null or "" is 400 invalid_field; send [] to clear. Send tags_base (the list you started from) too, and only your changes are applied.
pipeline_stagestringOptional: Free text.
statusstringOptional: You can't move an opted-out contact off opted_out.
dnd_smsintegerOptional: 1 opts the contact out of texts.
Details
You can't set it back to 0 on an opted-out contact (403): the contact must text START.
custom_fieldsobjectOptional: Merged key by key. null for a key deletes it.
phonestringOptional: Can't be changed: create a new contact instead.
Details
The same number in another format is fine.

More parameters (7)

dnd_email, dnd_callsintegerOptional
notesstringOptional
scoreintegerOptional: A non-integer returns 400 CONTACT_UPDATE_FAILED.
source, company_name, timezonestringOptional
address1, address2, city, state, postal_code, countrystringOptional
assigned_tointegerOptional
inbound_blockedintegerOptional

Returns

dataobject: The updated contact.

Errors

HTTP	Code	When
400	`PHONE_NOT_EDITABLE`	You sent a different phone number.
400	`invalid_field`	Wrong type, such as non-list `tags`.
400	`ASSIGNEE_NOT_ON_ACCOUNT`	`assigned_to` isn't on your account.
400	`CONTACT_UPDATE_FAILED`	A value can't be saved (`500` if the save failed).
403	`opt_out_locked`	Re-enabling texting on a STOP-locked contact (in `error_code`).
403	`opted_out`	Same, for other opt-outs such as Do Not Disturb (in `error_code`).
403	`permission_denied`	Key lacks `edit_contacts`.
403	`test_key_not_allowed`	Called with a test key.
404	`CONTACT_NOT_FOUND`	No contact with this id.
409	`CONTACT_CHANGED`	The contact opted out mid-save.
500	`CUSTOM_FIELD_NOT_SAVED`	A custom field didn't save. Retry.

PUT /contacts/:id

curl -X PUT "https://api.tryready.com/contacts/101" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "vip",
      "hot"
    ],
    "pipeline_stage": "qualified",
    "custom_fields": {
      "order_id": "1042"
    }
  }'

const res = await fetch('https://api.tryready.com/contacts/101', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "tags": [
      "vip",
      "hot"
    ],
    "pipeline_stage": "qualified",
    "custom_fields": {
      "order_id": "1042"
    }
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/contacts/101",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "tags": ["vip", "hot"],
        "pipeline_stage": "qualified",
        "custom_fields": {
            "order_id": "1042"
        }
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "id": 101,
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "+12125550199",
    "email": "ada@example.com",
    "tags": "[\"vip\",\"hot\"]",
    "pipeline_stage": "qualified",
    "source": "manual",
    "status": "active",
    "score": 50,
    "dnd_sms": 0,
    "opt_out_locked": 0,
    "opt_out_at": null,
    "timezone": "America/New_York",
    "custom_fields": {
      "order_id": "1042"
    },
    "created_at": "2026-10-01T21:04:51.779Z",
    "updated_at": "2026-10-01T21:20:13.004Z",
    "last_message_at": null
  }
}

#Delete a contact

DEL/contacts/:id

Permanently removes the contact and its conversation history, notes and tasks.

Cost Free

Legal. Keep your own opt-out list: a re-added number shows as not opted out.

Details

If you add the number again, the new contact and GET /v1/opt-outs/:phone show it as not opted out. Ready keeps the opt-out in a separate record for its own send check, but check your own list before you add a number back.

Path parameters

idintegerRequired: The contact id, not its phone number.

Errors

HTTP	Code	When
400	`INVALID_CONTACT_ID`	Not a contact id (for example a phone number).
403	`permission_denied`	Key lacks `edit_contacts`.
403	`test_key_not_allowed`	Called with a test key.
404	`CONTACT_NOT_FOUND`	No such contact, or already deleted.
423	`LITIGATION_HOLD`	Under a legal hold.

DEL /contacts/:id

curl -X DELETE "https://api.tryready.com/contacts/101" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/contacts/101', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.delete(
    "https://api.tryready.com/contacts/101",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true
}

{
  "success": false,
  "code": "INVALID_CONTACT_ID",
  "error": "That isn't a contact id. Use the id from the contact's record, not its phone number."
}