A2P registration · Ready Docs

#A2P registration

The flow: register a brand, confirm the payment if you got a client_secret, then poll GET /v1/registration every 15 to 60 minutes (approval takes days).

Details

Add more campaigns or vet the brand later if you need them.

What you can send at each step (reviews run in sequence, so times add up).

Details

Before you register: a trial's free sends end with 402 SANDBOX_LIMIT. Unregistered accounts created since June 23, 2026 can send 500 texts per 30-day cap window (Sending caps).
Brand submitted: the brand is reviewed first. Its campaign waits as awaiting_brand and isn't submitted yet.
Brand approved: Ready submits the campaign for review, under warm-up limits.
Campaign approved, sending from a paid number: full volume (campaigns added later have their own warm-up).

What it costs. Brand setup $30 keeping your number, $35 with a new one. Monthly: brand $10, campaign $20, plus $5 per number.

Details

A negotiated setup price replaces these (never more). A new number means sending preferred_area_code.
Your first campaign is created with the brand and has no setup fee; each extra campaign is $20 a month.
Brand and campaign fees start when you pay the setup fee (for a campaign with no setup fee, when you submit it). The first 30 days are included, so the first monthly charge comes 30 days later. It doesn't wait for carrier approval.

With a test key, nothing is registered or charged, only format checks run, and responses aren't the live shape.

Details

Skipped: the ownership, EIN-to-name match (ein_name_mismatch), duplicate, brand-first (brand_required_first) and vetting-state checks. Still run: invalid_ein, address_incomplete, business_description_required, consent_required. Test responses are wrapped in data: brand and campaign return registration_id: null, confirm returns only test and note, the other calls return reg_id (see Test keys).

:id in these paths is a registration_id: the brand.id or campaign.id from GET /v1/registration, not a carrier id.

Don't retry a brand or campaign POST after a timeout: poll GET /v1/registration first.

Details

Writes need manage_brands, which an owner's key has. Error shapes vary: branch on code (or error_code) when present, otherwise on error, which holds a machine code for some of them.

#Get registration requirements

GET/v1/registration/use-cases

Valid use cases, required fields and prices. Call this first.

Cost Free

Returns

data.use_casesstring[]: Valid campaign use_case values.
data.brand_required, campaign_requiredstring[]: Fields a request must include; one without them is refused.
data.auto_filledobject: Ready fills these in. Leave them blank.
data.pricing_usdobject: brand.setup is the new-number price; keeping your number (no preferred_area_code) is $30.

Errors

None specific.

GET /v1/registration/use-cases

curl "https://api.tryready.com/v1/registration/use-cases" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/registration/use-cases', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/registration/use-cases",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "use_cases": [
      "MARKETING",
      "CUSTOMER_CARE",
      "MIXED",
      "DELIVERY_NOTIFICATIONS",
      "ACCOUNT_NOTIFICATIONS",
      "FRAUD_ALERTS"
    ],
    "brand_required": [
      "company_name",
      "ein",
      "street",
      "city",
      "state",
      "zip",
      "business_description",
      "consent"
    ],
    "campaign_required": [
      "use_case"
    ],
    "auto_filled": {
      "website": "We host a compliant opt-in page for the brand and register that URL. Leave it blank.",
      "campaign_description": "Written from the use case and business name. Leave it blank.",
      "campaign_name": "Defaults to \"<business name> Campaign\". Optional."
    },
    "pricing_usd": {
      "brand": {
        "setup": 35,
        "monthly": 10
      },
      "campaign": {
        "setup": 0,
        "monthly": 20
      }
    },
    "consent_required": true,
    "note": "Registration is payment-gated. …"
  }
}

#Register a brand

POST/v1/registration/brand

Registers your business and creates its first campaign, so most accounts never call Add a campaign. Paid.

Auth API key with manage_brands
Cost $30 or $35 setup, then $10/month

First campaign.

Details

Its use case is MIXED. It's named after your business and submitted automatically once the brand is approved.

Body parameters

