Ban list

The ban list is a list of phone numbers Ready never texts. It isn’t the same as an opt-out. An opt-out lives on a contact (a STOP reply, dnd_sms or an opted-out status). The ban list is keyed by phone number, so it works for numbers that aren’t contacts and it outlasts a deleted contact. Every STOP reply is also saved here, so the opt-out survives if the contact is deleted. A contact imported or synced later for a banned number comes in opted out.

A text to a banned number is refused and not charged. A number you added answers 403 dnc_list; a number that texted STOP answers 403 opt_out_locked. Check one number answers opted_out: true for both.

#The Ban list entry object

idinteger: The entry id. Pass it to Remove a number.
phoneE.164 string: The blocked number.
reasonstring: Your reason, or Manually added or CSV upload. A STOP row carries a code such as opt_out_locked.
sourcestring: manual (added one at a time), bulk (a CSV upload) or sms_optout (the person texted STOP). A ban added on top of a saved STOP ends in +stop, such as manual+stop.
added_atstring: When it was added, ISO 8601.
source_label, reason_labelstring, string | null: How the dashboard names the source and reason, such as Texted STOP. Only in List the ban list.
removableboolean: false for a STOP row, which only the person can undo by texting START, and for a ban added over a saved STOP. Only in the list.
needs_attestationboolean: true when the reason says "do not call" or "DNC", so removing it needs attested: true. Only in the list.

#List the ban list

The newest entries on your ban list, newest first, and how many there are in all. Pages with offset: send the next offset to get the next page. q finds numbers containing those digits, and matched says how many did. Needs the view_contacts permission.

Parameters

limitinteger · queryDefault 200Max 500
offsetinteger · queryDefault 0: How many entries to skip, newest first.
qstring · queryMax 40 characters: Keeps only numbers containing these digits. Anything that isn’t a digit is ignored, so a q with no digits matches nothing.

Returns

data.rowsobject[]: Ban list entry objects.
data.totalinteger: How many numbers are on the list.
data.matchedinteger: How many numbers match q. The same as total when you send no q.
data.offsetinteger: The offset this page starts at.

Errors

HTTP	Code	When
500	`internal_error`	The list couldn’t be read. Retry.

curl "https://api.tryready.com/contacts/ban-list?limit=200" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/contacts/ban-list?limit=200', {
  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/contacts/ban-list?limit=200",
    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": {
    "rows": [
      {
        "id": 8812,
        "phone": "+12125550143",
        "reason": "Asked not to be texted on a call",
        "source": "manual",
        "added_at": "2026-11-02T15:04:11.000Z",
        "source_label": "Manually added",
        "reason_label": null,
        "removable": true,
        "needs_attestation": false
      },
      {
        "id": 8790,
        "phone": "+13055550178",
        "reason": "opt_out_locked",
        "source": "sms_optout",
        "added_at": "2026-10-28T09:12:40.000Z",
        "source_label": "Texted STOP",
        "reason_label": "Texted STOP",
        "removable": false,
        "needs_attestation": false
      }
    ],
    "total": 2
  }
}

#Export the ban list

Your whole ban list as a CSV file, oldest first, with the columns phone, reason (the words the dashboard shows: a row Ready added says why, such as Texted STOP, where the list’s reason field carries a code), source (the dashboard label, such as Texted STOP) and added_at. A list longer than 500,000 numbers is refused, never cut short. Counts toward your account’s 6 exports an hour, shared with your other exports. Needs the view_contacts permission.

Errors

HTTP	Code	When
422	`too_many_rows`	More than 500,000 numbers. Page the list with `offset` instead.
429	`rate_limited`	You’ve used this hour’s exports.
500	`internal_error`	The file couldn’t be built. Retry.

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

