readyDocs Open the appOpen the app

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.

A live key acts on your real account. To try sends, number purchases and registration without sending or paying, use a test key.

#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.

  1. #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"
  2. #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"

    Sample values. Your own rates are under Your price in Settings → Billing.

    Returns:
    {
      "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
      }
    }
  3. #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 200 means Ready accepted the text, not that it was delivered. Store data.message_id: delivery lookups and webhooks use it.

    In production, also send an Idempotency-Key header on every send, so a retry never sends twice.

    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
      }'
    Returns:
    {
      "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
      }
    }
  4. #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 in data.secret: store it.

    Reply from your phone and an inbound_reply event 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"
        ]
      }'
  5. #Go live

#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
Returns:
{
  "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"
}

#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
  • limit defaults 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 on GET /v1/calls, where a limit above 999 is refused with a 400. 0, negative or non-numeric values fall back to the default, except on GET /v1/calls, where a negative or non-numeric limit is refused with a 400 (0 falls back to the default there too).
  • offset must be a whole number, 0 or more. Other values return 400 invalid_offset on /contacts and /conversations.
  • next_before_id is set on the last page too, and is null when the page is empty. has_more can be true on a page that is exactly full, so the last page may be empty.
  • total can be an estimate on large or slow queries (on /contacts, total_is_estimate is then true), can be up to 2 minutes old, and can show 1 when nothing matches. Use it for display, not to end a loop.
EndpointStylePaging fields next to dataMax limit
GET /contactsoffsettotal, total_is_estimate1,000
GET /conversationsoffsethas_more, total, total_capped, count_cap, counts1,000
GET /conversations/:id/messagesoffsetnone500
GET /billing/transactionsoffsettotal, summary1000
GET /sms/logs (older path, use GET /v1/messages)offsethas_more (also as hasMore), total (always null)1,000
GET /v1/messagescursorhas_more, next_before_id200
GET /v1/opt-outscursorhas_more, next_before_id500 (default 100)
GET /v1/sub-accountscursorhas_more, next_before_id200
GET /v1/callscursorhas_more, next_cursor999 (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.

WhatLimitCountedOver 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 exports6 an hour, shared with the dashboardPer account429
Everything, as an outer ceiling1,200 requests a minute with a valid key, 300 without onePer IP address429 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_number with 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_balance when 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_REACHED on /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/messages or 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.

Returns:
{
  "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/send and the Zapier Send SMS action), number checkout and purchase, the registration writes (brand, campaign, confirm, resubmit, vet, rename, cancel and PUT /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) answers 403 test_key_not_allowed and changes nothing. That covers contacts, conversations, webhook settings, screening lists (/compliance/scrub-categories), POST /v1/scrub, /sms/generate and number releases (DELETE /v1/numbers/:id). Two billed reads are refused the same way: GET /v1/scrub/:phone and GET /ghl-dialer/token. The sentence is in error and message.
  • Reads are real: every other GET works and reads your real balance, rates, numbers, messages and contacts.
  • No delivery webhooks: test sends never trigger message_delivered or message_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_sms is simulated. Every tool that changes or bills something, including send_campaign, enroll_in_drip and ai_generate_message, is refused with test_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 /conversations and /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, /import or /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), or null.
  • _cents amounts are integer cents. _usd amounts and rates are US dollars. On /billing/balance, balance is 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/calls and POST /drip-campaigns. An endpoint that takes it lists Idempotency-Key with 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 429 and the 503s that ran nothing, below). After fixing a request, or after a 5xx that says nothing was sent, use a new key. After your own timeout, reuse the key; after a 504, check whether it went through first (When to retry).
    Errors that aren’t storedErrors are stored once the key is recorded, including a 202, a 500 and a 504. A 503 is 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. On POST /sms/generate (a dashboard route) every 4xx is 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-Id errors, permission_denied, IP_TEMPORARILY_BLOCKED, REQUEST_BLOCKED (400 or 403), REQUEST_TIMEOUT (408, the body never arrived), ADMISSION_SHED (503), and on /v1 paths unsupported_api_version.
    • On POST /v1/messages: a missing to or body, invalid_field and invalid_from.
    • On POST /v1/numbers and POST /v1/numbers/checkout: invalid_field. With a live key, the corrected retry is a real purchase.
  • 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 gets 409 idempotency_outcome_unknown: treat it like 202 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.