Smart Lists

A smart list is a saved audience. The paths say /segments for historical reasons. A smart list made here is filter rules, like "tagged vip and in Texas", so the list updates as your contacts change. A fixed list of contacts made under Contact lists shows here too, with the same id. Pass its id as segment_id to a campaign or a drip campaign.

#The Smart list object

idinteger: The list id. Pass it as segment_id.
namestring: The list’s name.
descriptionstring: Your description, or "".
filter_rulesstring | null: The rules, as a JSON-encoded string of rule objects. null on a fixed list. When you send rules, send a real array.
Child attributes
A rule is {"field": "...", "operator": "...", "value": "..."}. A contact must match every rule. A rule with a field or operator we don’t support is refused with segment_rule_unsupported, so a typo never sends to everyone.

tags: contains, not_contains, is_any_of, is_none_of (comma separated), exists, not_exists.

pipeline_stage, status: equals, not_equals, is_any_of, is_none_of, exists, is_empty.

first_name, last_name, company_name, city, state, postal_code, source: equals, not_equals, contains, not_contains, is_any_of.

email: equals, not_equals, contains, not_contains, exists, is_empty.

score: greater_than, less_than, equals, gte, lte, between ("40,80").

created_at: after, before, days_ago_more, days_ago_less.

last_activity (Last edited: when the contact was last edited, its updated_at; any edit, tag or import counts, and it is not the last text or call. To filter by the last text, use last_activity on List contacts): after, before, days_ago_more, days_ago_less.

For after and before, send ISO 8601 or YYYY-MM-DD; a date alone is midnight UTC, so after includes that day and before leaves it out.

custom_field: add key (the field name) or field_id; operators equals, not_equals, contains, not_contains, is_set, is_empty.
contact_countinteger | null: How many contacts are in the list. null when your seat only sees its assigned contacts.
is_dynamicinteger: In List smart lists, 1 for a rules list and 0 for a fixed list of contacts. The other endpoints return the stored value, which is 0 for a list made with POST /segments. Don’t use it to tell the two apart outside List smart lists.
created_atstring: When the list was made, ISO 8601.

#List smart lists

Every smart list on your account, newest first, with how many contacts are in each. Needs the view_contacts permission.

Returns a list of Smart list objects in data.

Errors

HTTP	Code	When
500	`segments_read_failed`	We couldn’t read your lists. Retry.
500	`segments_count_failed`	We couldn’t count the contacts in your lists. Retry.

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

const res = await fetch('https://api.tryready.com/segments', {
  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/segments",
    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": [
    {
      "id": 23,
      "name": "Texas VIPs",
      "description": "",
      "filter_rules": "[{\"field\":\"tags\",\"operator\":\"contains\",\"value\":\"vip\"},{\"field\":\"state\",\"operator\":\"equals\",\"value\":\"TX\"}]",
      "contact_count": 412,
      "is_dynamic": 1,
      "created_at": "2026-10-02T14:11:09.000Z"
    }
  ]
}

#Get a smart list

One smart list with its rules. Needs the view_contacts permission.

Errors

HTTP	Code	When
400	`invalid_field`	The id isn’t a positive whole number.
404	`segment_not_found`	No smart list with this id on your account.

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

const res = await fetch('https://api.tryready.com/segments/23', {
  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/segments/23",
    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}')

#List contacts in a smart list

The contacts the list matches right now, most recently updated first. Needs the view_contacts permission.

Parameters

limitinteger · queryDefault 50Max 1000
offsetinteger · queryDefault 0
afterstring · query: The next_cursor of the previous page. Reads the page that follows it, however far into a large list; use it instead of offset to walk a list of hundreds of thousands. offset is ignored when after is sent.
ids_only, ids_limitinteger · query: With ids_only=1, returns {ids, has_more} instead of contacts: up to ids_limit contact ids, newest first (max 100,000).

Returns a list of Contact objects in data.

Returns

total, total_is_estimateinteger, boolean: How many match. On very large accounts the total can be an estimate. total is null when we could not count them in time; fetch again for the count.
next_cursorstring or null: Send it as after to get the next page. null when this page was shorter than limit, which means the list is read to the end.

Errors

HTTP	Code	When
400	`invalid_field`	The id isn’t a positive whole number.
404	`segment_not_found`	No smart list with this id on your account.
400	`invalid_field`	`after` isn’t a `next_cursor` from an earlier page. Start again without it.
500	`segment_rules_damaged`	The list’s saved rules can’t be read. Send new `filter_rules` with Update a smart list.
503	`segment_read_failed`	We couldn’t read the list just now. Retry.

curl "https://api.tryready.com/segments/23/contacts?limit=100&offset=0" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/segments/23/contacts?limit=100&offset=0', {
  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/segments/23/contacts?limit=100&offset=0",
    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}')

#Create a smart list

Saves filter rules as a smart list. Returns 201. The same name, description and rules again within 2 minutes returns the first one with deduped: true. Needs the edit_contacts permission.

Parameters

namestringRequired
filter_rulesobject[]: An array of rules. See filter_rules for the shape. Leave it out to make an empty list, then fill it with Add contacts to a smart list.
descriptionstring