company_namestringRequired: Legal name. Alias: business_name.
einstringRequired: 9 digits: 12-3456789 or 123456789.
Details
reg_number is an alias. It can't be changed later over the API.
business_descriptionstringRequired: What the business does, in one or two sentences.
Details
For example Family dental practice in Austin.
consentbooleanRequired: true attests prior express written consent to text recipients.
entity_typeenumCarriers need itDefault PRIVATE_PROFIT: PRIVATE_PROFIT
PUBLIC_PROFIT
NON_PROFIT
GOVERNMENT
industrystringCarriers need it
street, city, state, zipstringRequired: Business address.
email, phone, first_name, last_namestringCarriers need it: Contact person; phone in E.164.
preferred_area_codestringOptional: Buys a new number in this 3-digit area code ($35).
number_choiceenumOptional: new (buy in preferred_area_code) or keep (current number).
Details
Defaults to new with an area code, otherwise keep. Other values aren't rejected yet, and are billed $35 without buying a number.

More parameters (5)

websitestringOptional: Leave blank. Ready hosts a compliant opt-in page for your brand and registers that URL; anything you send is replaced.
dbastringOptional: Doing-business-as name.
countrystringOptionalDefault US
phone_number_idintegerOptional: Which of your numbers to keep.
transfer_confirmbooleanOptional: Send true after a 409 needs_transfer_confirm to move the number from its other brand.

Returns

data.charged, amount, card_brand, card_last4, registration_id: Card on file: charged now (amount in cents).
data.client_secret, amount, monthly, label, has_card: No card, or declined (has_card: true): confirm with Stripe.js, then Confirm a payment.
Details
Pass Confirm a payment the payment_intent_id: the part of client_secret before _secret_. The registration_id comes back from that call.
data.zero_feeboolean: No fee due: submitted immediately.
Details
For example a negotiated $0.

Errors

HTTP	Code	When
400	no code	Missing `company_name` or `ein`, or bad `preferred_area_code` (`error`).
400	`invalid_ein`	In `code`.
400	`address_incomplete`	`error` names what's missing (`code`).
400	`business_description_required`	In `code`.
400	`preferred_area_code_required`	`new` without an area code (`error`).
400	`consent_required`	Not boolean `true`.
400	`ein_name_mismatch`	In `error`, with `title`, `message`, `steps`.
409	`duplicate_brand`	See `existing_reg_id`.
409	`needs_transfer_confirm`	A flag, not a code. Resend with `transfer_confirm: true`.
409	`paid_not_filed`	Don't pay again; contact support.
409	`area_code_unavailable`	See `alternatives`.
429	`duplicate_submission`	Repeat within 2 minutes. Don't retry.
202	`payment_processing`	Still processing.
502	`payment_unknown`	Don't resubmit; poll `GET /v1/registration`.
503	`payments_unavailable`	Nothing charged.

POST /v1/registration/brand

curl -X POST "https://api.tryready.com/v1/registration/brand" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Dental LLC",
    "ein": "12-3456789",
    "entity_type": "PRIVATE_PROFIT",
    "industry": "HEALTHCARE",
    "street": "100 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "email": "owner@acmedental.example.com",
    "phone": "+15125550100",
    "first_name": "Jordan",
    "last_name": "Lee",
    "business_description": "Family dental practice in Austin.",
    "consent": true
  }'

const res = await fetch('https://api.tryready.com/v1/registration/brand', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "company_name": "Acme Dental LLC",
    "ein": "12-3456789",
    "entity_type": "PRIVATE_PROFIT",
    "industry": "HEALTHCARE",
    "street": "100 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "email": "owner@acmedental.example.com",
    "phone": "+15125550100",
    "first_name": "Jordan",
    "last_name": "Lee",
    "business_description": "Family dental practice in Austin.",
    "consent": true
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/registration/brand",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "company_name": "Acme Dental LLC",
        "ein": "12-3456789",
        "entity_type": "PRIVATE_PROFIT",
        "industry": "HEALTHCARE",
        "street": "100 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "email": "owner@acmedental.example.com",
        "phone": "+15125550100",
        "first_name": "Jordan",
        "last_name": "Lee",
        "business_description": "Family dental practice in Austin.",
        "consent": True
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "charged": true,
    "amount": 3000,
    "card_brand": "visa",
    "card_last4": "4242",
    "registration_id": 481
  }
}

{
  "success": true,
  "data": {
    "client_secret": "pi_..._secret_...",
    "amount": 3000,
    "monthly": 1000,
    "label": "Brand Registration",
    "has_card": false
  }
}

