Update and delete contacts

#Update a contact

Changes only the fields you send. Use PUT: PATCH isn’t supported. Unknown fields are ignored with a 200; ignored_fields lists them, so check the spelling against the fields below. Needs the edit_contacts permission.

Parameters

idinteger · pathRequired: The contact id.

More parameters

first_name, last_name, emailstring
tagsstring[]: An array that replaces the whole list.

Clearing and merging
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_stagestring: Free text. Use a stage id from List stages.
statusstring: Any text is stored: there is no list of allowed values, so check your spelling. Setting opted_out, blocked, wrong_number or deceased turns texting off (it sets dnd_sms to 1). Check before you send one.

Undoing a status
Only blocked can be undone over the API: send {"status": "active", "dnd_sms": 0}. That works only if the contact wasn’t already opted out when it was blocked and hasn’t opted out since; otherwise it’s refused with 403 opted_out. The other three can’t be undone over the API. Changing their status later leaves texting off, and setting dnd_sms back to 0 is refused (403 opted_out). You can’t move a contact off opted_out.
dnd_smsinteger: 1 opts the contact out of texts.

Opting back in
You can’t set it back to 0 on an opted-out contact (403). A STOP-locked contact (opt_out_locked) can opt back in by texting START, unless the lock is a do-not-call or GoHighLevel DND match; a START doesn’t lift other opt-outs.
custom_fieldsobject: Merged key by key. null for a key deletes it.
phonestring: Can’t be changed: create a new contact instead. The same number in another format is fine.
dnd_email, dnd_callsinteger
notesstring: Free text kept on the contact. The Notes tab doesn’t show it; to add a note your team will see, use Create a note.
scoreinteger: 0 to 100. A decimal is rounded, and a number outside the range is clamped to it. A reply from the contact recalculates the score, so a value set here lasts until their next reply. A value that isn’t a number returns 400 invalid_field with field: "score".
source, company_name, timezonestring
address1, address2, city, state, postal_code, countrystring
assigned_tointeger
inbound_blockedinteger
website, date_of_birth, genderstring
auto_reply_suppressedinteger: Send 0 to resume texting a contact Ready paused for sending repeated auto-replies. It can only clear the pause: 1 is ignored.

Returns the updated Contact object in data. ignored_fields lists any field you sent that we did not recognise and did not save; it is left out when there are none.

Errors

HTTP	Code	When
400	`INVALID_CONTACT_ID`	Not a contact id (for example a phone number).
400	`PHONE_NOT_EDITABLE`	You sent a different phone number.
400	`invalid_field`	Wrong type, such as non-list `tags` or a `score` that isn’t a number.
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. `code` is `CONTACT_OPT_OUT_LOCKED`; `error_code` is `opt_out_locked`.
403	`opted_out`	Same, for other opt-outs such as Do Not Disturb. `code` is `CONTACT_OPTED_OUT`; `error_code` is `opted_out`.
403	`CONTACT_NOT_ASSIGNED`	Your key belongs to a team member who sees only their assigned contacts, and this contact is assigned to someone else.
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.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "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

Permanently removes the contact, its conversation history, notes, tasks and call recordings. If you add the number again, the new contact comes in opted out, because Ready keeps the opt-out on the number: see Keeping your own copy. Needs the edit_contacts permission.

Calls and recordings

The contact’s outbound dialer calls are removed too. Inbound calls, recording disclosure records and GoHighLevel dial pad calls stay, unlinked from the contact, as billing and consent records. Recordings and transcripts of every call with the contact, inbound, outbound, GoHighLevel dial pad and FaceTime, are deleted too and can’t be recovered. Export any you need first.

Parameters

idinteger · pathRequired: The contact id, not its phone number.

Returns { "success": true }.

Errors

HTTP	Code	When
400	`INVALID_CONTACT_ID`	Not a contact id (for example a phone number).
403	`CONTACT_NOT_ASSIGNED`	Your key belongs to a team member who sees only their assigned contacts, and this contact is assigned to someone else.
404	`CONTACT_NOT_FOUND`	No such contact, or already deleted.
423	`LITIGATION_HOLD`	Under a legal hold.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true
}

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