Number health

How your numbers deliver, and the account settings that keep texts going out when a number struggles. Every role on the account can read these.

#Get a number’s delivery

How well one number’s texts deliver: rates over the last day, week and month, each carrier over the last week, and its most common carrier errors with what they mean.

Path parameters

idintegerRequired: The number id.

Returns

phoneobject: { id, phone_number, friendly_name, status, health_score, total_delivered, total_failed, total_spam_reports, created_at }.
delivery_rate_24hobject: Texts from this number in the last 24 hours: delivered, failed, blocked, pending, total, and delivered_pct and failed_pct over the texts with a final status (null when none has one). delivery_rate_7d and delivery_rate_30d are the same over 7 and 30 days.
carrier_breakdown_7d[]object[]: Each { carrier, total, delivered, failed, pending }. carrier is the display name (T-Mobile, AT&T, Unknown carrier), not the slug the other carrier breakdowns return.
top_errors_7d[]object[]: Up to 5, most failures first. Each { error_name, carrier, count, explanation }. explanation is { title, body, reason, severity, fix_action }, or null when Ready has no explanation for that error.
sms_spamobject: The last saved web spam check: { spam_detected, reports, score, checked_at }. Run a new one with Check a number for spam reports.

Errors

HTTP	Code	When
404	`NUMBER_NOT_FOUND`	No number with this id on your account.
500	`DELIVERABILITY_LOAD_FAILED`	Ready couldn’t load the figures. Try again in a minute.

curl "https://api.tryready.com/v1/numbers/2647/deliverability" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers/2647/deliverability', {
  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/v1/numbers/2647/deliverability",
    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,
  "phone": {
    "id": 2647,
    "phone_number": "+14155550100",
    "friendly_name": "Front desk",
    "status": "active",
    "health_score": 100,
    "total_delivered": 9120,
    "total_failed": 233,
    "total_spam_reports": 0,
    "created_at": "2026-07-29T00:12:04.512Z"
  },
  "delivery_rate_24h": {
    "delivered": 812,
    "failed": 21,
    "blocked": 0,
    "pending": 4,
    "total": 837,
    "delivered_pct": 97.5,
    "failed_pct": 2.5,
    "pending_pct": 0.5
  },
  "delivery_rate_7d": {
    "delivered": 812,
    "failed": 21,
    "blocked": 0,
    "pending": 4,
    "total": 837,
    "delivered_pct": 97.5,
    "failed_pct": 2.5,
    "pending_pct": 0.5
  },
  "delivery_rate_30d": {
    "delivered": 812,
    "failed": 21,
    "blocked": 0,
    "pending": 4,
    "total": 837,
    "delivered_pct": 97.5,
    "failed_pct": 2.5,
    "pending_pct": 0.5
  },
  "carrier_breakdown_7d": [
    {
      "carrier": "T-Mobile",
      "total": 402,
      "delivered": 396,
      "failed": 5,
      "pending": 1
    }
  ],
  "top_errors_7d": [
    {
      "error_name": "EC_UNKNOWN_SUBSCRIBER",
      "carrier": "T-Mobile",
      "count": 5,
      "explanation": {
        "title": "Bad phone number",
        "body": "This number is not a working mobile number, or it is missing the country code. Check the number with the contact, and clean your list before you send again.",
        "reason": "Recipient's phone number is not valid. Correct it before you send again.",
        "severity": "data",
        "fix_action": "scrub_list"
      }
    }
  ],
  "sms_spam": {
    "spam_detected": false,
    "reports": 0,
    "score": 0,
    "checked_at": "2026-11-10T08:00:12.004Z"
  }
}

#Check a number for spam reports

Searches the web for spam reports about one number and saves the result on the number (spam on Get a number). A number checked recently answers the saved result with cached: true instead of searching again.

Path parameters

idintegerRequired: The number id.

Returns

data.statusstring: clean, low_risk, medium_risk, high_risk, or unknown when Ready couldn’t finish the search. unknown isn’t a clean result, and isn’t saved. On a cached answer, read spam_detected and reports instead.
data.spam_scorenumber: Higher is worse.
data.text_reportsinteger: Reports about texts.
data.call_reportsinteger: Reports about calls.
data.spam_sources[]object[]: Up to 8 of the pages that mention the number.
data.checked_atstring: When it was checked, ISO 8601.

Errors

HTTP	Code	When
404	`NUMBER_NOT_FOUND`	No number with this id on your account.
500	`SPAM_CHECK_FAILED`	Ready couldn’t run the check. Try again in a minute.

curl "https://api.tryready.com/v1/numbers/2647/spam-check" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers/2647/spam-check', {
  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/v1/numbers/2647/spam-check",
    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": {
    "checked": true,
    "data_complete": true,
    "phone_number": "+14155550100",
    "spam_score": 0,
    "status": "clean",
    "total_web_mentions": 0,
    "text_reports": 0,
    "call_reports": 0,
    "recent_reports": 0,
    "distinct_sources": 0,
    "spam_sources": [],
    "checked_at": "2026-11-11T18:00:00.000Z"
  }
}