{
  "success": true,
  "data": {
    "charged": true,
    "amount": 0,
    "zero_fee": true,
    "registration_id": 481
  }
}

#Add a campaign

POST/v1/registration/campaign

Adds a campaign with another use case (your brand already has one). Consent is given once, on the brand.

Auth API key with manage_brands
Cost No setup fee; $20/month from submission (first 30 days included)

Body parameters

campaign_namestringOptionalDefault <business name> Campaign
use_caseenumRequired: One of the use cases, case-insensitive.
brand_idintegerOptional: The brand's registration_id.
Details
Send it when the brand is already approved so the campaign goes straight to review; otherwise it waits as awaiting_brand.
campaign_descriptionstringOptional: Leave blank: Ready writes it from your use_case and business name.

Errors

HTTP	Code	When
400	no code	Missing `use_case` (read `error`).
400	`brand_required_first`	No brand yet (one awaiting payment counts).
400	`invalid_use_case`	`valid` lists them.
409	`duplicate_use_case`	Use case taken (`existing_reg_id`, `existing_campaign_name`). The first campaign is `MIXED`.
429	`duplicate_submission`	Repeat within 2 minutes.

POST /v1/registration/campaign

curl -X POST "https://api.tryready.com/v1/registration/campaign" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "Appointment reminders",
    "use_case": "ACCOUNT_NOTIFICATIONS",
    "brand_id": 481
  }'

const res = await fetch('https://api.tryready.com/v1/registration/campaign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "campaign_name": "Appointment reminders",
    "use_case": "ACCOUNT_NOTIFICATIONS",
    "brand_id": 481
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/registration/campaign",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "campaign_name": "Appointment reminders",
        "use_case": "ACCOUNT_NOTIFICATIONS",
        "brand_id": 481
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "charged": true,
    "amount": 0,
    "zero_fee": true,
    "registration_id": 482
  }
}

#Confirm a payment

POST/v1/registration/confirm

After Stripe.js confirms a client_secret, this submits the registration now. Safe to call twice.

Auth API key with manage_brands
Cost Free

Body parameters

payment_intent_idstringRequired: The part of client_secret before _secret_.

Errors

HTTP	Code	When
400	no code	`payment_intent_id is required`.
400	`payment_not_completed`	Payment failed (`status`).
202	`payment_processing`	Still processing; retry shortly.
404	`payment_not_found`	Not a payment on your account.
503	`payment_check_unavailable`	Couldn't check the payment. Retry.
503	`payments_unavailable`	Payments down. Retry later.

POST /v1/registration/confirm

curl -X POST "https://api.tryready.com/v1/registration/confirm" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
  }'

const res = await fetch('https://api.tryready.com/v1/registration/confirm', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/registration/confirm",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "registration_id": 481,
  "type": "brand"
}

{
  "success": true,
  "already_processed": true,
  "registration_id": 481
}

#Get registration status

GET/v1/registration

Your most recent brand and campaign, and whether you can send at registered rates.

Cost Free

Returns

data.brand, data.campaignobject | null: Most recent only: status, carrier_status, approved_at.
Details
carrier_status is the carrier's own text, such as VERIFIED, VETTED_VERIFIED, UNVERIFIED, REGISTERED. A rejected one adds rejection_reason and rejection_help.
statusstring: not_started, pending_payment, pending, awaiting_brand, approved or active, rejected, suspended, cancelled (also canceled), deregistered, expired, payment_declined. Treat unknown values as "not sending".
data.can_send_registeredboolean: true once the carriers approve your campaign. Registered pricing starts earlier, at paid submission.

Errors

None specific.

GET /v1/registration

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

const res = await fetch('https://api.tryready.com/v1/registration', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/registration",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "brand": {
      "id": 481,
      "status": "approved",
      "carrier_status": "VETTED_VERIFIED",
      "approved_at": "2026-07-28T20:00:00.000Z"
    },
    "campaign": {
      "id": 482,
      "status": "rejected",
      "carrier_status": null,
      "approved_at": null,
      "name": "Dealership outreach",
      "rejection_reason": "Sample message lacks opt-out language",
      "rejection_help": "The carriers turned this down for the reasons in rejection_reason. Fix those, then resubmit with POST /v1/registration/482/resubmit."
    },
    "can_send_registered": false
  }
}

