SMS numbers tools
Register a brand for US texting (A2P 10DLC), then buy and manage the numbers its texts come from.
- create_sms_sender
- get_sms_sender
- update_sms_sender
- verify_sms_sender
- delete_sms_sender
- search_sms_numbers
- list_sms_numbers
- add_sms_number
- remove_sms_number
create_sms_sender
Register this team for SMS (A2P 10DLC). TWO-STEP: call FIRST without confirm (or confirm:false) to get a PREVIEW — the chosen tier, estimated monthly fee, sample messages, and the consent URLs to be submitted — which creates NOTHING and charges nothing. SHOW that preview to the user for approval, THEN call again with confirm:true to actually register. Takes the full wizard payload { business, representative, campaign, consent }. An EIN is REQUIRED (422 ein_required; no sole-proprietor tier → irs.gov). campaign.use_case is REQUIRED and LOCKED once created. On confirm, Sequence registers the brand, then a background sweep creates the campaign once the brand is approved and provisions the number once the campaign is approved (approval takes hours to 1–3 business days) — the sender sits 'pending' until then and the owner is emailed at each step. Idempotent on the team; recurring per-team campaign fee.
businessobjectrequired- Brand / Customer Profile facts. EIN required.
business.legal_namestringrequiredbusiness.entity_typeenumrequired- LIMITED_LIABILITY_COMPANY | CORPORATION | PARTNERSHIP | NON_PROFIT
Legal entity type registered with the state. business.einstringrequired- Federal tax ID, format 12-3456789. REQUIRED — no EIN, no SMS (422 ein_required).
business.industryenumrequired- AGRICULTURE | AUTOMOTIVE | BANKING | CONSTRUCTION | CONSUMER | EDUCATION | ELECTRONICS | ENERGY | ENGINEERING | FAST_MOVING_CONSUMER_GOODS | FINANCIAL | FINTECH | FOOD_AND_BEVERAGE | GOVERNMENT | HEALTHCARE | HOSPITALITY | INSURANCE | JEWELRY | LEGAL | MANUFACTURING | MEDIA | NOT_FOR_PROFIT | OIL_AND_GAS | ONLINE | PROFESSIONAL_SERVICES | RAW_MATERIALS | REAL_ESTATE | RELIGION | RETAIL | TECHNOLOGY | TELECOMMUNICATIONS | TRANSPORTATION | TRAVEL
Twilio/TCR business industry. business.websitestringrequired- Must be live (no login wall) — carriers visit it.
business.addressobjectrequired- Registered business address.
business.address.streetstringrequiredbusiness.address.citystringrequiredbusiness.address.regionstringrequired- State/province abbreviation, e.g. TX.
business.address.postal_codestringrequiredbusiness.address.iso_countrystring- ISO-3166-1 alpha-2 country code. Defaults to 'US'.
business.emailstringrequired- Use a domain email; free webmail gets flagged.
business.regions_of_operationstring- Defaults to USA_AND_CANADA.
representativeobjectrequired- Authorized representative (E.164 mobile).
representative.first_namestringrequiredrepresentative.last_namestringrequiredrepresentative.business_titlestringrequired- Official job title, e.g. CEO or Owner.
representative.job_positionenumrequired- CEO | CFO | Director | GM | VP | General Counsel | Other
TCR-recognised job position for the authorised representative. representative.emailstringrequiredrepresentative.mobilestringrequired- E.164 mobile, e.g. +15125550100.
campaignobjectrequired- Texting program / campaign.
campaign.descriptionstringrequired- Use-case description, ≥40 chars — the #1 thing carriers read.
campaign.sample_messagesstring[]required- ≥2 sample messages, each ≥20 chars.
campaign.use_caseenumrequired- LOW_VOLUME | MIXED | MARKETING
REQUIRED campaign tier — LOW_VOLUME (Low Volume Mixed, cheapest, fits most single businesses), MIXED, or MARKETING. Sets the monthly fee and is LOCKED once the campaign is created (TCR can't change it after) — confirm the choice with the user first. consentobjectrequired- How contacts opt in (opt_in_method + a ≥40-char opt_in_description) plus the brand's own live Privacy Policy and Terms URLs — both REQUIRED; Sequence submits them to carriers verbatim and never hosts or substitutes them.
consent.opt_in_methodstringrequiredconsent.opt_in_urlstring- URL of the brand's opt-in form, if consent is collected on a web form.
consent.privacy_urlstringrequired- REQUIRED — the brand's own LIVE Privacy Policy URL (usually on their website, e.g. https://example.com/privacy). Ask the user for it or find it on the brand's site, and verify it loads (200). Sequence does not host compliance pages; carriers fetch this URL and a dead link is an automatic campaign rejection.
consent.terms_urlstringrequired- REQUIRED — the brand's own LIVE Terms & Conditions URL. Same rules as privacy_url: ask the user or find it on the brand's site, and verify it loads before submitting.
consent.opt_in_descriptionstringrequiredsms_forward_tostring- Customer texts are copied to this phone with a link to the Inbox. E.164.
confirmboolean- Leave false/omitted to get a preview (creates + charges nothing). Set true ONLY after the user has approved the previewed tier + samples — this registers and bills.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
get_sms_sender
Get this team's SMS sender, refreshing brand + campaign status from Twilio. Returns { sender, status_summary (brand→campaign→number→messaging-service stepper), last_checked_at }. 404 if no sender is registered yet.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
update_sms_sender
Update this team's SMS reply-forwarding number without contacting Twilio or changing brand, campaign, or phone registration. Returns the saved sender and its stored status summary. Pass null to disable forwarding.
sms_forward_tostring | nullrequired- Customer texts are copied to this phone with a link to the Inbox. A US/Canada phone number (E.164 or formatted, e.g. +15618230854). Required; null disables forwarding.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
verify_sms_sender
Re-poll the SMS sender's carrier status; if it was rejected, optionally resubmit the campaign by supplying a corrected wizard payload in the body (the rejection reason is surfaced in status_summary.blocking_reason). Bare POST with no body polls without resubmitting. Forwarding updates are rejected: omit sms_forward_to and use update_sms_sender separately. Like verify_domain but campaign approval takes hours to days.
businessobject- Corrected business facts for resubmit (omit to poll only).
business.legal_namestringrequiredbusiness.entity_typeenumrequired- LIMITED_LIABILITY_COMPANY | CORPORATION | PARTNERSHIP | NON_PROFIT
business.einstringrequiredbusiness.industryenumrequired- AGRICULTURE | AUTOMOTIVE | BANKING | CONSTRUCTION | CONSUMER | EDUCATION | ELECTRONICS | ENERGY | ENGINEERING | FAST_MOVING_CONSUMER_GOODS | FINANCIAL | FINTECH | FOOD_AND_BEVERAGE | GOVERNMENT | HEALTHCARE | HOSPITALITY | INSURANCE | JEWELRY | LEGAL | MANUFACTURING | MEDIA | NOT_FOR_PROFIT | OIL_AND_GAS | ONLINE | PROFESSIONAL_SERVICES | RAW_MATERIALS | REAL_ESTATE | RELIGION | RETAIL | TECHNOLOGY | TELECOMMUNICATIONS | TRANSPORTATION | TRAVEL
business.websitestringrequiredbusiness.addressobjectrequiredbusiness.address.streetstringrequiredbusiness.address.citystringrequiredbusiness.address.regionstringrequiredbusiness.address.postal_codestringrequiredbusiness.address.iso_countrystringbusiness.emailstringrequiredbusiness.regions_of_operationstringrepresentativeobject- Corrected representative for resubmit (omit to poll only).
representative.first_namestringrequiredrepresentative.last_namestringrequiredrepresentative.business_titlestringrequiredrepresentative.job_positionenumrequired- CEO | CFO | Director | GM | VP | General Counsel | Other
representative.emailstringrequiredrepresentative.mobilestringrequiredcampaignobject- Corrected campaign for resubmit (omit to poll only). use_case is locked at first campaign creation — resubmit keeps the original tier.
campaign.descriptionstringrequiredcampaign.sample_messagesstring[]requiredcampaign.use_caseenumrequired- LOW_VOLUME | MIXED | MARKETING
consentobject- Corrected consent for resubmit (omit to poll only).
consent.opt_in_methodstringrequiredconsent.opt_in_urlstringconsent.privacy_urlstringrequired- The brand's own LIVE Privacy Policy URL — required; verify it loads.
consent.terms_urlstringrequired- The brand's own LIVE Terms & Conditions URL — required; verify it loads.
consent.opt_in_descriptionstringrequiredsms_forward_tostring- Deprecated here: rejected with settings_update_required. Omit this field and use update_sms_sender to change reply forwarding.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
delete_sms_sender
Tear down this team's SMS registration at Twilio (release number, delete messaging service) and drop the row. Irreversible.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
search_sms_numbers
Search buyable SMS-enabled US local numbers before adding one to the pool (read-only — buys nothing). Filter by area_code (local presence) and/or a `contains` digit pattern (e.g. a memorable number). Returns candidate numbers; pass one to add_sms_number as phone_number to buy that exact number.
area_codestring- 3-digit NANP area code, e.g. 919.
containsstring- Digit/pattern the number must contain, e.g. 5550 or a vanity string.
limitnumber- Max candidates to return (1–20, default 5).
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
list_sms_numbers
List the phone numbers currently in this team's SMS sender pool (all send under the one approved A2P campaign). Returns { numbers, primary }. 404 if no sender is registered; 422 if the sender has no messaging service yet.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
add_sms_number
Buy one SMS-enabled US number and add it to this team's sender pool — the way to get a second area code (e.g. an 803 alongside a 919). Pick by area_code (widens nationwide only if that code has no inventory), a `contains` pattern (hard requirement — fails rather than buying an unrelated number), or an explicit phone_number from search_sms_numbers. The number joins the existing campaign instantly (no new carrier review) and costs a recurring per-number fee. Requires a registered sender with a messaging service.
area_codestring- Preferred 3-digit area code, e.g. 803.
containsstring- Require this digit pattern; no match fails (won't buy an unrelated number).
phone_numberstring- Buy this exact E.164 number (e.g. from search_sms_numbers).
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
remove_sms_number
Release one number from this team's SMS pool (detaches it and stops its recurring fee — irreversible). Cannot remove the last number (delete_sms_sender tears down the whole registration instead). If the released number was the primary, another pool number takes its place.
phone_numberstringrequired- E.164 number to release, e.g. +18035551234.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.