Registration

Register with the carriers so your texts deliver at full throughput: register (one call files your brand and its first campaign), confirm the payment if you got a client_secret, then poll GET /v1/registration every 15 to 60 minutes (approval usually takes 2 to 7 days). Add more campaigns or vet the brand later if you need them. Until you’re approved, sending caps apply, and a test key registers and charges nothing.

Registration is paid: brand submit charges the first month, then a monthly fee. See Billing and pricing.

#The Registration object

idinteger: The registration_id. This is the :id in the paths below, not a carrier id.
statusstring: Where the brand or campaign stands. Use it only to show progress; to decide whether to send, check data.can_send_registered. Treat unknown values as “not sending”. One you never started is just {"status": "not_started"}.
Possible values

approved, registered, active: can send. Send at registered rates.

pending, awaiting_brand (a campaign waiting for its brand, not submitted yet): waiting on carriers. Poll every 15 to 60 minutes.

rejected: needs your fix. Read rejection_reason, rejection_detail and rejection_help, fix those, then resubmit.

not_started, deregistered, suspended, archived, deleted, cancelled: not started, unpaid or stopped. Register, or finish paying. For suspended, contact support.
carrier_statusstring | null: The carrier’s own text, such as VERIFIED, VETTED_VERIFIED, UNVERIFIED, REGISTERED.
approved_atstring | null: When the carriers approved it, ISO 8601.
namestring: On a campaign, the carrier campaign name (not the label set by Rename a registration).
rejection_reasonstring: On a rejected one with carrier reasons: the carrier’s text.
rejection_detailstring: The same in plain English.
rejection_suggested_fixstring or null: Our AI’s suggested fix, when it has one. It is a suggestion, not the carrier’s reason.
rejection_helpstring: What to fix, and how to resubmit.

#Get registration status

Your most recent brand and campaign, every brand and campaign on the account, and whether you can send at registered rates. Before sending, check one field: data.can_send_registered.

Returns your brand and campaign as Registration objects in data.brand and data.campaign. Each is the most recent one; for an account that registers through its agency, an approved one is shown ahead of a newer one that isn’t approved. An unpaid or cancelled registration isn’t shown: you see the one before it, or not_started.

Returns

data.registrations[]object[]: Every brand and campaign shown on your Registration page, not only the most recent: newest first (for an account that registers through its agency, approved ones first). Each is a Registration object with type (brand or campaign) and name: the label you gave it, else the campaign name or the business name. Unpaid and cancelled ones are left out, as above.
data.can_send_registeredboolean: true once the carriers approve your campaign, even if a newer one is still in review. Sending opens earlier, once your brand is approved, so texts can go out while a campaign is in review, and registered pricing starts earlier still, at paid submission.

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().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/registration",
    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": {
    "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_detail": "Sample message lacks opt-out language.",
      "rejection_suggested_fix": "Add Reply STOP to opt out to each sample message, then resubmit.",
      "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,
    "registrations": [
      {
        "id": 482,
        "status": "rejected",
        "carrier_status": null,
        "approved_at": null,
        "rejection_reason": "Sample message lacks opt-out language",
        "rejection_detail": "Sample message lacks opt-out language.",
        "rejection_suggested_fix": "Add Reply STOP to opt out to each sample message, then resubmit.",
        "rejection_help": "The carriers turned this down for the reasons in rejection_reason. Fix those, then resubmit with POST /v1/registration/482/resubmit.",
        "type": "campaign",
        "name": "Dealership outreach"
      },
      {
        "id": 481,
        "status": "approved",
        "carrier_status": "VETTED_VERIFIED",
        "approved_at": "2026-07-28T20:00:00.000Z",
        "type": "brand",
        "name": "Acme Motors"
      }
    ]
  }
}

#Get registration requirements

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

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 plus brand.first_month is what brand submit charges. brand.setup is 0 unless your account has a one-time setup price agreed with Ready, and campaign.setup is always 0. brand.first_month is the first month of Registration; brand.monthly plus campaign.monthly is what Registration bills a month, and campaign.monthly alone is what an extra campaign adds. priority is the Priority Registration fee, added to brand submit when you send rush: true. vetting.standard and vetting.enhanced are the one-time brand vetting fees Vet a brand charges; an upgrade from Standard to Enhanced costs the difference.

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().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/registration/use-cases",
    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": {
    "use_cases": [
      "MARKETING",
      "CUSTOMER_CARE",
      "MIXED",
      "DELIVERY_NOTIFICATIONS",
      "ACCOUNT_NOTIFICATIONS",
      "FRAUD_ALERTS"
    ],
    "brand_required": [
      "company_name",
      "ein",
      "street",
      "city",
      "state",
      "zip",
      "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": "Your first campaign is named after your business (letters, digits, underscores and spaces, up to 30 characters). Optional."
    },
    "pricing_usd": {
      "brand": {
        "setup": 0,
        "monthly": 25,
        "first_month": 25
      },
      "campaign": {
        "setup": 0,
        "monthly": 20
      },
      "priority": 149
    },
    "consent_required": true,
    "note": "Registration is paid. …"
  }
}