#Get rejection details

GET/v1/registration/denied

The latest rejected registration, the carrier's reasons and a suggested fix.

Cost Free

Returns

data.deniedboolean: false (and nothing else) when nothing is rejected.
data.reg_id, type, nameinteger, string, string: The registration to resubmit.
data.reasons, reasonstring: The carrier's text, and the same in plain English.
data.ai_fixobject | null: Suggested changes, when we have them.

Errors

HTTP	Code	When
500	`denied_status_unavailable`	Couldn't load the details. Retry in a minute.

GET /v1/registration/denied

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

const res = await fetch('https://api.tryready.com/v1/registration/denied', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/registration/denied",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "denied": true,
    "reg_id": 482,
    "type": "campaign",
    "name": "Dealership outreach",
    "reasons": "…carrier text…",
    "reason": "…plain English…",
    "ai_fix": {
      "…": "…"
    }
  }
}

{
  "success": true,
  "data": {
    "denied": false
  }
}

#Resubmit a registration

POST/v1/registration/:id/resubmit

Resubmits a rejected registration, optionally with corrected fields.

Auth API key with manage_brands
Idempotent Yes, with Idempotency-Key
Cost Free

Path parameters

idintegerRequired: The rejected registration's id.

Headers

Idempotency-KeystringRecommended: Resubmitting deregisters and re-registers with the carrier.

Body parameters

fieldsobjectOptional: Corrections. Only these keys apply: company_name, dba, website, industry, entity_type, use_cases, campaign_description, street, city, state, zip, email, phone, first_name, last_name.
Details
Others, and empty strings, are ignored, including ein: to change the EIN, contact support.

Errors

HTTP	Code	When
400	`invalid_field`	`fields` isn't an object.
404	`not_rejected`	Not rejected.
500	`resubmit_unconfirmed`	Don't resubmit yet; poll `GET /v1/registration`.
502	no code	Carrier refused (`error` and `code`).

POST /v1/registration/:id/resubmit

curl -X POST "https://api.tryready.com/v1/registration/482/resubmit" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "campaign_description": "Appointment reminders for patients who opted in at the front desk."
    }
  }'

const res = await fetch('https://api.tryready.com/v1/registration/482/resubmit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "fields": {
      "campaign_description": "Appointment reminders for patients who opted in at the front desk."
    }
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, uuid, requests

r = requests.post(
    "https://api.tryready.com/v1/registration/482/resubmit",
    headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    json={
        "fields": {
            "campaign_description": "Appointment reminders for patients who opted in at the front desk."
        }
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "reg_id": 482,
  "type": "campaign",
  "status": "pending",
  "submit": {
    "ok": true,
    "status": "pending"
  },
  "message": "…"
}

#Vet a brand

POST/v1/registration/:id/vet

External vetting raises your brand's carrier score and daily throughput. Paid, one time.

Auth API key with manage_brands
Cost $79 Standard, $179 Enhanced, $100 upgrade

Path parameters

idintegerRequired: The brand's registration id.

Body parameters

vetting_typeenumOptionalDefault STANDARD: STANDARD or ENHANCED, case-insensitive.
Details
A brand already vetted Standard can upgrade to Enhanced for the $100 difference (upgrade: true). If vetting can't be submitted, the fee is refunded automatically.

Returns

Top level, not under data.

charged, amount_cents, vetting_type, upgrade, card_last4, payment_intent_id: Card on file: charged now.
client_secret, has_card, payment_intent_id: No card: confirm with Stripe.js, then Confirm the vetting payment with this payment_intent_id.

Errors

HTTP	Code	When
400	no code	`vetting_type must be STANDARD or ENHANCED`.
400	`reg_not_found`	Not your brand (`error`).
400	`not_a_brand_registration`	Id is a campaign (`error`).
400	`brand_not_linked_to_infobip`	Brand not yet with the carriers (`error`).
403	`forbidden`	Only the registering account can vet (`error`).
409	`already_vetted`	The same tier or a lower one again.

POST /v1/registration/:id/vet

curl -X POST "https://api.tryready.com/v1/registration/481/vet" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vetting_type": "ENHANCED"
  }'

