Contact lists

A contact list is a group of contacts you pick by hand. Lists and smart lists are the same thing underneath: one set of lists with one set of ids. GET /lists shows both kinds, and a list you make here works anywhere a segment_id is asked for, such as a campaign audience. A list made here holds only the contacts you add. A smart list made with POST /segments holds the contacts its rules match plus any you add by hand.

These paths start with /lists. The older /dialer/lists paths answer the same. Every route here needs the view_contacts permission, which every role holds by default.

Taking a contact out of a list only happens through Remove contacts from a list. Deleting a list never deletes its contacts.

#The Contact list object

idinteger: The list id. It also works as a segment_id.
namestring: The list’s name.
descriptionstring: Your description, or "".
contact_countinteger | null: How many contacts are in the list. A hand-picked list is counted live. A smart list shows its last saved count, or null when your seat only sees its assigned contacts.
is_dynamicinteger: 1 for a smart list or a list we refill on a schedule, 0 for a fixed list of contacts.
created_atstring: When the list was made.

#List contact lists

Every list on your account, hand-picked lists and smart lists alike, newest first, with how many contacts are in each. Shows up to 500 lists.

Returns

listsobject[]: A list of Contact list objects.
truncatedboolean: true when you have more than 500 lists and only the first 500 are shown.

Errors

HTTP	Code	When
500	`lists_read_failed`	We couldn’t load your lists. Retry.

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

const res = await fetch('https://api.tryready.com/lists', {
  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.get(
    "https://api.tryready.com/lists",
    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,
  "data": {
    "lists": [
      {
        "id": 31,
        "name": "Open house leads",
        "description": "",
        "contact_count": 58,
        "is_dynamic": 0,
        "created_at": "2026-10-20T16:04:51.000Z"
      },
      {
        "id": 23,
        "name": "Texas VIPs",
        "description": "",
        "contact_count": 412,
        "is_dynamic": 1,
        "created_at": "2026-10-02T14:11:09.000Z"
      }
    ],
    "truncated": false
  }
}

#List contacts in a list

One page of a list’s contacts. A hand-picked list shows the most recently added first. A smart list shows the contacts its rules match now plus the ones added by hand, newest contact first. To get the next page, pass the last page’s next_cursor as after.

Parameters

limitinteger · queryDefault 100Max 500
afterinteger · query: The next_cursor from the page before.
searchstring · query: Only contacts whose first name, last name or phone contains this text. Up to 100 characters are used.

Returns

listobject: The list’s id, name and description.
contactsobject[]: Each has id, first_name, last_name, phone, email, status, last_disposition (the last call result, if you use the dialer), added_at (when it joined the list; null on a smart list) and cursor.
totalinteger: How many contacts match, across all pages.
total_is_estimateboolean: Smart lists only. true when the total couldn’t be counted in time and is the last known count.
next_cursorinteger: Pass it as after for the next page. null when this page wasn’t full.

Errors

HTTP	Code	When
400	`list_not_found`	The id isn’t a whole number.
404	`list_not_found`	No list with this id on your account.
500	`rules_damaged`	This smart list’s saved rules are damaged. Save its rules again with Update a smart list.
500	`load_failed`	We couldn’t load the contacts. Retry.

curl "https://api.tryready.com/lists/31/contacts?limit=100" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/lists/31/contacts?limit=100', {
  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.get(
    "https://api.tryready.com/lists/31/contacts?limit=100",
    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,
  "data": {
    "list": {
      "id": 31,
      "name": "Open house leads",
      "description": ""
    },
    "contacts": [
      {
        "id": 101,
        "first_name": "Maria",
        "last_name": "Lopez",
        "phone": "+15125550123",
        "email": "maria@example.com",
        "status": "active",
        "last_disposition": null,
        "added_at": "2026-10-21T09:12:40.000Z",
        "cursor": 88412
      }
    ],
    "total": 58,
    "next_cursor": null
  }
}

#Create a list

Makes an empty hand-picked list. Returns 201. Sending the same name again within 2 minutes returns the first list with deduped: true. Needs the edit_contacts permission.

Parameters

namestringRequired: Up to 200 characters; longer names are cut.
descriptionstring: Up to 1,000 characters; longer text is cut.

Returns the new list’s id in data, plus deduped: true when it’s a repeat.

Errors

HTTP	Code	When
400	`name_required`	No name.
400	`invalid_field`	`name` or `description` is a list or object.
500	`create_failed`	We couldn’t create the list. Retry.

curl -X POST "https://api.tryready.com/lists" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Open house leads",
    "description": "Signed in at the Oak St open house"
  }'

const res = await fetch('https://api.tryready.com/lists', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Open house leads",
    "description": "Signed in at the Oak St open house"
  }),
});
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.post(
    "https://api.tryready.com/lists",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "name": "Open house leads",
        "description": "Signed in at the Oak St open house"
    },
    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": 31
  }
}

