Ready API reference
Send texts, manage contacts and numbers, and get events by webhook. JSON over HTTPS.
#Introduction
Every path is relative to this base URL. HTTPS only: http:// redirects, and a redirected POST can lose its body.
https://api.tryready.com
Send JSON (Content-Type: application/json), up to 1 MB, or 50 MB on /v1/messages/bulk (413 PAYLOAD_TOO_LARGE). Malformed JSON returns 400 INVALID_JSON. A response has "success": true and the result in data, with paging fields next to it on lists; a few put fields at the top level, and each endpoint’s Returns says where. An error has "success": false: see Errors.
/v1/* is versioned. The other paths here are supported, but new endpoints go under /v1. Other paths the dashboard uses may accept an API key today, but they aren’t part of the API, can change without notice, and will be closed to API keys.
#Quickstart
You need a Ready account and a phone that can receive texts. First, in the app, click Activate number in the banner at the top (new accounts see this step when they first sign in): pick an area code, add a card and click Activate. That gives you a number to send from.
Node examples use built-in fetch and top-level await (an .mjs file, Node 20+). Python examples use requests.
#Get an API key
Open Settings → Developers, click Create key, keep Live, click Create and copy the key (shown once, starts with
rsms_).If you already have a live key, the new one is added and the old one keeps working until you click Revoke on its row (API keys).export READY_API_KEY="rsms_your_key_here"#Check the key works
401 AUTH_REQUIRED: the variable is usually empty.401 INVALID_API_KEY: the key was revoked, mistyped or cut off.curl "https://api.tryready.com/v1/account" \ -H "X-API-Key: $READY_API_KEY"const res = await fetch('https://api.tryready.com/v1/account', { 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/account", 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}')Sample values. Your own rates are under Your price in Settings → Billing.
{ "success": true, "data": { "balance_usd": 25, "balance_cents": 2500, "plan": null, "sms_rate_usd_per_segment": 0.0075, "carrier_fee_usd_per_segment": 0.0045, "compliance_usd_per_segment": 0.003, "mms_usd_per_message": 0.0305 } }#Send a text to your own phone
Put your own mobile number in
to. It’s one of your first 20 free sends, so the sample shows no carrier fee and the balance doesn’t move.A
200means Ready accepted the text, not that it was delivered. Storedata.message_id: delivery lookups and webhooks use it.In production, also send an
Idempotency-Keyheader on every send, so a retry never sends twice."consent_attested": trueis your promise that the recipient gave prior express written consent (TCPA). Your own phone is fine. Ready handlesSTOPand other opt-outs. See Compliance.curl -X POST "https://api.tryready.com/v1/messages" \ -H "X-API-Key: $READY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "to": "+12125550199", "body": "Hello from Ready", "consent_attested": true }'const res = await fetch('https://api.tryready.com/v1/messages', { method: 'POST', headers: { 'X-API-Key': process.env.READY_API_KEY, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "to": "+12125550199", "body": "Hello from Ready", "consent_attested": 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, uuid, requests r = requests.post( "https://api.tryready.com/v1/messages", headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())}, json={ "to": "+12125550199", "body": "Hello from Ready", "consent_attested": 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}'){ "success": true, "data": { "message_id": "179088672338905475132359", "segments": 1, "sent_body": "Hello from Ready Reply STOP to opt out.", "compliance_text_added": "Reply STOP to opt out.", "status": "queued", "sent_at": "2026-10-01T20:32:03.473Z", "balance_usd": 25 } }#Get delivery updates and replies
Point Ready at a public HTTPS URL that accepts
POST(a free request inspector works). The first time you save, the response includes your signing secret indata.secret: store it.Reply from your phone and an
inbound_replyevent arrives. Before going live, verify the signature on every event.curl -X PUT "https://api.tryready.com/v1/webhooks" \ -H "X-API-Key: $READY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://you.example.com/ready-webhook", "events": [ "message_delivered", "message_failed", "inbound_reply" ] }'const res = await fetch('https://api.tryready.com/v1/webhooks', { method: 'PUT', headers: { 'X-API-Key': process.env.READY_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://you.example.com/ready-webhook", "events": [ "message_delivered", "message_failed", "inbound_reply" ] }), }); 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/webhooks", headers={"X-API-Key": os.environ["READY_API_KEY"]}, json={ "url": "https://you.example.com/ready-webhook", "events": ["message_delivered", "message_failed", "inbound_reply"] }, 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}')#Go live
- Register your business and campaign (registration). Until then the limits in Sending caps apply.
- Buy more numbers: Phone numbers.
- Branch on error codes (Errors). Send an Idempotency-Key on every send.
- Subscribe to
contact_opted_outand keep your copy of opt-outs in sync.
#Authentication
#API keys
Send the key as X-API-Key: rsms_… or Authorization: Bearer rsms_…. If both are present, the bearer token is used. A client that only speaks HTTP Basic, like the Twilio SDK, can send the key as the password, with anything as the user name.
- Keys start with
rsms_and are shown once. Only the account owner or an admin can create one, and it acts with the owner’s permissions, except that a key can’t sign in or open dashboard sessions, change the login email or sign-in phone, add, remove or change cards, pay out partner earnings or change the payout bank, pause, resume or cancel the account, agree to or cancel paid iMessage lines, or turn off a compliance check (403 api_key_not_allowed). - To create, list, rotate or revoke keys, from the dashboard or over the API: API keys.
#Authentication errors
In error_code and code: 401 AUTH_REQUIRED (no key or an empty variable), 401 INVALID_API_KEY, 401 INVALID_TOKEN, 403 ACCOUNT_SUSPENDED, 503 AUTH_CHECK_UNAVAILABLE (nothing ran; retry).
X-API-Key: rsms_your_key_here
Authorization: Bearer rsms_your_key_here
{
"success": false,
"error": "Sign in to continue. For API calls, send your API key in the X-API-Key header.",
"code": "AUTH_REQUIRED",
"error_code": "AUTH_REQUIRED"
}
{
"success": false,
"error": "That API key isn't valid or was revoked. Create a new one in Settings > Developers > API keys.",
"code": "INVALID_API_KEY",
"error_code": "INVALID_API_KEY"
}
#Acting as a sub-account
Agencies add X-Sub-Account-Id: <sub-account id> to a /v1 API key request to run it as that sub-account: what you create is the sub-account’s, and whoever pays for the sub-account pays (you, for a sub-account created with billing: "agency"). Your own numbers aren’t visible while you act as a sub-account. To buy a number for one, call POST /v1/numbers/checkout then POST /v1/numbers, both with the header, and poll GET /v1/numbers/:id until it’s active.
Refusals run nothing: 400 invalid_sub_account_id (not a numeric id, also 0 or empty), 400 sub_account_header_not_supported (a path outside /v1), 400 sub_account_header_needs_api_key, 403 sub_account_forbidden (not a sub-account you manage, including your own id), 403 sub_account_suspended and 404 sub_account_not_found.
#Conventions
#Pagination
Lists are offset lists (limit and offset) or cursor lists (limit and before_id: pass the previous page’s next_before_id). Cursor lists ignore offset, so a client that sends it gets page one forever. GET /v1/calls takes an opaque cursor instead: pass the previous page’s next_cursor.
Stop when has_more is false, not on a short page or on next_before_id. /contacts has no has_more: stop on a page with fewer rows than limit.
Limits and edge cases
limitdefaults to 50 and is capped at 1,000 (500 for thread messages; 1000 for transactions, where the default is 20). Larger values are capped without an error, except onGET /v1/calls, where alimitabove 999 is refused with a400.0, negative or non-numeric values fall back to the default, except onGET /v1/calls, where a negative or non-numericlimitis refused with a400(0falls back to the default there too).offsetmust be a whole number, 0 or more. Other values return400 invalid_offseton/contactsand/conversations.next_before_idis set on the last page too, and isnullwhen the page is empty.has_morecan betrueon a page that is exactly full, so the last page may be empty.totalcan be an estimate on large or slow queries (on/contacts,total_is_estimateis thentrue), can be up to 2 minutes old, and can show 1 when nothing matches. Use it for display, not to end a loop.
| Endpoint | Style | Paging fields next to data | Max limit |
|---|---|---|---|
GET /contacts | offset | total, total_is_estimate | 1,000 |
GET /conversations | offset | has_more, total, total_capped, count_cap, counts | 1,000 |
GET /conversations/:id/messages | offset | none | 500 |
GET /billing/transactions | offset | total, summary | 1000 |
GET /sms/logs (older path, use GET /v1/messages) | offset | has_more (also as hasMore), total (always null) | 1,000 |
GET /v1/messages | cursor | has_more, next_before_id | 200 |
GET /v1/opt-outs | cursor | has_more, next_before_id | 500 (default 100) |
GET /v1/sub-accounts | cursor | has_more, next_before_id | 200 |
GET /v1/calls | cursor | has_more, next_cursor | 999 (default 25) |
GET /v1/messages?limit=200
GET /v1/messages?limit=200&before_id=<next_before_id>
# stop when has_more is false
#Rate limits
A 429 from these limits means nothing ran: wait Retry-After seconds and retry with the same Idempotency-Key. The sending caps (daily_cap, number_daily_cap, monthly_cap, ramp_cap) also answer 429 but have no Retry-After and won’t clear in a retry loop; on /v1/messages the warm-up and unregistered caps answer 409 RAMP_CAP_REACHED and 402 MONTHLY_CAP_REACHED instead: see When to retry and Sending caps.
| What | Limit | Counted | Over it |
|---|---|---|---|
Sending (/v1/messages, /sms/send) |
Paced to your carrier throughput for AT&T and unknown-carrier recipients (3 a second if your cap is unknown). Hard ceiling 6,000 sends a minute. Ready holds a request up to 1.5 s before refusing, for up to 40 waiting requests per server; past that a send is refused at once. | Per account (pacing is counted per server) | Pacing: 429 rate_limited, with Retry-After. The body has retry_after_ms and cap_per_sec; Retry-After is retry_after_ms rounded up to whole seconds. Ceiling: 429 rate_limited with no retry_after_ms; wait a minute. |
Every /v1 read and non-send write: account, balance, numbers, opt-outs, webhooks, calls and reports, plus bulk send, message history, validate and scrub (/v1/messages/bulk, GET /v1/messages, /v1/validate, /v1/scrub) |
About 120 requests a minute, plus 140 bulk calls a minute | Per account (the 120 is counted per server, so it’s approximate) | 429 rate_limited. Bulk also gets 429 throughput_exceeded, below. |
| Number purchase | /phone-numbers/checkout and /phone-numbers/buy: 20 a minute each. POST /v1/numbers/checkout and POST /v1/numbers: 120 a minute. Shared ceilings of 700 checkouts and 140 buys a minute. |
Per account | 429 rate_limited |
| Contact exports | 6 an hour, shared with the dashboard | Per account | 429 |
| Everything, as an outer ceiling | 1,200 requests a minute with a valid key, 300 without one | Per IP address | 429 RATE_LIMITED with retry_after_seconds |
Repeated 429s without a valid key (a mistyped key in a retry loop, for example) block the IP for 15 minutes or longer (403 IP_TEMPORARILY_BLOCKED). A key that already worked in the last hour skips the block. A key you just fixed waits it out like any other request, so stop the retry loop first. A dashboard session and an API key on the same account share the per-account limits.
Bulk isn’t faster. POST /v1/messages/bulk counts every recipient against the same per-second pace before it sends anything, and refuses an over-pace batch whole: 429 throughput_exceeded with Retry-After. Bulk counts every recipient on every carrier; single sends only count AT&T and unknown-carrier recipients, so bulk won’t get you past your carrier pace.
#Sending caps
- Trial: sends go out from a number on your account (
400 no_sender_numberwith no active number), and a card is required (402 CARD_REQUIRED). The first 20 sends are free, and they’re real texts. After that each send is billed at the unregistered rate (402 insufficient_balancewhen the balance can’t cover it; add funds under Settings → Billing, see Add money), up to the unregistered cap below. - Daily caps: none on your account unless Ready sets one (
429 daily_cap). You can cap a number yourself (429 number_daily_cap). Both reset at midnight Pacific time (America/Los_Angeles), whatever your account’s time zone. - Unregistered accounts created since June 23, 2026: 500 texts per 30-day cap window until they have an approved campaign and a paid number (
402 MONTHLY_CAP_REACHEDon/v1/messages). No daily cap. The send counter resets 30 days after its window starts, not on the first of the month; recent-send counts use the last 30 days. - Warm-up: 500 texts from brand approval until your first campaign is approved, and 500 for a later campaign’s first 2 business days (
409 RAMP_CAP_REACHED). Full volume unlocks once the first campaign is approved. Reviews run in sequence: the brand first, then Ready submits the campaign. - T-Mobile gives your brand a daily tier for texts to T-Mobile numbers (GET /v1/registration/throughput). Ready doesn’t hold or refuse
/v1/messagesor bulk sends for it, so a send over your tier isn’t refused by Ready.
Headers. Every response has X-RateLimit-Limit, X-RateLimit-Remaining (approximate) and X-RateLimit-Reset (Unix seconds) for the limit that applied. On sends, rely on Retry-After: X-RateLimit-Policy: 3;w=1 is your carrier pace in texts per second, and Limit and Remaining can come from two different limits.
{
"success": false,
"error": "You're sending faster than your numbers allow (about 3 texts a second), so this text wasn't sent. Wait 2 seconds and try again, or send in one call with POST /v1/messages/bulk.",
"code": "rate_limited",
"error_code": "rate_limited",
"retry_after_ms": 1500,
"cap_per_sec": 3
}
#Test keys
A key starting rsms_test_ simulates sends, purchases and registration: nothing is sent or charged. Other writes are refused and reads are real. It reads your real account, so keep it as safe as a live key.
Create one in Settings → Developers: click Create key, choose Test under Environment, then click Create. It’s shown once and starts with rsms_test_. An account has one test key: creating another, or Replace on its row, replaces it and the old one stops working immediately. Revoke turns it off. Only the account owner or an admin can create, replace or revoke it, and it never touches your live key.
- Simulated: sending texts (
POST /v1/messages,/v1/messages/bulk,/sms/sendand the Zapier Send SMS action), number checkout and purchase, the registration writes (brand, campaign, confirm, resubmit, vet, rename, cancel andPUT /v1/auto-vet),POST /v1/validate, and creating sub-accounts, adding team members and removing a sub-account’s legacy markup. - Refused: every other write (
POST,PUT,PATCH,DELETE) answers403 test_key_not_allowedand changes nothing. That covers contacts, conversations, webhook settings, screening lists (/compliance/scrub-categories),POST /v1/scrub,/sms/generateand number releases (DELETE /v1/numbers/:id). Two billed reads are refused the same way:GET /v1/scrub/:phoneandGET /ghl-dialer/token. The sentence is inerrorandmessage. - Reads are real: every other
GETworks and reads your real balance, rates, numbers, messages and contacts. - No delivery webhooks: test sends never trigger
message_deliveredormessage_failed. To try your endpoint, use Send test (see Webhooks). - MCP: on the MCP server a test key works as a bearer token, but only
send_smsis simulated. Every tool that changes or bills something, includingsend_campaign,enroll_in_dripandai_generate_message, is refused withtest_key_not_allowed, so it sends and charges nothing. Tools that only read work.
What a test key checks
On POST /v1/messages, /v1/messages/bulk and /sms/send, a test key checks the request itself: required fields, types, lengths, that to is a phone number, and Ready’s global block list. /v1/messages and bulk also check that from is one of your numbers (invalid_from). Your permissions, rate limits and a suspended or past-due account are checked as for a live key; the rest of your account’s state isn’t. Sends skip the opt-out, DND, balance and consent_attested checks, and the 60-second duplicate guard (duplicate_send). Number purchases don’t check payment_intent_id: a made-up id, a reused one or none at all succeeds. Registration calls don’t check that the id is yours or that the payment exists. They also skip the EIN-to-name match (ein_name_mismatch), duplicate, brand-first (brand_required_first) and vetting-state checks. The format checks (invalid_ein, address_incomplete, consent_required) still run. A 200 from a test key doesn’t mean the live call will succeed.
Simulated response shapes
Simulated responses say "test": true (at the top level or in data), most add a note, and some shapes differ. POST /v1/messages and POST /sms/send return the live data object, with the same fields repeated at the top level: { "success": true, "test": true, "data": { "message_id": "test-msg-…", "segments": 1, "status": "queued", "sent_body": "…", "compliance_text_added": null }, "message_id": "test-msg-…", "segments": 1, "status": "queued", "sent_body": "…", "compliance_text_added": null, "note": "test mode: no real message sent, no charge" }. sent_body and compliance_text_added preview the opt-out line and business name a live send would add, and segments is counted on sent_body. Both fields are left out if your settings can’t be read. The message isn’t stored, so GET /v1/messages/:id answers 404 message_not_found for it. POST /v1/messages/bulk gives each result a test-msg-… message_id and its segments, but still checks your balance first, so a low balance can get 402 insufficient_credits. POST /v1/numbers returns data.phone_number with no phone_number_id (an order outside the US returns no phone_number). Registering a brand or campaign returns registration_id: null. Registration resubmit, vet, vet/confirm and cancel return data.reg_id with test and note, not the live shape; rename returns only data.reg_id and test. Confirm returns no registration_id. Creating a sub-account returns id: null. Checkout returns a test-… payment_intent_id and no client_secret. Validate returns line_type: "unknown", carrier: null and textable: null for a number it can read, and valid: false with a reason for one it can’t. Removing a sub-account’s legacy markup returns only data.id and test. PUT /v1/auto-vet returns enabled, test and note outside data.
#Versioning
/v1 responses carry X-API-Version: 1. Pin it with Accept-Version: 1; an unserved version returns 406 unsupported_api_version with a supported list. X-API-Version is the bare number (1), while supported uses the v-prefixed name (["v1"]); Accept-Version takes either, in any case. Paths outside /v1 aren’t versioned.
What can change within /v1. We only add: new fields, new endpoints and new error codes. Write your code to ignore fields it doesn’t know. Removing or changing a field or an endpoint gets at least 90 days' notice by email to the owner of every account that used an API key in the last 90 days. From the day of that notice, the affected responses carry a Deprecation header and a Sunset header with the date it stops working. A Deprecation header with no Sunset only means a newer /v1 endpoint exists; the older path keeps working. Only Sunset means it will stop.
Spelling of canceled. Each list of statuses keeps its own spelling, and an old value is never renamed. Registration statuses use canceled; campaign statuses use cancelled; phone numbers can show either on old rows. Match the list in the docs for the resource you read.
#Timeouts
Requests time out after 30 seconds, except:
- 60 seconds: reading
/conversationsand/contacts(GET). - 90 seconds: number checkout and purchase (
POST /v1/numbers,/v1/numbers/checkout,/phone-numbers/checkout). - 90 seconds: card charges and paid filings (
POST /billing/purchase, registration checkout and confirm, a vet). - 120 seconds: uploads and large bodies (a path with
/bulk,/importor/upload). - 15 minutes: a campaign send (
POST /campaigns/:id/send,/send-remaining-now,/send-missed).
A read, or an upload that never finished, returns 408 REQUEST_TIMEOUT: nothing changed. A write that may have gone through returns 504 REQUEST_TIMEOUT_OUTCOME_UNKNOWN and Ready keeps working on it. So does a paid lookup (GET /v1/validate/:phone, GET /v1/scrub/:phone), which may still have been charged. What to do after each: When to retry.
#Timestamps, money and ids
- Timestamps: ISO 8601 in UTC with milliseconds (
2026-10-01T20:32:03.473Z), ornull. _centsamounts are integer cents._usdamounts and rates are US dollars. On/billing/balance,balanceis a count of texts, not money.- Ids are opaque. Message ids are strings (digits for texts you send, often alphanumeric for texts you receive): don’t parse them.
- Phone numbers come back in E.164 (
+12125550199).
#Idempotency
Send a new Idempotency-Key per message, and reuse it only to retry that message. Any unique string up to 255 characters (a UUID is easiest; longer is 400 idempotency_key_too_long). A retry with the same key returns the original response with Idempotent-Replayed: true, without sending or charging twice.
- Where: on the requests that send, buy or charge, such as
POST /v1/messages,/v1/messages/bulk,/sms/send,/sms/imessage,/imessage/groups,/imessage/groups/:id/send,/sms/generate,/v1/numbers/checkout,/phone-numbers/checkout,POST /v1/numbers,/v1/registration/:id/resubmit,/v1/validate,/v1/scrub,POST /v1/callsandPOST /drip-campaigns. An endpoint that takes it listsIdempotency-Keywith its parameters. - A key is tied to its first request. The same key with a different body returns the first result and does not send the new one. There’s no mismatch error.
- Errors are stored too (all but
429and the503s that ran nothing, below). After fixing a request, or after a5xxthat says nothing was sent, use a new key. After your own timeout, reuse the key; after a504, check whether it went through first (When to retry).Errors that aren’t stored
Errors are stored once the key is recorded, including a202, a500and a504. A503is stored too, unless it was answered before anything was sent, charged or written (for example, your balance, account or a price couldn’t be read); then the same key can be retried. OnPOST /sms/generate(a dashboard route) every4xxis released the same way, so a retry with the same key runs again instead of replaying. These are refused before the key is recorded, so they aren’t stored and a corrected retry with the same key goes through:- On any endpoint: malformed JSON (
INVALID_JSON),PAYLOAD_TOO_LARGE,idempotency_key_too_long, authentication and account errors (AUTH_REQUIRED,INVALID_API_KEY,INVALID_TOKEN,ACCOUNT_SUSPENDED,AUTH_CHECK_UNAVAILABLE),X-Sub-Account-Iderrors,permission_denied,IP_TEMPORARILY_BLOCKED,REQUEST_BLOCKED(400 or 403),REQUEST_TIMEOUT(408, the body never arrived),ADMISSION_SHED(503), and on/v1pathsunsupported_api_version. - On
POST /v1/messages: a missingtoorbody,invalid_fieldandinvalid_from. - On
POST /v1/numbersandPOST /v1/numbers/checkout:invalid_field. With a live key, the corrected retry is a real purchase.
- On any endpoint: malformed JSON (
- Keys are scoped per account and per endpoint, and remembered for at least 7 days.
- A retry while the first request runs gets
409 idempotency_in_progress. Unfinished after 20 minutes, it gets409 idempotency_outcome_unknown: treat it like202 send_outcome_unknown(Checking whether a text went out).
Duplicate guard. Without a key, an identical text (same recipient, body and media) within 60 seconds is refused: 409 duplicate_send. To send it twice on purpose, give each request its own key.