const res = await fetch('https://api.tryready.com/v1/registration/481/vet', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "vetting_type": "ENHANCED"
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/registration/481/vet",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "vetting_type": "ENHANCED"
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "charged": true,
  "amount_cents": 17900,
  "vetting_type": "ENHANCED",
  "upgrade": false,
  "card_last4": "4242",
  "payment_intent_id": "pi_3Q8bVt2eZvKYlo2C1d2e3f4g"
}

{
  "success": true,
  "charged": false,
  "client_secret": "pi_..._secret_...",
  "amount_cents": 17900,
  "vetting_type": "ENHANCED",
  "upgrade": false,
  "has_card": false,
  "payment_intent_id": "pi_3Q8bVt2eZvKYlo2C1d2e3f4g"
}

#Confirm the vetting payment

POST/v1/registration/:id/vet/confirm

Applies the vetting after a client_secret payment. Safe to call twice.

Auth API key with manage_brands
Cost Free

Path parameters

idintegerRequired: The brand's registration id.

Body parameters

payment_intent_idstringRequired: From Vet a brand.

Errors

HTTP	Code	When
400	`payment_intent_mismatch`	The payment isn't for this vetting.
400	`payment_not_succeeded`	Not paid yet (`202` while processing; `error`).
400	`could_not_retrieve_payment_intent`	No such payment.
409	`payment_refunded`	That payment was refunded.
503	`could_not_retrieve_payment_intent`	We couldn't check the payment. Don't pay again; retry.

POST /v1/registration/:id/vet/confirm

curl -X POST "https://api.tryready.com/v1/registration/481/vet/confirm" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "pi_3Q8bVt2eZvKYlo2C1d2e3f4g"
  }'

const res = await fetch('https://api.tryready.com/v1/registration/481/vet/confirm', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "payment_intent_id": "pi_3Q8bVt2eZvKYlo2C1d2e3f4g"
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/registration/481/vet/confirm",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "payment_intent_id": "pi_3Q8bVt2eZvKYlo2C1d2e3f4g"
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "charged": true,
  "vetting_type": "ENHANCED",
  "upgrade": false
}

Get a brand's carrier limits

GET/v1/registration/:id/limits

Read carrier-assigned SMS limits for the campaigns belonging to a brand. No recipient validation is needed. Use the Ready brand registration ID, such as data.brand.id from GET /v1/registration, rather than a carrier ID or a campaign blast ID.

Authenticate with X-API-Key. The brand must be visible in the key's account or selected sub-account. For a client workspace, use X-Sub-Account-Id with your agency key. The call is read-only and has no charge.

Query parameters

Parameter	Purpose
`campaign_id`	Optional Ready campaign registration ID. Return only that campaign under this brand.
`after_id`	Optional pagination cursor. Return campaign registrations after this ID. Each page holds up to 10 campaigns.

Returns

data.brand contains id, name, and status. Each entry in data.campaigns has its registration id, name, status, source, checked_at, and carriers:

Carrier	Assignment
AT&T	`status`, `message_class`, `sms_per_minute`, `sms_per_second`, and `scope: "campaign"`. Fractional rates are preserved, such as 75 per minute = 1.25 per second.
T-Mobile	`status`, `tier`, `daily_messages`, and `scope: "brand"`. This is a shared daily allowance. Do not add the same brand allowance across campaigns.
Verizon	`status`, `sms_per_second`, and `scope: "campaign"`. A `null` rate means the carrier did not report one, not unlimited sending or instant arrival.

source: "carrier_assignment" means Ready read the carrier's assignment. Results are cached for up to 60 seconds; checked_at records that read. A campaign not yet registered has source: "not_registered", checked_at: null, and carriers: null.

When data.has_more is true, call again with after_id=data.next_after_id. These assignments describe allowed capacity, not available daily headroom or measured sending speed. Check approval and carrier status, use GET /v1/registration/throughput for account usage and warm-up restrictions, and allow for concurrent traffic and delivery time.

Errors

400: an invalid ID or cursor. 404 registration_not_found: the brand is not visible to this account, or the selected campaign does not belong to it. 503 throughput_unavailable: the database or carrier assignments could not be read. A failure does not return guessed limits.

curl "https://api.tryready.com/v1/registration/123/limits" \
  -H "X-API-Key: YOUR_READY_API_KEY"

