Brand vetting and carrier limits

#Vet a brand

External vetting raises your brand’s carrier score and daily throughput. Paid once, at your price for Standard, Enhanced, or the upgrade from Standard to Enhanced; the charge comes back as amount_cents. Needs the manage_brands permission.

Parameters

idinteger · pathRequired: The brand’s registration id.
vetting_typeenumDefault STANDARD: STANDARD or ENHANCED, case-insensitive. A brand already vetted Standard can upgrade to Enhanced for the price difference (upgrade: true). If vetting can’t be submitted, the fee is refunded automatically.

Returns

charged, amount_cents, vetting_type, upgrade, card_last4, payment_intent_id: Card on file: charged now.
client_secret, has_card, payment_intent_id: Not charged yet (no card on file, or the saved card needs confirming): confirm with Stripe.js, then Confirm the vetting payment with this payment_intent_id.

Errors

On these errors, error holds the code again. Show message to a person: it says what happened and what to do.

HTTP	Code	When
400	`invalid_vetting_type`	`vetting_type` isn’t `STANDARD` or `ENHANCED`.
400	`not_a_brand_registration`	Id is a campaign (`error`).
400	`brand_not_linked_to_carrier`	Brand not yet with the carriers (`error`).
404	`reg_not_found`	No registration has this id, or it isn’t your account’s or a sub-account’s. Both read the same (`error`).
409	`already_vetted`	The same tier or a lower one again (`error`).

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().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/481/vet",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "vetting_type": "ENHANCED"
    },
    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,
  "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

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

Parameters

idinteger · pathRequired: The brand’s registration id.
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.

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().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/481/vet/confirm",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "payment_intent_id": "pi_3Q8bVt2eZvKYlo2C1d2e3f4g"
    },
    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,
  "charged": true,
  "vetting_type": "ENHANCED",
  "upgrade": false
}

#Get a brand’s carrier limits

Reads the carrier-assigned SMS limits for the campaigns belonging to a brand. No recipient validation is needed. These 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.

Parameters

idinteger · pathRequired: The Ready brand registration ID, such as data.brand.id from GET /v1/registration, not a carrier ID or a campaign ID. The brand must be visible in the key’s account or selected sub-account.
campaign_idinteger · query: Ready campaign registration ID. Return only that campaign under this brand.
after_idinteger · query: Pagination cursor. Return campaign registrations after this ID. Each page holds up to 10 campaigns.

Returns

data.brandobject

The brand’s id, name and status.

data.campaigns[]array of objects

The brand’s campaigns.

Child attributes

id, name, statusinteger, string, string: The campaign’s registration id, name and status.
sourcestring: carrier_assignment means Ready read the carrier’s assignment. not_registered is a campaign not yet registered; then checked_at and carriers are null.
checked_atstring | null: When Ready read the assignment. Results are cached for up to 60 seconds.
carriers.attobject: 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.
carriers.tmobileobject: status, tier, daily_messages, and scope: "brand". This is a shared daily allowance. Do not add the same brand allowance across campaigns.
carriers.verizonobject: status, sms_per_second, and scope: "campaign". A null rate means the carrier did not report one, not unlimited sending or instant arrival.

data.has_more, next_after_idboolean, integer | null

When has_more is true, call again with after_id=data.next_after_id.

data.cache_ttl_secondsinteger

How long results are cached, in seconds.

Errors

HTTP	Code	When
400	no code	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: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/registration/123/limits', {
  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/123/limits",
    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": 123, "name": "Acme Roofing", "status": "approved" },
    "campaigns": [
      {
        "id": 456,
        "name": "Appointment reminders",
        "status": "approved",
        "source": "carrier_assignment",
        "checked_at": "2026-01-15T14:02:11.000Z",
        "carriers": {
          "att": { "status": "REGISTERED", "message_class": "T", "sms_per_minute": 75, "sms_per_second": 1.25, "scope": "campaign" },
          "tmobile": { "status": "REGISTERED", "tier": "LOW", "daily_messages": 2000, "scope": "brand" },
          "verizon": { "status": "REGISTERED", "sms_per_second": 10, "scope": "campaign" }
        }
      }
    ],
    "has_more": false,
    "next_after_id": null,
    "cache_ttl_seconds": 60
  }
}

#Get throughput

Live sending capacity: 24-hour volume and rejections, T-Mobile daily cap and tier, warm-up state. You can cache the response for up to one minute. Warm-up rules: Sending caps.

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. Then daily_loss_usd estimates what they cost, and brand names the brand to vet (cta: vet, upgrade or maxed) and price_usd, what that vetting charges in dollars (the upgrade price is the difference; null when maxed).

data.tmobileobject | null

daily_cap, tier, next_cap, sent_today, pct, coverage, usage_reliable. Read sent_today only when usage_reliable is true. 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: in_warmup, sent, cap, remaining, capped, ends_at, registration_id, carrier_campaign_id, campaign_id. 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.

Child attributes

in_warmupboolean | null: While true, pace within remaining. false once you’re past it, and null with ramp_unavailable: true when we couldn’t read it, so keep pacing.
ends_atstring: An estimate.
registration_idinteger | null: The Ready registration ID of the campaign in warm-up: the value the limits endpoint takes as campaign_id. null for the brand-wide ramp.
carrier_campaign_idstring | null: The carrier’s campaign ID. null for the brand-wide ramp.
campaign_idstring | null: Deprecated: the same value as carrier_campaign_id, not the Ready registration ID the limits endpoint takes as campaign_id. Use registration_id or carrier_campaign_id.

cachedboolean

Cached for up to one minute; a cached answer has "cached": true.

Errors

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

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().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/throughput",
    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": {
    "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",
      "registration_id": 412,
      "carrier_campaign_id": "8f3c1a2e",
      "campaign_id": "8f3c1a2e"
    }
  }
}

Older paths

GET /v1/registration/denied is an older path, not an alias of Get registration status: it returns only the latest rejected registration, as { denied, reg_id, type, name, reasons, reason, ai_fix }, or { denied: false } when nothing is rejected, and 503 denied_status_unavailable when it cannot be read.