#Rename a list

Changes a list’s name and description. Works on smart lists too, and leaves their rules alone. Send name every time, even when you only change the description. Needs the manage_campaigns permission.

Parameters

namestringRequired: Up to 200 characters; longer names are cut.
descriptionstring: Up to 1,000 characters. Leave it out to keep the current one.

Returns { "success": true }.

Errors

HTTP	Code	When
400	`name_required`	No name.
400	`invalid_field`	`name` or `description` is a list or object.
400	`list_not_found`	The id isn’t a whole number.
404	`list_not_found`	No list with this id on your account.
500	`update_failed`	We couldn’t save the list. Retry.

curl -X PATCH "https://api.tryready.com/lists/31" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Oak St open house"
  }'

const res = await fetch('https://api.tryready.com/lists/31', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Oak St open house"
  }),
});
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.patch(
    "https://api.tryready.com/lists/31",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "name": "Oak St open house"
    },
    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
}

#Delete a list

Deletes a list of either kind. Its contacts stay in your account; only their place in the list goes. Campaigns that used the list lose it as their audience. On a smart list we also take its smartlist-<id> tag off your contacts. Needs the manage_campaigns permission.

Parameters

forcestring · query: Send 1 to delete a list that unsent campaigns still send to. Those campaigns then won’t send.

Returns { "success": true }.

Errors

HTTP	Code	When
400	`list_not_found`	The id isn’t a whole number.
404	`list_not_found`	No list with this id on your account.
409	`list_in_use`	Another smart list’s rules use this list. Change those rules first; `force` doesn’t skip this.
409	`list_in_use`	A draft, scheduled or paused campaign sends to this list, and you didn’t send `force=1`. The body has a `campaigns` list with each one’s `id`, `name` and `status`.
500	`delete_failed`	Nothing was deleted. Retry.

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

const res = await fetch('https://api.tryready.com/lists/31', {
  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/lists/31",
    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_code": "list_in_use",
  "code": "list_in_use",
  "error": "This Smart List is the audience for a campaign that hasn't sent yet: Spring promo (scheduled). If you delete it, that campaign won't send.",
  "campaigns": [
    {
      "id": 77,
      "name": "Spring promo",
      "status": "scheduled"
    }
  ]
}

#Add contacts to a list

Adds your contacts to a list by id, up to 50,000 at a time. Works on both kinds of list. Ids that aren’t contacts on your account are skipped, and adding someone twice is safe. Needs the edit_contacts permission.

Parameters

contact_idsinteger[]Required: The contacts to add. You can send one id as contact_id instead.

Returns

addedinteger: Contacts newly added. Ones already in the list aren’t counted.
totalinteger | null: How many contacts are in the list now. null on a smart list when your seat only sees its assigned contacts.

Errors

HTTP	Code	When
400	`invalid_contacts`	No ids, more than 50,000, or none of them is a valid id.
400	`invalid_field`	`contact_ids` isn’t a list, or `contact_id` is a list.
400	`list_not_found`	The list id isn’t a whole number.
404	`list_not_found`	No list with this id on your account.
500	`list_total_unconfirmed`	The contacts were added, but we couldn’t count the list after.
500	`add_failed`	We couldn’t add the contacts. Retrying is safe.

curl -X POST "https://api.tryready.com/lists/31/add-contacts" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      101,
      102
    ]
  }'

const res = await fetch('https://api.tryready.com/lists/31/add-contacts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
      101,
      102
    ]
  }),
});
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.post(
    "https://api.tryready.com/lists/31/add-contacts",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "contact_ids": [101, 102]
    },
    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,
  "added": 2,
  "total": 60
}

#Add one contact or phone number to a list

Adds one contact by id, or by phone number. With a phone number and no contact_id, we use your contact with that number, or make a new contact for it, then add it. Needs the edit_contacts permission.

Parameters

