Canonical Schema Reference
Valid values for all enum fields used in account and campaign registration. Every field listed here is read by a human reviewer, so use the most accurate value, not the most convenient one.
For context on how these fields fit into the registration flow, see Register via API.
Account fields
organization.type
The legal structure of your business.
| Value | Description |
|---|---|
co_op | Cooperative |
government | Government or government agency |
llc | Limited Liability Company |
non_profit | Non-profit organisation |
partnership | General or limited partnership |
private_corporation | Privately held corporation |
public_corporation | Publicly traded corporation |
sole_proprietor | Sole proprietorship (no EIN required; see Sole Proprietor Path) |
A common mistake: if your business name ends in "LLC" or "Inc.", use llc or private_corporation respectively, not sole_proprietor. Sole proprietors don't have an EIN and aren't incorporated.
organization.identifier_type
The type of business registration number you're providing.
| Value | Description |
|---|---|
ein | US Employer Identification Number (format: XX-XXXXXXX or XXXXXXXXX) |
cbn | Canadian Business Number (exactly 9 digits) |
More identifier types are on the roadmap. Contact support if your business uses a different identifier.
organization.industry
Choose the category that best matches your primary business activity.
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
organization.regions_of_operation
The geographic regions where your business operates. Accepts an array.
| Value | Description |
|---|---|
africa | Africa |
asia | Asia |
australia | Australia and Oceania |
europe | Europe |
latin_america | Latin America |
usa_and_canada | United States and Canada |
Most US-based businesses use ["usa_and_canada"].
organization.contact.title
The job title of the authorised representative submitting the registration.
| Value | Description |
|---|---|
ceo | Chief Executive Officer |
cfo | Chief Financial Officer |
director | Director |
gm | General Manager |
vp | Vice President |
general_counsel | General Counsel |
other | Any other title (set title_other to the specific title text) |
Campaign fields
use_cases
Accepts an array. Choose all that apply to your campaign. If your messages cover multiple cases, list them all.
| Value | Description |
|---|---|
account_notification | Account status updates (balance alerts, statement ready, etc.) |
customer_care | Support conversations, help desk, case updates |
delivery_notification | Shipping and delivery status |
fraud_alert | Fraud warnings and suspicious activity notices |
higher_education | Messages from colleges and universities |
marketing | Promotional content, offers, sales |
polling_voting | Polls, surveys, and voting campaigns |
public_service_announcement | Informational messages from government or non-profit orgs |
security_alert | Two-factor codes, login alerts |
two_factor_authentication | OTP codes for authentication |
For special use cases (political, proxy, sweepstakes, etc.) that don't appear here, contact support.
includes
Content types present in your messages. Required when applicable; leaving a flag unset when the content is present is a common reason for rejection.
| Value | Description |
|---|---|
links | Messages contain URLs |
phone_numbers | Messages contain phone numbers |
age_gated | Messages contain age-restricted content |
direct_lending | Messages are related to lending or financial products |
volume
Expected daily send volume to T-Mobile (the network with the strictest volume caps).
| Value | Description |
|---|---|
low | Up to 2,000 SMS segments per day to T-Mobile |
high | Up to 200,000 segments per day, subject to TCR trust score |
Start with low unless you're certain you'll exceed 2,000 messages per day. You can request a volume increase after your campaign is approved.
consent_flow
A written description of how recipients opted in to receive your messages. Must be between 40 and 4,096 characters. Reviewers check this against your actual opt-in flow, so be specific and accurate — vague descriptions like "users opt in on our website" are reliably rejected.
What to include:
- Where the opt-in happens (checkout page, signup form, paper form, etc.)
- The exact wording of the consent prompt or checkbox
- Whether consent is pre-checked (it shouldn't be) or unchecked by default
- The disclosures shown at the point of opt-in
See Consent Flows for templates and examples.
link_sample
A URL representing a link that will appear in your messages. Optional, but recommended if your campaign uses includes: ["links"].
Carriers use this field to establish your campaign's link domain. If you send links from a domain different from what you registered here, carriers are significantly more likely to filter those messages. If link shortening is enabled on your account, Surge substitutes the link shortener URL automatically — contact support to coordinate if you have a custom link-sample URL.
Example: "https://acme.com/track/12345"
Max length: 255 characters.
message_samples
An array of 2–5 real examples of messages you'll send. Each sample must be 20–1,024 characters. The canonical opt-out sample is:
"You are now opted in to messages from {brand name}. Frequency varies. Msg&data rates apply. Reply STOP to opt out."
Replace \{brand name\} with your actual brand name. Leaving template tokens like \{Agent Name\} or \{Agency\} unreplaced is a common rejection reason.
Variable content in templates should be indicated with square brackets rather than curly braces: [customer name], [order number]. Curly braces suggest placeholder tokens that weren't filled in.