ready. Try Ready →Sign up

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.

Base URL
https://api.tryready.com

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

  • Responses have "success": true and the result in data, with paging fields next to it on lists. A few put fields at the top level; each endpoint's Returns says where.
  • Endpoint defaults: API key auth, not idempotent, rate limited per IP (1,200 a minute, see Rate limits). Each endpoint lists Auth, Idempotent and Rate limit only where they differ.
  • Errors have "success": false, an error sentence and a stable code. See Errors.
  • Requests are JSON (Content-Type: application/json), up to 1 MB (413 PAYLOAD_TOO_LARGE). Malformed JSON returns 400 INVALID_JSON.
  • Paths. /v1/* is versioned. The other paths here are supported, but new endpoints go under /v1.
    DetailsAn API key works on the endpoints in this reference. Other paths the dashboard uses may accept it today, but they aren't part of the API, can change without notice, and will be closed to API keys.

New here? Start with the Quickstart.

#The API by area

Each area has its own page. A link to an old /api#section address still opens the right page.

  • Start here: Quickstart, authentication and test keys, errors, pagination, rate limits, idempotency and versioning.
  • Webhooks: events, signatures, delivery and the webhook settings endpoints.
  • Messages: send one text or many, get a message, list messages.
  • Conversations: list conversations and their messages; assign, mark read, archive and star.
  • Opt-outs and scrubbing: check and list opt-outs, scrub numbers, export opt-outs.
  • Contacts: list, get, create, update and delete contacts.
  • Validate numbers: check whether numbers can get texts.
  • Phone numbers: list numbers, check an area code, buy and release numbers.
  • Client accounts: create and list client accounts, set a client's markup.
  • A2P registration: register a brand and campaign, pay, check status, resubmit, vet a brand.
  • Balance and billing: balance, rates and billing history.
  • AI copy: write message drafts.
  • Zapier: the Ready Zapier app.
  • MCP for AI agents: connect an AI agent to Ready.
  • Legacy endpoints: older paths that are still supported.