#Texts sent per number, last 7 days

How many texts each of your numbers sent on each of the last 7 UTC calendar days (a day ends at midnight UTC, not in your account’s time zone), oldest first, the chart on the Numbers page. Includes your sub-accounts’ numbers.

Returns

sparkobject: Keyed by phone number. Each value is 7 counts, oldest day first. A number that sent nothing in the 7 days isn’t listed.

Errors

HTTP	Code	When
500	no code	Ready couldn’t load the counts. Try again.

curl "https://api.tryready.com/v1/numbers/sent-7d" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers/sent-7d', {
  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/v1/numbers/sent-7d",
    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,
  "spark": {
    "+14155550100": [
      120,
      98,
      143,
      0,
      0,
      87,
      131
    ]
  }
}

#Get number protection

Whether Ready replaces a sending number automatically when it gets spam reports. A replacement is a new number with its own monthly fee, so the account holder turns this on in the app.

Returns

data.enabledboolean: Whether Ready replaces a flagged number now.
data.sourcestring: explicit_opt_in, explicit_opt_out, not_opted_in or unknown.
data.attestedboolean: Whether the account holder has authorized replacements.
data.attested_atstring | null: When they did.

Errors

HTTP	Code	When
500	`SETTING_LOAD_FAILED`	Ready couldn’t load the setting. Try again in a minute.

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

const res = await fetch('https://api.tryready.com/v1/sms-protection', {
  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/v1/sms-protection",
    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": {
    "enabled": false,
    "source": "not_opted_in",
    "explicitly_enabled": false,
    "attested": false,
    "attested_at": null,
    "attestation_required_to_enable": true,
    "attestation_text": "I authorize a replacement number to be bought on my behalf when one of mine gets flagged. ...",
    "replacement_price_cents": 200
  }
}

#Get Smart delivery

Smart delivery (the smart-routing endpoint) moves a text to another of your numbers when its own number is delivering badly. On unless you turned it off.

Returns

data.enabledboolean: The setting now.

Errors

HTTP	Code	When
500	`SETTING_LOAD_FAILED`	Ready couldn’t load the setting. Try again in a minute.

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

const res = await fetch('https://api.tryready.com/v1/smart-routing', {
  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/v1/smart-routing",
    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": {
    "enabled": true
  }
}

#Turn Smart delivery on or off

Turns Smart delivery on or off for the account. It only moves texts between numbers you already have, so it costs nothing. Needs the manage_phones permission.

Body parameters

enabledbooleanRequired: true or false.

Returns

data.enabledboolean: The setting now.

Errors

HTTP	Code	When
400	`toggle_invalid`	`enabled` is missing, or isn’t `true` or `false`.
500	`SETTING_SAVE_UNCONFIRMED`	Ready couldn’t confirm the change. Read it back to check.

curl -X PUT "https://api.tryready.com/v1/smart-routing" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

const res = await fetch('https://api.tryready.com/v1/smart-routing', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "enabled": false
  }),
});
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/v1/smart-routing",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "enabled": False
    },
    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": {
    "enabled": false
  }
}

#Get local presence

Whether texts and calls go out from a number that is local to the contact, when your account has one. On unless you turned it off.

Returns

data.enabledboolean: The setting now.
data.opt_inboolean: false today. When true, local presence is on only for an account that turned it on itself.
data.price_per_text_usdnumber: What local presence costs the account for each segment of a delivered text, in dollars. A two-segment text costs twice this. 0 while it isn’t charged.

Errors

HTTP	Code	When
500	`SETTING_LOAD_FAILED`	Ready couldn’t load the setting. Try again in a minute.

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

const res = await fetch('https://api.tryready.com/v1/local-presence', {
  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/v1/local-presence",
    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": {
    "enabled": true,
    "opt_in": false,
    "price_per_text_usd": 0
  }
}

#Turn local presence on or off

Turns local presence on or off for the account. Off, a text or call to someone you haven’t reached yet goes out from the account’s default number instead, and from_strategy local does the same; a send that asks for even, deliverability or random still spreads across all your numbers. Each change is recorded in the account’s history, and sending it again with the value already set changes nothing. Needs the manage_phones permission.

Body parameters

enabledbooleanRequired: true or false.

Returns

data.enabledboolean: The setting now.

Errors

HTTP	Code	When
400	`toggle_invalid`	`enabled` is missing, or isn’t `true` or `false`.
403	`products_locked`	Your agency locked this switch for your account. Ask your agency to change it. Nothing changed.
500	`SETTING_SAVE_UNCONFIRMED`	Ready couldn’t confirm the change. Read it back to check.

curl -X PUT "https://api.tryready.com/v1/local-presence" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

const res = await fetch('https://api.tryready.com/v1/local-presence', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "enabled": false
  }),
});
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/v1/local-presence",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "enabled": False
    },
    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": {
    "enabled": false
  }
}