contact_idinteger: The contact to add.
phonestring: A phone number, used when there is no contact_id.

Returns added and total, as Add contacts to a list does.

Errors

HTTP	Code	When
400	`invalid_contacts`	No usable `contact_id` and no `phone`.
400	`invalid_phone`	The phone number isn’t one we can read.
400	`invalid_field`	`contact_id` or `phone` is a list or object.
400	`list_not_found`	The list id isn’t a whole number.
404	`list_not_found`	No list with this id on your account.
500	`list_total_unconfirmed`	The contact was added, but we couldn’t count the list after.
500	`add_failed`	We couldn’t add the contact. Retrying is safe.

curl -X POST "https://api.tryready.com/lists/31/add-contact" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15125550188"
  }'

const res = await fetch('https://api.tryready.com/lists/31/add-contact', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phone": "+15125550188"
  }),
});
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.post(
    "https://api.tryready.com/lists/31/add-contact",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "phone": "+15125550188"
    },
    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,
  "added": 1,
  "total": 61
}

#Remove contacts from a list

Takes contacts out of a list, up to 50,000 at a time. This is the only route that does. The contacts stay in your account. Needs the edit_contacts permission.

On a smart list, this removes contacts added by either add route (Add contacts to a list or Add contacts to a smart list). A contact the list’s rules still match stays in the list, and still_matching tells you how many did.

Parameters

contact_idsinteger[]Required: The contacts to remove.

Returns

totalinteger: How many contacts are in the list now.
still_matchinginteger: How many of the contacts you sent are still in a smart list because its rules match them. Always 0 on a hand-picked list. null when we couldn’t work it out.

Errors

HTTP	Code	When
400	`invalid_contacts`	No ids, more than 50,000, or none of them is a valid id.
400	`invalid_field`	`contact_ids` isn’t a list.
400	`list_not_found`	The list id isn’t a whole number.
404	`list_not_found`	No list with this id on your account.
500	`list_total_unconfirmed`	The contacts were removed, but we couldn’t count the list after.
500	`remove_failed`	We couldn’t remove the contacts. Retrying is safe.

curl -X POST "https://api.tryready.com/lists/31/remove-contacts" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      101,
      102
    ]
  }'

const res = await fetch('https://api.tryready.com/lists/31/remove-contacts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
      101,
      102
    ]
  }),
});
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.post(
    "https://api.tryready.com/lists/31/remove-contacts",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "contact_ids": [101, 102]
    },
    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,
  "total": 59,
  "still_matching": 0
}

#Preview a smart list

Counts how many of your contacts a set of rules matches, without saving anything. Use it to check rules before you create a smart list. Needs the edit_contacts permission.

Parameters

filter_rulesobject[]: An array of rules. See filter_rules for the shape. No rules, or a value that isn’t a list, matches nobody: count is 0, and a top-level note says no rules were read.
include_sampleboolean: Also return up to 5 matching contacts, newest first.

Returns

countinteger: How many contacts match.
sampleobject[]: Only with include_sample. Each has id, first_name, last_name and phone.

Errors

HTTP	Code	When
400	`segment_rule_unsupported`	A rule names a field or operator we don’t support.
400	`invalid_field`	`include_sample` is a list or object.
503	`segment_preview_failed`	We couldn’t count the matching contacts. Retry.

curl -X POST "https://api.tryready.com/segments/preview" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter_rules": [
      {
        "field": "tags",
        "operator": "contains",
        "value": "vip"
      },
      {
        "field": "state",
        "operator": "equals",
        "value": "TX"
      }
    ],
    "include_sample": true
  }'

const res = await fetch('https://api.tryready.com/segments/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter_rules": [
      {
        "field": "tags",
        "operator": "contains",
        "value": "vip"
      },
      {
        "field": "state",
        "operator": "equals",
        "value": "TX"
      }
    ],
    "include_sample": true
  }),
});
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.post(
    "https://api.tryready.com/segments/preview",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "filter_rules": [
            {
                "field": "tags",
                "operator": "contains",
                "value": "vip"
            },
            {
                "field": "state",
                "operator": "equals",
                "value": "TX"
            }
        ],
        "include_sample": True
    },
    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": {
    "count": 412,
    "sample": [
      {
        "id": 2210,
        "first_name": "Dana",
        "last_name": "Reyes",
        "phone": "+12145550147"
      }
    ]
  }
}