Returns a Smart list object in data, plus deduped: true when it’s a repeat.

Errors

HTTP	Code	When
400	`segment_name_required`	No name.
400	`invalid_field`	`filter_rules` isn’t a list.
400	`segment_rule_unsupported`	A rule names a field or operator we don’t support.
500	`segment_create_failed`	We couldn’t confirm the list was saved. List your smart lists before you try again.
503	`segment_count_failed`	We couldn’t count the list’s contacts, so nothing was saved. Retry.

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

const res = await fetch('https://api.tryready.com/segments', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Texas VIPs",
    "filter_rules": [
      {
        "field": "tags",
        "operator": "contains",
        "value": "vip"
      },
      {
        "field": "state",
        "operator": "equals",
        "value": "TX"
      }
    ]
  }),
});
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",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "name": "Texas VIPs",
        "filter_rules": [
            {
                "field": "tags",
                "operator": "contains",
                "value": "vip"
            },
            {
                "field": "state",
                "operator": "equals",
                "value": "TX"
            }
        ]
    },
    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}')

#Update a smart list

Changes the name, description or rules. Sending filter_rules to a fixed list turns it into a rules list: its contacts are then the ones the rules match. Needs the edit_contacts and manage_campaigns permissions. If the save landed but we couldn’t read the list back, you get 200 with data: null and warning_code: "SEGMENT_REREAD_FAILED": the change is saved, so get the list.

Parameters

namestring
filter_rulesobject[]: Replaces the rules.
descriptionstring

Errors

HTTP	Code	When
400	`segment_name_required`	`name` is empty.
400	`nothing_to_update`	No `name`, `description` or `filter_rules` sent.
400	`invalid_field`	`filter_rules` isn’t a list.
400	`segment_rule_unsupported`	A rule names a field or operator we don’t support.
400	`invalid_field`	The id isn’t a positive whole number.
404	`segment_not_found`	No smart list with this id on your account.
500	`segment_update_failed`	Nothing was saved. Retry.
500	`segment_update_unconfirmed`	We couldn’t confirm the save. Get the list before you try again.

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

const res = await fetch('https://api.tryready.com/segments/23', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter_rules": [
      {
        "field": "tags",
        "operator": "contains",
        "value": "vip"
      }
    ]
  }),
});
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/segments/23",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "filter_rules": [
            {
                "field": "tags",
                "operator": "contains",
                "value": "vip"
            }
        ]
    },
    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}')

#Add contacts to a smart list

The same as Add contacts to a list, with segment_ error codes; new code should use /lists. Puts specific contacts in a list, up to 50,000 at a time. On a rules list we tag them so the list includes them. Adding someone twice is safe. Needs the edit_contacts permission.

Parameters

contact_idsinteger[]: Required unless you send all.
allboolean: true adds every contact you can see instead of a list of ids. Campaigns that send to this list then reach all of them, and so does any drip you later fill from it. There is no count beforehand and no undo token. On a rules list, take them back out by removing the smartlist-<id> tag with Tag or untag many contacts, which returns an undo_token.

Returns

addedinteger: Contacts added. With all: true on a rules list the answer is 202 with queued: true, job_id and tag instead, and the contacts are tagged in the background.
contact_countinteger | null: How many are in the list now. null on a rules list when the count couldn’t be read, or when your seat only sees its assigned contacts; the add still worked.
tagstring: Rules lists only: the tag the contacts got, smartlist-<id>.

Errors

HTTP	Code	When
400	`no_contacts_selected`	No contacts.
400	`too_many_contacts`	More than 50,000.
400	`invalid_field`	The id isn’t a positive whole number.
404	`segment_not_found`	No smart list with this id on your account.
500	`segment_rules_damaged`	The contacts got the tag but the list’s rules can’t be read, so they aren’t in it. Send new `filter_rules` with Update a smart list, then add them again.
500	`segment_add_failed`	The add didn’t finish. Adding the same contacts again is safe.

curl -X POST "https://api.tryready.com/segments/23/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/segments/23/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/segments/23/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,
  "contact_count": 414
}

#Delete a smart list

The same as Delete a list, with segment_ error codes; new code should use /lists. Deletes the list. Your contacts stay; the ones you added by hand lose its smartlist-<id> tag. Needs the edit_contacts and manage_campaigns permissions.

Parameters

forceinteger · query: 1 deletes the list even when campaigns that haven’t sent yet use it. Those campaigns then fail.

Returns { "success": true }.

Errors

HTTP	Code	When
400	`invalid_field`	The id isn’t a positive whole number.
404	`segment_not_found`	No smart list with this id on your account.
409	`segment_in_use`	Draft, scheduled or paused campaigns send to this list. `campaigns` lists them (`id`, `name`, `status`). Send `?force=1` to delete anyway. Delete a list answers the same case as `list_in_use`.
409	`list_in_use`	Another smart list’s rules use this list. Change those rules first; `force` doesn’t override this.
500	`segment_delete_failed`	Nothing was deleted. Retry.

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

const res = await fetch('https://api.tryready.com/segments/23', {
  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/segments/23",
    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
}