const res = await fetch('https://api.tryready.com/contacts/ban-list/export', {
  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/contacts/ban-list/export",
    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:

phone,reason,source,added_at
+13055550178,Texted STOP,Texted STOP,2026-10-28T09:12:40.000Z
+12125550143,Asked not to be texted on a call,Manually added,2026-11-02T15:04:11.000Z

#Add a number

Puts one number on the ban list. Adding a number that is already there succeeds with already_listed: true and adds no second entry. Needs the edit_contacts permission.

Parameters

phonestringRequired: A 10-digit US number or an E.164 number, up to 40 characters. A number with fewer than 10 digits is refused.
reasonstring: Up to 200 characters. Defaults to Manually added. A reason that says "do not call" or "DNC" makes the entry need attested: true to remove.

Returns

data.entryobject | null: The entry, without the list-only fields. null in the rare case the number was saved but couldn’t be read back; it is still blocked.
data.already_listedboolean: true if the number was already on the list. Its reason is kept, unless the earlier entry was a STOP: then your ban is added on top and the STOP is kept underneath.

Errors

HTTP	Code	When
400	`invalid_field`	No `phone`, or a field is too long or not text.
400	`invalid_phone`	Not a full phone number.
500	`internal_error`	Not added. Retry.

curl -X POST "https://api.tryready.com/contacts/ban-list" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+12125550143",
    "reason": "Asked not to be texted on a call"
  }'

const res = await fetch('https://api.tryready.com/contacts/ban-list', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phone": "+12125550143",
    "reason": "Asked not to be texted on a call"
  }),
});
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/contacts/ban-list",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "phone": "+12125550143",
        "reason": "Asked not to be texted on a call"
    },
    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": {
    "entry": {
      "id": 8812,
      "phone": "+12125550143",
      "reason": "Asked not to be texted on a call",
      "source": "manual",
      "added_at": "2026-11-02T15:04:11.000Z"
    },
    "already_listed": false
  }
}

#Upload a CSV of numbers

Adds every number in a CSV file to the ban list. Send a multipart form with the file in file, up to 10 MB and 50,000 rows. A file over either limit is refused and nothing is added. Uploading the same file again adds nothing new. Needs the edit_contacts permission.

Which column is read

The column whose header names a phone, such as phone, mobile, cell, telephone or phone number; else a column named number. With no header row, the first column is read. A file with a header but none of those columns has no numbers. Blank rows aren’t counted. A cell that isn’t a full phone number is skipped.

Parameters

filefile · multipartRequired: A CSV file, one number per row.

Returns

data.addedinteger: Numbers newly blocked, including ones added on top of a saved STOP.
data.skippedinteger: Rows not added: already on the list, repeated in the file, or not a phone number.
data.total_in_fileinteger: Data rows in the file, header and blank rows not counted.

Errors

HTTP	Code	When
400	`file_missing`	No file, or an empty one.
400	`upload_failed`	The upload couldn’t be read. Send it again.
413	`file_too_large`	Over 10 MB. Split the file.
413	`too_many_rows`	More than 50,000 rows. Split the file.
422	`no_numbers`	No phone numbers found in the file.
429	`rate_limited`	Too many requests in the last minute.
500	`internal_error`	The upload stopped partway. Some numbers may already be added, so check the list before you upload again.

curl -X POST "https://api.tryready.com/contacts/ban-list/bulk" \
  -H "X-API-Key: $READY_API_KEY" \
  -F "file=@ban-list.csv"

Returns:

{
  "success": true,
  "data": { "added": 1180, "skipped": 20, "total_in_file": 1200 }
}

#Remove a number

Takes an entry off the ban list, so the number can be texted again. A number that texted STOP can’t be removed: only the person can undo that, by texting START. Removing a ban you added on top of a saved STOP lifts your ban but keeps the STOP, so the number stays blocked. Every removal is recorded with who removed it. Needs the edit_contacts permission.

Parameters

idinteger · pathRequired: The entry id from List the ban list.
attestedboolean: Send true to confirm the person gave consent again. Required when the entry’s reason says "do not call" or "DNC" (needs_attestation).

Returns data.deleted: true.

Errors

HTTP	Code	When
400	`invalid_field`	`id` isn’t a whole number, or `attested` isn’t a boolean.
400	`attestation_required`	A "do not call" entry, sent without `attested: true`.
404	`not_found`	No entry with this id on your list, or it was already removed.
409	`consumer_opt_out`	The number texted STOP. It stays on the list.
500	`internal_error`	Not removed. Retry.

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

const res = await fetch('https://api.tryready.com/contacts/ban-list/8812', {
  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/ban-list/8812",
    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": { "deleted": true }
}