# Only one campaign registration
curl "https://api.tryready.com/v1/registration/123/limits?campaign_id=456" \
  -H "X-API-Key: YOUR_READY_API_KEY"

#Get throughput

GET/v1/registration/throughput

Live sending capacity: 24-hour volume and rejections, T-Mobile daily cap and tier, warm-up state.

Cost Free

Returns

data.total_24h, rejected_24h, reject_pctinteger, integer, number: Last 24 hours: messages, rejections (messages, not segments), percent rejected.
data.throttledboolean: true at 50 or more rejections and 5% or more of the last 24 hours.
Details
Then daily_loss_usd estimates what they cost, and brand names the brand to vet (cta: vet, upgrade or maxed).
data.tmobileobject | null: daily_cap, tier, next_cap, sent_today, pct, coverage, usage_reliable. Read sent_today only when usage_reliable is true.
Details
The ladder is 2,000, 10,000, 40,000, 100,000, 200,000; next_cap is null at the top. The whole object is null until you have a T-Mobile tier.
data.rampobject: Warm-up state (below).
cachedboolean: Refreshed at most once a minute; a cached answer has "cached": true.

Warm-up limits

500 texts from brand approval until your first campaign is approved, and 500 for a later campaign's first 2 business days. Over the cap: 409 RAMP_CAP_REACHED. While ramp.in_warmup is true, pace within ramp.remaining.

Details

Full volume unlocks once the first campaign is approved. The later-campaign cap applies to an account that's already live. ramp.in_warmup is false once you're past it. ends_at is an estimate. If more than one warm-up runs at once (a brand ramp and a newly approved campaign), this reports the one you're most limited by, and ramp.campaign_id names it (null for the brand-wide ramp).

Errors

HTTP	Code	When
503	`throughput_unavailable`	Couldn't be read. Never a fake all-clear.

GET /v1/registration/throughput

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

const res = await fetch('https://api.tryready.com/v1/registration/throughput', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/registration/throughput",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "throttled": false,
    "total_24h": 1840,
    "rejected_24h": 12,
    "reject_pct": 0.7,
    "daily_loss_usd": 0,
    "brand": null,
    "tmobile": {
      "daily_cap": 2000,
      "tier": "LOW",
      "next_cap": 10000,
      "sent_today": 640,
      "pct": 32,
      "coverage": 0.9,
      "usage_reliable": true
    },
    "ramp": {
      "in_warmup": true,
      "sent": 180,
      "cap": 500,
      "remaining": 320,
      "capped": false,
      "ends_at": "2026-10-06T13:00:00.000Z",
      "campaign_id": "8f3c1a2e"
    }
  }
}

#Rename a registration

PUT/v1/registration/:id/name

A Ready dashboard label; nothing changes with the carriers.

Auth API key with manage_brands
Cost Free

Path parameters

idintegerRequired: The registration id.

Body parameters

namestringRequired: Up to 80 characters; longer is cut.
Details
It isn't returned by GET /v1/registration, which shows the carrier campaign name.

Errors

HTTP	Code	When
400	no code	`name is required`.
404	`registration_not_found`	No registration with this id.

PUT /v1/registration/:id/name

curl -X PUT "https://api.tryready.com/v1/registration/482/name" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reminders (main office)"
  }'

const res = await fetch('https://api.tryready.com/v1/registration/482/name', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Reminders (main office)"
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/v1/registration/482/name",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "name": "Reminders (main office)"
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "id": 482,
    "display_name": "Reminders (main office)"
  }
}

#Cancel a registration

DEL/v1/registration/:id

Cancels the registration and its monthly fee. The setup fee isn't refunded.

Auth Account owner's API key
Cost Free

Path parameters

idintegerRequired: The registration id.

Errors

HTTP	Code	When
400	`registration_approved`	Approved; contact support.
403	no code	Owner only.
404	`registration_not_found`	No registration with this id.
409	`registration_changed`	Status just changed; nothing removed.
502	`subscription_cancel_failed`	We couldn't confirm the monthly fee stopped.

DEL /v1/registration/:id

curl -X DELETE "https://api.tryready.com/v1/registration/482" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/registration/482', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.delete(
    "https://api.tryready.com/v1/registration/482",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true
}