readyDocs Open the appOpen the app

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.

HTTPCodeWhen
400invalid_vetting_typevetting_type isn’t STANDARD or ENHANCED.
400not_a_brand_registrationId is a campaign (error).
400brand_not_linked_to_carrierBrand not yet with the carriers (error).
404reg_not_foundNo registration has this id, or it isn’t your account’s or a sub-account’s. Both read the same (error).
409already_vettedThe same tier or a lower one again (error).

#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
HTTPCodeWhen
400payment_intent_mismatchThe payment isn’t for this vetting.
400payment_not_succeededNot paid yet (202 while processing; error).
400could_not_retrieve_payment_intentNo such payment.
409payment_refundedThat payment was refunded.
503could_not_retrieve_payment_intentWe couldn’t check the payment. Don’t pay again; retry.

#Turn auto-vetting on or off

Records your brand’s authorization for Ready to vet it at the Standard fee (one time, charged to the card on file, emailed first) when it sends at 80% of its T-Mobile daily limit two days in a row (Sending speed and capacity). Ready also needs the account switch Auto-unlock when a business hits its cap on (it’s on unless you turned it off; read and set it with Turn auto-unlock on or off); with either one off, Ready doesn’t vet the brand or charge for it. Needs the manage_brands permission.

Parameters

enabledbooleanRequired
true or false, as a JSON boolean.
Returns
enabledboolean
The setting now. GET /v1/auto-vet returns the rest.
Errors
HTTPCodeWhen
400enabled_requiredenabled is missing.
400invalid_fieldenabled is not a JSON boolean.
404no_brandThe account has no registered brand yet.
403owner_onlyTurning it on, from a sub-account whose agency pays for it. Only the account that pays for vetting turns it on; turning it off is always allowed.
500preference_save_failedThe setting wasn’t saved. When you turn it on and Ready can’t record your authorization, it stays off. Try again.

#Get the auto-vetting setting

Reads whether your brand authorized auto-vetting, and whether it’s already vetted. It doesn’t read the account switch. Any key on the account can call it.

Returns
enabledboolean
true when auto-vetting is on.
opted_outboolean
true when it was turned off.
vettedboolean
true when the brand is already vetted.
has_brandboolean
true when the account has a registered brand. Without one, the other three are false.
Errors
HTTPCodeWhen
500preference_unavailableThe setting could not be read. Try again.

#Turn auto-unlock on or off

The account switch Auto-unlock when a business hits its cap. With it off, Ready never vets a brand automatically, whatever auto-vetting says. With it on, a brand is vetted only when its own auto-vetting is on too. It covers every brand your account pays for. Needs the manage_brands permission.

Body parameters

enabledbooleanRequired
true or false, as a JSON boolean.
Returns
enabledboolean
The setting now.
Errors
HTTPCodeWhen
400enabled_requiredenabled is missing.
400invalid_fieldenabled is not a JSON boolean.
500auto_unlock_save_failedThe setting wasn’t saved. Try again.

#Get auto-unlock

Whether auto-unlock is on. It’s on unless someone turned it off.

Returns
enabledboolean
The setting now.
Errors
HTTPCodeWhen
500no codeReady couldn’t load the setting. Try again.

#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
HTTPCodeWhen
400no codeAn invalid ID or cursor.
404registration_not_foundThe brand is not visible to this account, or the selected campaign does not belong to it.
503throughput_unavailableThe database or carrier assignments could not be read. A failure does not return guessed limits.

#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
HTTPCodeWhen
503throughput_unavailableCouldn’t be read. Never a fake all-clear.
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.