#Register

One call registers your business and its first campaign. That’s all most accounts need. Only add another campaign if you text for a second, different reason. The first campaign’s use case is MIXED unless you send use_case, it’s named after your business unless you send campaign_name, and it’s submitted automatically once the brand is approved. Paid: the first month today (no setup fee), then monthly. pricing_usd in Get registration requirements has your prices. After a timeout, send the identical request again: it reuses the same pending checkout and never charges twice (it answers checkout_in_progress or paid_not_filed instead). A payment still being checked doesn’t show in GET /v1/registration. Needs the manage_brands permission.

Parameters

company_namestringRequired: Legal name. Alias: business_name.
einstringRequired: 9 digits: 47-2918563 or 472918563. reg_number is an alias. It can’t be changed later over the API.
consentbooleanRequired: true attests prior express written consent to text recipients.
street, city, state, zipstringRequired: Business address.
preferred_area_codestring: Buys a new number in this 3-digit area code. Brand submit charges the same amount; the number is then billed monthly at your number price.
number_choiceenum: new (buy in preferred_area_code) or keep (current number). Defaults to new with an area code, otherwise keep.
rushbooleanDefault false: true buys Priority Registration, the same option as in the app: your brand goes to the front of the line. It adds the Priority Registration fee (pricing_usd.priority in Get registration requirements) to this one charge, and amount in the reply includes it. If the carriers reject the brand, or we send it to standard review instead of a fast-review slot, the priority fee is refunded. It doesn’t promise an approval time. Test keys get 403 test_key_not_allowed.

More parameters (8)

business_descriptionstring: What the business does, in one or two sentences. Leave it out and Ready writes one from your website, same as in the app. For example Family dental practice in Austin.
entity_typeenumDefault PRIVATE_PROFIT: PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT or GOVERNMENT.
industrystring: Your industry.
email, phone, first_name, last_namestring: Contact person. Leave them out and Ready uses your account’s.
dbastring: Doing-business-as name.
countrystringDefault US
phone_number_idinteger: Which of your numbers to keep.
transfer_confirmboolean: 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, the priority fee included when you sent rush: true).
data.client_secret, amount, monthly, label, has_card: No card, or declined (has_card: true): confirm with Stripe.js, then Confirm a payment. Pass it 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 (for example a negotiated $0): submitted immediately.

Errors

HTTP	Code	When
202	`payment_processing`	Still processing.
400	`invalid_request`	Missing `company_name` or `ein`, or bad `preferred_area_code` (`error`).
400	`invalid_use_case`	`use_case` isn’t one of the listed values.
400	`invalid_tax_id`	The company number doesn’t fit its country.
400	`invalid_ein`	In `code`.
400	`address_incomplete`	`error` names what’s missing (`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`.
403	`test_key_not_allowed`	A test key sent `rush: true`. Nothing was charged.
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. Send the `payment_intent_id` from this answer to Confirm registration payment (`POST /v1/registration/confirm`) and the registration is filed.
409	`area_code_unavailable`	See `alternatives`.
429	`duplicate_submission`	Repeat within 2 minutes. Don’t retry.
502	`payment_unknown`	The charge is still being checked and won’t show in `GET /v1/registration` yet. Resending the identical request is safe and never charges twice. If it doesn’t settle in a few minutes, contact support.
503	`payments_unavailable`	Nothing charged.

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": "47-2918563",
    "street": "100 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "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": "47-2918563",
    "street": "100 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "consent": 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, 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": "47-2918563",
        "street": "100 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "consent": 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}')

Returns:

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

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

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

#Get opt in page links

The public opt in page Ready hosts for each of your registered brands. It is the page the carriers review, and the link you share where people agree to get your texts. A registration that isn’t paid yet has no page, so it isn’t listed.

Returns

dataarray: One entry per registration with a page. Empty when there are none.
data[].registration_idinteger: The registration the page belongs to.
data[].brand_namestring: The brand’s trade name, or its company name.
data[].statusstring: The registration’s status.
data[].slugstring: The page’s short name in its link.
data[].public_urlstring: The full link to the page.

Errors

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

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

const res = await fetch('https://api.tryready.com/v1/registration/optin-urls', {
  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/registration/optin-urls",
    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": [
    {
      "registration_id": 412,
      "brand_name": "Acme Plumbing",
      "status": "approved",
      "slug": "acme-plumbing-x7k2",
      "public_url": "https://optin.tryready.com/websites/acme-plumbing-x7k2/3f9a1c"
    }
  ]
}