Start a toll-free verification

Body Parameters

The body is optional.

• numbersarray of string

  Your live toll-free numbers this program texts from, E.164. One per business unless multiple_numbers_reason says why.

• multiple_numbers_reasonstring

  Why the program needs more than one number (one per store, say). Required with more than one number.

• business_namestring

  The legal name, as on the IRS EIN letter, optionally with "d/b/a" and the brand your messages carry. Example: Acme Plumbing LLC d/b/a Acme.

• einstring

  The EIN (US), matching the legal name; elsewhere the business registration number. Example: 12-3456789.

• entity_typePRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT, SOLE_PROPRIETOR
• streetstring
• citystring
• statestring
• postal_codestring
• countrystring

  Example: United States.

• contact_first_namestring
• contact_last_namestring
• contact_phonestring
• brand_emailstring

  The business's own email, for its customers: the HELP reply and the hosted opt-in page name it.

• websitestring (uri)
• use_case2fa, account_notification, customer_care, delivery_notification, fraud_alert, higher_education, marketing, mixed, polling_voting, public_service_announcement, security_alert, low_volume
• use_case_summarystring

  What the program sends, to whom and why. At least 40 characters. At most 1500 characters.

• sample_messagesarray of string

  At least two example messages. At most 8 items.

• help_replystring
• stop_replystring
• opt_in_descriptionstring

  How people opt in, step by step. At least 40 characters. At most 2000 characters.

• opt_in_urlstring (uri)

  The opt-in page. With none of your own we make you a hosted one.

• monthly_volumestring

  Example: About 1,000 messages per month.

• volume_basisexisting, projecting
• advertisingyes, no, unsure

  Whether the messages advertise a product or service.

• previous_servicenew, short_code, long_number

  Where this traffic ran before.

• previous_contentstring

  Sample messages from the previous service (not new only). At most 2000 characters.

• previous_numbersstring

  The numbers it used (not new only).

• number_publishedstring

  Where people see this number.

• fortune_500boolean
• urls_in_messagesstring

  Links your messages include, or "None".

• phones_in_messagesstring

  Phone numbers your messages include, or "None".

• terms_urlstring (uri)
• privacy_urlstring (uri)

Details

Any field you send replaces what we filled in. Returns a draft with problems: what the carriers would send it back for.

Nothing is sent anywhere until you submit it. A number can be on one verification at a time.

Responses

• 201TollFreeVerification

  Toll-free verification, status draft

• 400Error

  invalid_request: a field of the wrong type or value (param names it)

• 401Error

  Missing, malformed, or revoked API key

• 402Error

  Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

• 409Error

  invalid_state: a number is already on another verification, or another form is still open

• 429Error

  Rate limit or quota exceeded

Response Fields

• idstring

  Example: tfv_a1B2c3D4e5F6.

• objecttoll_free_verification
• statusdraft, in_review, submitted, verified, rejected

  draft: not submitted. in_review: our team is checking it by hand; nothing has gone to the carriers yet. submitted: we sent it to the carriers; waiting on their answer. verified: its numbers text anyone who opted in. rejected: sent back; rejection.reason says why.

• numbersarray of string
• business_namestring
• readyboolean

  Nothing the carriers require is missing (problems is empty).

• problemsarray of object

  What the carriers would send it back for, one entry per answer to fix.

• problems[].fieldstring

  Example: ein.

• problems[].messagestring
• editableboolean

  Whether PATCH may change it now (draft, in_review and rejected).

• next_actoryou, textkit, carriers, nobody

  Who acts next.

• formTollFreeVerificationInput

  The form as it stands, every field. contact_email is always our support address: the carriers write to us, and we forward what only you can answer.

• businessobject

  The business on the form, as business verification sees it. Nullable.

• business.statusnot_started, pending, verified, rejected
• business.attestation_neededboolean

  Submit needs an attestation for these business details.

• business.signedobject

  Nullable.

• business.signed.signer_namestring
• business.signed.signer_titlestring
• business.signed.signed_atstring (date-time)
• business.rejectionobject

  Nullable.

• business.rejection.codestring
• business.rejection.notestring

  Nullable.

• rejectionobject

  Set while rejected: what the carriers or our team asked for. Nullable.

• rejection.reasonstring
• rejection.rejected_atstring (date-time)
• carrier_referencestring

  The carriers' case number, once they give one. Nullable.

• registration_idstring

  The registration it was filled in from, if any. Nullable.

• historyarray of object
• history[].atstring (date-time)
• history[].statusdraft, in_review, submitted, verified, rejected
• history[].actorcustomer, staff, system, carrier
• history[].notestring

  Nullable.

• created_atstring (date-time)
• updated_atstring (date-time)

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

• 400

  invalid_request: a field of the wrong type or value (param names it)

• 401

  Missing, malformed, or revoked API key

• 402

  Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

• 409

  invalid_state: a number is already on another verification, or another form is still open

• 429

  Rate limit or quota exceeded