TFN (Toll Free Numbers) Registration API
The Vonage TFN (Toll Free Numbers) Registration API allows you to manage Toll Free Number registrations in the US & Canada.
For more information, visit the Vonage Developer Portal.
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
The content creator, not an ISV or reseller
500Ericsson LM- Enter the full legal name of the content provider (end-customer) — not an ISV or reseller.
- The legal name must exactly match the name on official tax documents, such as the IRS CP 575 or 147C Letter. Even a missing period, dash, or abbreviation may result in rejection.
- If the business operates under a trade name, enter the legal name here and add the trade name in the Brand Name (DBA) field.
500101 Crawfords Corner RdStreet number and name.
500HolmdelCity name
500CAState or province. For the United States, use 2-character codes, e.g., ‘CA’ for California.
1021012Zip Code or postal code. For the United States, use a 5-digit ZIP code
USTwo-letter country code following the ISO 3166-2 standard
500https://www.vonage.comProvide a publicly available website link for the company/organization. Must be a valid URL.
500JohnFirst name of business contact.
500SmithLast name of business contact.
500john.smith@vonage.comEmail address must match the company, organization or brand (DBA) name if entered.
50012125551212Phone number of business contact. Must be a valid phone number in E.164 format without the + prefix.
500Vonage Holdings CorpIf applicable, the Brand name ‘Doing Business As (DBA)’.
- If your business operates under a trade name that is different from its official legal name, enter that name here (e.g., a product brand or service name).
- Leave blank if not applicable.
- For Sole Proprietors, if you operate under your own name, leave this field blank.
500https://www.vonage.com/legal/messaging-service-supplementary-terms/Provide a publicly accessible Terms & Conditions link for the company/organization. Submissions with a missing, inaccessible, or blank URL will be rejected. The Terms must include:
- program/brand name, program description
- "message and data rates may apply" disclosure
- message frequency (or recurring message disclosure)
- customer support contact
- opt-out instructions (HELP and STOP)
- a link to the Privacy Policy
- the disclosure that states "Carriers are not liable for delayed or undelivered messages."
- relevant disclosures present at opt-in
- if using a web form for opt-in, this link must also appear on the opt-in page
500https://www.vonage.com/legal/privacy-policy/Provide a publicly accessible Privacy Policy link for the company/organization. Submissions with a missing, inaccessible, or blank URL will be rejected. The policy must state:
- what data you collect and how it's used, and
- that mobile information and opt-in consent will not be shared with third parties or affiliates for marketing or promotional purposes.
PRIVATE_PROFITSelect the legal classification that accurately describes the organization sending messages.
- The entity type selected must be entirely accurate, as an incorrect selection may result in rejection.
- If you select Sole Proprietor and do not have an EIN or CBN, you are not required to fill in any of the Tax Identifier fields.
SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENTEINEINSelect the tax classification that matches your organization's country of registration:
- US businesses: Select EIN (Employer Identification Number / Federal Tax ID)
- Canadian businesses: Select CBN (Canadian Business Number), NEQ - (Numéro d'entreprise du Québec) or Provincial Number
- Other countries: Select the relevant option for your country, or select Other.
- Sole Proprietors: If you select Sole Proprietor and do not have an EIN or CBN, leave this field blank. Additional validation checks will apply.
EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER50012-3456789Enter the tax identification number that corresponds to the Tax Identifier Type selected. This number must exactly match the legal entity name entered in the Official Entity Name field.
- US businesses (EIN): Enter your 9-digit Employer Identification Number in the format XX-XXXXXXX (e.g., 12-3456789). This must match the name on your IRS CP 575 or 147C Letter exactly
- Canadian businesses (CBN): Enter your 9-digit Canada Business Number in the format XXXXXXXXX (e.g., 123456789)
- Other countries: Enter the official business registration number issued by your national or local business authority
- Sole Proprietors: If you do not have an EIN or CBN, you may leave this field blank, and you are not required to fill in the Tax Identifier Type or Tax Identifier Issuing Country fields either. Your submission will undergo additional validation checks to confirm sole proprietorship status. Note: if you do have an EIN or CBN, you must enter it here and select the appropriate (non-Sole Proprietor) Entity Type
2USSelect the country that issued your tax identifier. This should be the country where your business is legally registered — not necessarily where you are located. Sole Proprietors: If you do not have an EIN or CBN, leave this field blank. Use the two-character ISO 3166 country code format (e.g., US, CA, GB, AU). For a full list of country codes, visit iso.org/obp/ui.
10,000Estimated monthly message volume.
101001,00010,000100,000250,000500,000750,0001,000,0005,000,00010,000,000+ISV/Reseller initiating the registration on behalf of the customer.
Note: This is only required for ISV and resellers.
500Reseller ABCIf you are an ISV/Reseller, enter the name of your business.
500john.doe@resellerabc.comVonage will only communicate with this email address for ISV/Reseller submissions. Must be a valid email.
List all toll-free phone numbers to be registered. Add up to 5 TFNs.
111118001234567Must be a valid purchased TFN in E.164 international format without the + prefix. Should always start with prefix 1800, 1888, 1877, 1866, 1855, 1844, or 1833.
149Two numbers are for two sales regions, one number per region to manage and track the business (East and West)This field is required when multiple numbers are included in the registration. Provide a clear reason for each number to get multiple numbers verified for messaging services.
Describes the use case.
PoliticalUse case category that represents your business industry; choose “Mixed” if marketing and alerts.
2FAApp NotificationsAppointmentsAuctionsAuto / Dealership ServicesBankingBillingBooking ConfirmationsBusiness UpdatesCOVID-19 AlertsCareer TrainingChatbotConversational / AlertsCourier Services & DeliveriesEducationalEmergency AlertsEmployee Alerts / NotificationsEvents & PlanningFinancial ServicesFraud AlertsFundraisingGeneral MarketingHR / StaffingHealthcareHousing Community UpdatesInsurance ServicesJob AlertsLegal ServicesMixedMotivational RemindersNotary NotificationsNotificationsOrder NotificationsPoliticalPublic WorksReal Estate ServicesReceipt NotificationsReligious ServicesRepair and Diagnostics AlertsRewards ProgramSurveysSystem AlertsWaitlist AlertsWebinar RemindersWorkshop Alerts500This Toll-Free Number will be used to deliver opt-in SMS communications, such as one-time passwords (OTPs), alerts, and notifications, to end users who have provided explicit consent.Describe the business reason for the selected use case, and enter any other important information about this request.
500cv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgRNote: This field is required only when the use_case category is set to "Political".
If you do not have a token, visit Campaign Verify at https://www.campaignverify.org/ to get started. A valid token follows a specific, pipe-delimited format, comprised of six fields: cv|1.0|mno|tfree|UUID|SecretString
- cv: A constant prefix indicating a Campaign Verify token.
- 1.0: The token version number (currently 1.0).
- mno: The Service ID for Toll-Free numbers (for 10DLC, this would be tcr).
- tfree: The Channel ID for Toll-Free.
- UUID: A unique identifier specific to your verified committee/brand.
- SecretString: A unique, 32-bit URL-safe random string.
1000[Candidate/Org Name]: You’re invited to a community meeting on [Date] at [Location]. RSVP here: [URL]. Message frequency varies. Reply STOP to end.Provide an example of a message to be sent, up to 1000 characters.
Select 'true' if your messages include content that is legally restricted to certain age groups over 21 years of age (e.g., alcohol, gambling, adult content).
On your website:
- Provide the end user's birth date (MM/DD/YYYY) to receive promotional/alert messages.
- On the bottom, add instructions that "If a user is too young to purchase, then place a hold on sending messages until age appropriate."
On end user's mobile device:
- Double Opt-In age gate text message flow includes a Birthdate entry field End user receives opt-in message from an online/mobile site. Example: [Brand Name]: Welcome! Reply with your "birthdate" (MM/DD/YYYY) to successfully sign-up for promotional/alerts messages from _____ (content provider name). Reply STOP to cancel. End user sends message in this format - MM/DD/YYYY - If user replies with age of 21+ then add to opt-in list and send opt-in confirmation message. Example: [Brand Name]: Welcome! Msg frequency varies. Msg & data rates may apply. For support, reply HELP for STOP to cancel.
OtherSelect consent method collected from the message recipient.
Online (website, Mobile app/browser)Text-to-joinPoint of saleOther494Paper-based opt-in form: End-customer consent may be obtained via a paper form. The form requires the end user to enter their mobile phone number and affirmatively select a consent checkbox stating “I agree to receive text messages.” The signed and completed form constitutes valid opt-in documentation.Note: This field is required only when the workflow is set to "Other".
Describe the opt-in process where consent is collected from the message recipient.
https://drive.google.com/file/d/screenshot1/view- Provide a shared link or publicly accessible link to a screenshot
- Do not add any additional content, i.e. "here's a list"
Provide one or more opt-in keywords that trigger an auto-response message to the recipient.
160[Vonage]: Welcome! You've signed up for alert messages. Msg freq varies. Msg&data rates may apply. Reply HELP for info, STOP to opt-out.The opt-in message responds to the recipient with your brand name, welcome, use case category and helpful hints.
Note: SMS response message is limited to 160 characters for compliance purposes.
160[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.comThe HELP keyword confirmation message sent to a user should contain your Brand name and two (2) contact methods, such as a toll-free number, email address or a link to a customer support page.
Note: SMS response message is limited to 160 characters for compliance purposes.
350This is test additional information.Provide any additional information.
SUBMITTEDThe submission status of the registration.
SUBMITTEDDRAFTEjemplo Solicitar
{
"business": {
"name": "Ericsson LM",
"address": {
"street": "101 Crawfords Corner Rd",
"city": "Holmdel",
"state": "CA",
"postal_code": "21012",
"country": "US"
},
"company_website": "https://www.vonage.com",
"contact": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@vonage.com",
"phone": "12125551212"
},
"dba": "Vonage Holdings Corp",
"terms_and_conditions_url": "https://www.vonage.com/legal/messaging-service-supplementary-terms/",
"privacy_policy_url": "https://www.vonage.com/legal/privacy-policy/",
"entity_type": "PRIVATE_PROFIT",
"tax_id_type": "EIN",
"tax_id": "12-3456789",
"tax_id_issuing_country": "US"
},
"estimated_monthly_volume": "10,000",
"isv_reseller": {
"name": "Reseller ABC",
"contact_email": "john.doe@resellerabc.com"
},
"requested_numbers": [
{
"number": "18001234567",
"business_reason": "Two numbers are for two sales regions, one number per region to manage and track the business (East and West)"
}
],
"use_case": {
"category": "Political",
"description": "This Toll-Free Number will be used to deliver opt-in SMS communications, such as one-time passwords (OTPs), alerts, and notifications, to end users who have provided explicit consent.",
"campaign_verify_auth_token": "cv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgR"
},
"message_content": {
"content": "[Candidate/Org Name]: You’re invited to a community meeting on [Date] at [Location]. RSVP here: [URL]. Message frequency varies. Reply STOP to end.",
"age_gated": false
},
"opt_in": {
"workflow": "Other",
"workflow_description": "Paper-based opt-in form: End-customer consent may be obtained via a paper form. The form requires the end user to enter their mobile phone number and affirmatively select a consent checkbox stating “I agree to receive text messages.” The signed and completed form constitutes valid opt-in documentation.",
"images": [
{
"url": "https://drive.google.com/file/d/screenshot1/view"
},
{
"url": "https://drive.google.com/file/d/screenshot2/view"
}
],
"keywords": [
"JOIN",
"START",
"YES"
],
"confirmation_message": "[Vonage]: Welcome! You've signed up for alert messages. Msg freq varies. Msg&data rates may apply. Reply HELP for info, STOP to opt-out.",
"help_message": "[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.com"
},
"additional_information": "This is test additional information.",
"status": "SUBMITTED"
}Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
3fa85f64-5717-4562-b3fc-2c963f66afa6Unique identifier of a registration
The content creator, not an ISV or reseller
500Ericsson LM- Enter the full legal name of the content provider (end-customer) — not an ISV or reseller.
- The legal name must exactly match the name on official tax documents, such as the IRS CP 575 or 147C Letter. Even a missing period, dash, or abbreviation may result in rejection.
- If the business operates under a trade name, enter the legal name here and add the trade name in the Brand Name (DBA) field.
500101 Crawfords Corner RdStreet number and name.
500HolmdelCity name
500CAState or province. For the United States, use 2-character codes, e.g., ‘CA’ for California.
1021012Zip Code or postal code. For the United States, use a 5-digit ZIP code
USTwo-letter country code following the ISO 3166-2 standard
500https://www.vonage.comProvide a publicly available website link for the company/organization. Must be a valid URL.
500JohnFirst name of business contact.
500SmithLast name of business contact.
500john.smith@vonage.comEmail address must match the company, organization or brand (DBA) name if entered.
50012125551212Phone number of business contact. Must be a valid phone number in E.164 format without the + prefix.
500Vonage Holdings CorpIf applicable, the Brand name ‘Doing Business As (DBA)’.
- If your business operates under a trade name that is different from its official legal name, enter that name here (e.g., a product brand or service name).
- Leave blank if not applicable.
- For Sole Proprietors, if you operate under your own name, leave this field blank.
500https://www.vonage.com/legal/messaging-service-supplementary-terms/Provide a publicly accessible Terms & Conditions link for the company/organization. Submissions with a missing, inaccessible, or blank URL will be rejected. The Terms must include:
- program/brand name, program description
- "message and data rates may apply" disclosure
- message frequency (or recurring message disclosure)
- customer support contact
- opt-out instructions (HELP and STOP)
- a link to the Privacy Policy
- the disclosure that states "Carriers are not liable for delayed or undelivered messages."
- relevant disclosures present at opt-in
- if using a web form for opt-in, this link must also appear on the opt-in page
500https://www.vonage.com/legal/privacy-policy/Provide a publicly accessible Privacy Policy link for the company/organization. Submissions with a missing, inaccessible, or blank URL will be rejected. The policy must state:
- what data you collect and how it's used, and
- that mobile information and opt-in consent will not be shared with third parties or affiliates for marketing or promotional purposes.
PRIVATE_PROFITSelect the legal classification that accurately describes the organization sending messages.
- The entity type selected must be entirely accurate, as an incorrect selection may result in rejection.
- If you select Sole Proprietor and do not have an EIN or CBN, you are not required to fill in any of the Tax Identifier fields.
SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENTEINEINSelect the tax classification that matches your organization's country of registration:
- US businesses: Select EIN (Employer Identification Number / Federal Tax ID)
- Canadian businesses: Select CBN (Canadian Business Number), NEQ - (Numéro d'entreprise du Québec) or Provincial Number
- Other countries: Select the relevant option for your country, or select Other.
- Sole Proprietors: If you select Sole Proprietor and do not have an EIN or CBN, leave this field blank. Additional validation checks will apply.
EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER50012-3456789Enter the tax identification number that corresponds to the Tax Identifier Type selected. This number must exactly match the legal entity name entered in the Official Entity Name field.
- US businesses (EIN): Enter your 9-digit Employer Identification Number in the format XX-XXXXXXX (e.g., 12-3456789). This must match the name on your IRS CP 575 or 147C Letter exactly
- Canadian businesses (CBN): Enter your 9-digit Canada Business Number in the format XXXXXXXXX (e.g., 123456789)
- Other countries: Enter the official business registration number issued by your national or local business authority
- Sole Proprietors: If you do not have an EIN or CBN, you may leave this field blank, and you are not required to fill in the Tax Identifier Type or Tax Identifier Issuing Country fields either. Your submission will undergo additional validation checks to confirm sole proprietorship status. Note: if you do have an EIN or CBN, you must enter it here and select the appropriate (non-Sole Proprietor) Entity Type
2USSelect the country that issued your tax identifier. This should be the country where your business is legally registered — not necessarily where you are located. Sole Proprietors: If you do not have an EIN or CBN, leave this field blank. Use the two-character ISO 3166 country code format (e.g., US, CA, GB, AU). For a full list of country codes, visit iso.org/obp/ui.
ISV/Reseller initiating the registration on behalf of the customer.
Note: This is only required for ISV and resellers.
500Reseller ABCIf you are an ISV/Reseller, enter the name of your business.
500john.doe@resellerabc.comVonage will only communicate with this email address for ISV/Reseller submissions. Must be a valid email.
10,000Estimated monthly message volume.
101001,00010,000100,000250,000500,000750,0001,000,0005,000,00010,000,000+TFN number details
111118001234567Must be a valid purchased TFN in E.164 international format without the + prefix. Should always start with prefix 1800, 1888, 1877, 1866, 1855, 1844, or 1833.
PENDING_REVIEWThe verification status of the tfn.
UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKEDSUBMITTEDDisallowedContent - GamblingReason the number is rejected for tfn registration
149Two numbers are for two sales regions, one number per region to manage and track the business (East and West)This field is required when multiple numbers are included in the registration. Provide a clear reason for each number to get multiple numbers verified for messaging services.
Describes the use case.
PoliticalUse case category that represents your business industry; choose “Mixed” if marketing and alerts.
2FAApp NotificationsAppointmentsAuctionsAuto / Dealership ServicesBankingBillingBooking ConfirmationsBusiness UpdatesCOVID-19 AlertsCareer TrainingChatbotConversational / AlertsCourier Services & DeliveriesEducationalEmergency AlertsEmployee Alerts / NotificationsEvents & PlanningFinancial ServicesFraud AlertsFundraisingGeneral MarketingHR / StaffingHealthcareHousing Community UpdatesInsurance ServicesJob AlertsLegal ServicesMixedMotivational RemindersNotary NotificationsNotificationsOrder NotificationsPoliticalPublic WorksReal Estate ServicesReceipt NotificationsReligious ServicesRepair and Diagnostics AlertsRewards ProgramSurveysSystem AlertsWaitlist AlertsWebinar RemindersWorkshop Alerts500This Toll-Free Number will be used to deliver opt-in SMS communications, such as one-time passwords (OTPs), alerts, and notifications, to end users who have provided explicit consent.Describe the business reason for the selected use case, and enter any other important information about this request.
500cv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgRNote: This field is required only when the use_case category is set to "Political".
If you do not have a token, visit Campaign Verify at https://www.campaignverify.org/ to get started. A valid token follows a specific, pipe-delimited format, comprised of six fields: cv|1.0|mno|tfree|UUID|SecretString
- cv: A constant prefix indicating a Campaign Verify token.
- 1.0: The token version number (currently 1.0).
- mno: The Service ID for Toll-Free numbers (for 10DLC, this would be tcr).
- tfree: The Channel ID for Toll-Free.
- UUID: A unique identifier specific to your verified committee/brand.
- SecretString: A unique, 32-bit URL-safe random string.
The expiration date of the Campaign Verify token. This field is applicable only to Political use cases. New tokens typically remain valid for 2 years from the date of issue.
1000[Candidate/Org Name]: You’re invited to a community meeting on [Date] at [Location]. RSVP here: [URL]. Message frequency varies. Reply STOP to end.Provide an example of a message to be sent, up to 1000 characters.
Select 'true' if your messages include content that is legally restricted to certain age groups over 21 years of age (e.g., alcohol, gambling, adult content).
On your website:
- Provide the end user's birth date (MM/DD/YYYY) to receive promotional/alert messages.
- On the bottom, add instructions that "If a user is too young to purchase, then place a hold on sending messages until age appropriate."
On end user's mobile device:
- Double Opt-In age gate text message flow includes a Birthdate entry field End user receives opt-in message from an online/mobile site. Example: [Brand Name]: Welcome! Reply with your "birthdate" (MM/DD/YYYY) to successfully sign-up for promotional/alerts messages from _____ (content provider name). Reply STOP to cancel. End user sends message in this format - MM/DD/YYYY - If user replies with age of 21+ then add to opt-in list and send opt-in confirmation message. Example: [Brand Name]: Welcome! Msg frequency varies. Msg & data rates may apply. For support, reply HELP for STOP to cancel.
OtherSelect consent method collected from the message recipient.
Online (website, Mobile app/browser)Text-to-joinPoint of saleOther494Paper-based opt-in form: End-customer consent may be obtained via a paper form. The form requires the end user to enter their mobile phone number and affirmatively select a consent checkbox stating “I agree to receive text messages.” The signed and completed form constitutes valid opt-in documentation.Note: This field is required only when the workflow is set to "Other".
Describe the opt-in process where consent is collected from the message recipient.
https://drive.google.com/file/d/screenshot1/view- Provide a shared link or publicly accessible link to a screenshot
- Do not add any additional content, i.e. "here's a list"
Provide one or more opt-in keywords that trigger an auto-response message to the recipient.
160[Vonage]: Welcome! You've signed up for alert messages. Msg freq varies. Msg&data rates may apply. Reply HELP for info, STOP to opt-out.The opt-in message responds to the recipient with your brand name, welcome, use case category and helpful hints.
Note: SMS response message is limited to 160 characters for compliance purposes.
160[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.comThe HELP keyword confirmation message sent to a user should contain your Brand name and two (2) contact methods, such as a toll-free number, email address or a link to a customer support page.
Note: SMS response message is limited to 160 characters for compliance purposes.
350This is test additional information.Provide any additional information.
SUBMITTEDThe submission status of the registration.
SUBMITTEDDRAFT2026-04-01T10:36:07.664896ZThe date and time of creation.
2026-04-16T13:15:58.07686ZThe date and time of last update.
2026-04-01T10:36:07.664896ZThe date and time of submission.
Ejemplo Respuesta
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"business": {
"name": "Ericsson LM",
"address": {
"street": "101 Crawfords Corner Rd",
"city": "Holmdel",
"state": "CA",
"postal_code": "21012",
"country": "US"
},
"company_website": "https://www.vonage.com",
"contact": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@vonage.com",
"phone": "12125551212"
},
"dba": "Vonage Holdings Corp",
"terms_and_conditions_url": "https://www.vonage.com/legal/messaging-service-supplementary-terms/",
"privacy_policy_url": "https://www.vonage.com/legal/privacy-policy/",
"entity_type": "PRIVATE_PROFIT",
"tax_id_type": "EIN",
"tax_id": "12-3456789",
"tax_id_issuing_country": "US"
},
"isv_reseller": {
"name": "Reseller ABC",
"contact_email": "john.doe@resellerabc.com"
},
"estimated_monthly_volume": "10,000",
"requested_numbers": [
{
"number": "18001234567",
"status": "PENDING_REVIEW",
"rejected_reason": "DisallowedContent - Gambling",
"business_reason": "Two numbers are for two sales regions, one number per region to manage and track the business (East and West)"
}
],
"use_case": {
"category": "Political",
"description": "This Toll-Free Number will be used to deliver opt-in SMS communications, such as one-time passwords (OTPs), alerts, and notifications, to end users who have provided explicit consent.",
"campaign_verify_auth_token": "cv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgR",
"campaign_verify_expiry_date": "2019-08-24T14:15:22Z"
},
"message_content": {
"content": "[Candidate/Org Name]: You’re invited to a community meeting on [Date] at [Location]. RSVP here: [URL]. Message frequency varies. Reply STOP to end.",
"age_gated": false
},
"opt_in": {
"workflow": "Other",
"workflow_description": "Paper-based opt-in form: End-customer consent may be obtained via a paper form. The form requires the end user to enter their mobile phone number and affirmatively select a consent checkbox stating “I agree to receive text messages.” The signed and completed form constitutes valid opt-in documentation.",
"images": [
{
"url": "https://drive.google.com/file/d/screenshot1/view"
},
{
"url": "https://drive.google.com/file/d/screenshot2/view"
}
],
"keywords": [
"JOIN",
"START",
"YES"
],
"confirmation_message": "[Vonage]: Welcome! You've signed up for alert messages. Msg freq varies. Msg&data rates may apply. Reply HELP for info, STOP to opt-out.",
"help_message": "[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.com"
},
"additional_information": "This is test additional information.",
"status": "SUBMITTED",
"creation_date": "2026-04-01T10:36:07.664896Z",
"last_update_date": "2026-04-16T13:15:58.07686Z",
"submission_date": "2026-04-01T10:36:07.664896Z"
}Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
The content creator, not an ISV or reseller
500Ericsson LM- Enter the full legal name of the content provider (end-customer) — not an ISV or reseller.
- The legal name must exactly match the name on official tax documents, such as the IRS CP 575 or 147C Letter. Even a missing period, dash, or abbreviation may result in rejection.
- If the business operates under a trade name, enter the legal name here and add the trade name in the Brand Name (DBA) field.
500101 Crawfords Corner RdStreet number and name.
500HolmdelCity name
500CAState or province. For the United States, use 2-character codes, e.g., ‘CA’ for California.
1021012Zip Code or postal code. For the United States, use a 5-digit ZIP code
USTwo-letter country code following the ISO 3166-2 standard
500https://www.vonage.comProvide a publicly available website link for the company/organization. Must be a valid URL.
500JohnFirst name of business contact.
500SmithLast name of business contact.
500john.smith@vonage.comEmail address must match the company, organization or brand (DBA) name if entered.
50012125551212Phone number of business contact. Must be a valid phone number in E.164 format without the + prefix.
500Vonage Holdings CorpIf applicable, the Brand name ‘Doing Business As (DBA)’.
- If your business operates under a trade name that is different from its official legal name, enter that name here (e.g., a product brand or service name).
- Leave blank if not applicable.
- For Sole Proprietors, if you operate under your own name, leave this field blank.
500https://www.vonage.com/legal/messaging-service-supplementary-terms/Provide a publicly accessible Terms & Conditions link for the company/organization. Submissions with a missing, inaccessible, or blank URL will be rejected. The Terms must include:
- program/brand name, program description
- "message and data rates may apply" disclosure
- message frequency (or recurring message disclosure)
- customer support contact
- opt-out instructions (HELP and STOP)
- a link to the Privacy Policy
- the disclosure that states "Carriers are not liable for delayed or undelivered messages."
- relevant disclosures present at opt-in
- if using a web form for opt-in, this link must also appear on the opt-in page
500https://www.vonage.com/legal/privacy-policy/Provide a publicly accessible Privacy Policy link for the company/organization. Submissions with a missing, inaccessible, or blank URL will be rejected. The policy must state:
- what data you collect and how it's used, and
- that mobile information and opt-in consent will not be shared with third parties or affiliates for marketing or promotional purposes.
PRIVATE_PROFITSelect the legal classification that accurately describes the organization sending messages.
- The entity type selected must be entirely accurate, as an incorrect selection may result in rejection.
- If you select Sole Proprietor and do not have an EIN or CBN, you are not required to fill in any of the Tax Identifier fields.
SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENTEINEINSelect the tax classification that matches your organization's country of registration:
- US businesses: Select EIN (Employer Identification Number / Federal Tax ID)
- Canadian businesses: Select CBN (Canadian Business Number), NEQ - (Numéro d'entreprise du Québec) or Provincial Number
- Other countries: Select the relevant option for your country, or select Other.
- Sole Proprietors: If you select Sole Proprietor and do not have an EIN or CBN, leave this field blank. Additional validation checks will apply.
EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER50012-3456789Enter the tax identification number that corresponds to the Tax Identifier Type selected. This number must exactly match the legal entity name entered in the Official Entity Name field.
- US businesses (EIN): Enter your 9-digit Employer Identification Number in the format XX-XXXXXXX (e.g., 12-3456789). This must match the name on your IRS CP 575 or 147C Letter exactly
- Canadian businesses (CBN): Enter your 9-digit Canada Business Number in the format XXXXXXXXX (e.g., 123456789)
- Other countries: Enter the official business registration number issued by your national or local business authority
- Sole Proprietors: If you do not have an EIN or CBN, you may leave this field blank, and you are not required to fill in the Tax Identifier Type or Tax Identifier Issuing Country fields either. Your submission will undergo additional validation checks to confirm sole proprietorship status. Note: if you do have an EIN or CBN, you must enter it here and select the appropriate (non-Sole Proprietor) Entity Type
2USSelect the country that issued your tax identifier. This should be the country where your business is legally registered — not necessarily where you are located. Sole Proprietors: If you do not have an EIN or CBN, leave this field blank. Use the two-character ISO 3166 country code format (e.g., US, CA, GB, AU). For a full list of country codes, visit iso.org/obp/ui.
ISV/Reseller initiating the registration on behalf of the customer.
Note: This is only required for ISV and resellers.
500Reseller ABCIf you are an ISV/Reseller, enter the name of your business.
500john.doe@resellerabc.comVonage will only communicate with this email address for ISV/Reseller submissions. Must be a valid email.
10,000Estimated monthly message volume.
101001,00010,000100,000250,000500,000750,0001,000,0005,000,00010,000,000+List all toll-free phone numbers to be registered. Add up to 5 TFNs.
111118001234567Must be a valid purchased TFN in E.164 international format without the + prefix. Should always start with prefix 1800, 1888, 1877, 1866, 1855, 1844, or 1833.
149Two numbers are for two sales regions, one number per region to manage and track the business (East and West)This field is required when multiple numbers are included in the registration. Provide a clear reason for each number to get multiple numbers verified for messaging services.
Describes the use case.
PoliticalUse case category that represents your business industry; choose “Mixed” if marketing and alerts.
2FAApp NotificationsAppointmentsAuctionsAuto / Dealership ServicesBankingBillingBooking ConfirmationsBusiness UpdatesCOVID-19 AlertsCareer TrainingChatbotConversational / AlertsCourier Services & DeliveriesEducationalEmergency AlertsEmployee Alerts / NotificationsEvents & PlanningFinancial ServicesFraud AlertsFundraisingGeneral MarketingHR / StaffingHealthcareHousing Community UpdatesInsurance ServicesJob AlertsLegal ServicesMixedMotivational RemindersNotary NotificationsNotificationsOrder NotificationsPoliticalPublic WorksReal Estate ServicesReceipt NotificationsReligious ServicesRepair and Diagnostics AlertsRewards ProgramSurveysSystem AlertsWaitlist AlertsWebinar RemindersWorkshop Alerts500This Toll-Free Number will be used to deliver opt-in SMS communications, such as one-time passwords (OTPs), alerts, and notifications, to end users who have provided explicit consent.Describe the business reason for the selected use case, and enter any other important information about this request.
500cv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgRNote: This field is required only when the use_case category is set to "Political".
If you do not have a token, visit Campaign Verify at https://www.campaignverify.org/ to get started. A valid token follows a specific, pipe-delimited format, comprised of six fields: cv|1.0|mno|tfree|UUID|SecretString
- cv: A constant prefix indicating a Campaign Verify token.
- 1.0: The token version number (currently 1.0).
- mno: The Service ID for Toll-Free numbers (for 10DLC, this would be tcr).
- tfree: The Channel ID for Toll-Free.
- UUID: A unique identifier specific to your verified committee/brand.
- SecretString: A unique, 32-bit URL-safe random string.
1000[Candidate/Org Name]: You’re invited to a community meeting on [Date] at [Location]. RSVP here: [URL]. Message frequency varies. Reply STOP to end.Provide an example of a message to be sent, up to 1000 characters.
Select 'true' if your messages include content that is legally restricted to certain age groups over 21 years of age (e.g., alcohol, gambling, adult content).
On your website:
- Provide the end user's birth date (MM/DD/YYYY) to receive promotional/alert messages.
- On the bottom, add instructions that "If a user is too young to purchase, then place a hold on sending messages until age appropriate."
On end user's mobile device:
- Double Opt-In age gate text message flow includes a Birthdate entry field End user receives opt-in message from an online/mobile site. Example: [Brand Name]: Welcome! Reply with your "birthdate" (MM/DD/YYYY) to successfully sign-up for promotional/alerts messages from _____ (content provider name). Reply STOP to cancel. End user sends message in this format - MM/DD/YYYY - If user replies with age of 21+ then add to opt-in list and send opt-in confirmation message. Example: [Brand Name]: Welcome! Msg frequency varies. Msg & data rates may apply. For support, reply HELP for STOP to cancel.
OtherSelect consent method collected from the message recipient.
Online (website, Mobile app/browser)Text-to-joinPoint of saleOther494Paper-based opt-in form: End-customer consent may be obtained via a paper form. The form requires the end user to enter their mobile phone number and affirmatively select a consent checkbox stating “I agree to receive text messages.” The signed and completed form constitutes valid opt-in documentation.Note: This field is required only when the workflow is set to "Other".
Describe the opt-in process where consent is collected from the message recipient.
https://drive.google.com/file/d/screenshot1/view- Provide a shared link or publicly accessible link to a screenshot
- Do not add any additional content, i.e. "here's a list"
Provide one or more opt-in keywords that trigger an auto-response message to the recipient.
160[Vonage]: Welcome! You've signed up for alert messages. Msg freq varies. Msg&data rates may apply. Reply HELP for info, STOP to opt-out.The opt-in message responds to the recipient with your brand name, welcome, use case category and helpful hints.
Note: SMS response message is limited to 160 characters for compliance purposes.
160[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.comThe HELP keyword confirmation message sent to a user should contain your Brand name and two (2) contact methods, such as a toll-free number, email address or a link to a customer support page.
Note: SMS response message is limited to 160 characters for compliance purposes.
350This is test additional information.Provide any additional information.
SUBMITTEDSet to SUBMITTED to submit DRAFT registration. If omitted, the previous status is maintained.
SUBMITTEDEjemplo Solicitar
{
"business": {
"name": "Ericsson LM",
"address": {
"street": "101 Crawfords Corner Rd",
"city": "Holmdel",
"state": "CA",
"postal_code": "21012",
"country": "US"
},
"company_website": "https://www.vonage.com",
"contact": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@vonage.com",
"phone": "12125551212"
},
"dba": "Vonage Holdings Corp",
"terms_and_conditions_url": "https://www.vonage.com/legal/messaging-service-supplementary-terms/",
"privacy_policy_url": "https://www.vonage.com/legal/privacy-policy/",
"entity_type": "PRIVATE_PROFIT",
"tax_id_type": "EIN",
"tax_id": "12-3456789",
"tax_id_issuing_country": "US"
},
"isv_reseller": {
"name": "Reseller ABC",
"contact_email": "john.doe@resellerabc.com"
},
"estimated_monthly_volume": "10,000",
"requested_numbers": [
{
"number": "18001234567",
"business_reason": "Two numbers are for two sales regions, one number per region to manage and track the business (East and West)"
}
],
"use_case": {
"category": "Political",
"description": "This Toll-Free Number will be used to deliver opt-in SMS communications, such as one-time passwords (OTPs), alerts, and notifications, to end users who have provided explicit consent.",
"campaign_verify_auth_token": "cv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgR"
},
"message_content": {
"content": "[Candidate/Org Name]: You’re invited to a community meeting on [Date] at [Location]. RSVP here: [URL]. Message frequency varies. Reply STOP to end.",
"age_gated": false
},
"opt_in": {
"workflow": "Other",
"workflow_description": "Paper-based opt-in form: End-customer consent may be obtained via a paper form. The form requires the end user to enter their mobile phone number and affirmatively select a consent checkbox stating “I agree to receive text messages.” The signed and completed form constitutes valid opt-in documentation.",
"images": [
{
"url": "https://drive.google.com/file/d/screenshot1/view"
},
{
"url": "https://drive.google.com/file/d/screenshot2/view"
}
],
"keywords": [
"JOIN",
"START",
"YES"
],
"confirmation_message": "[Vonage]: Welcome! You've signed up for alert messages. Msg freq varies. Msg&data rates may apply. Reply HELP for info, STOP to opt-out.",
"help_message": "[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.com"
},
"additional_information": "This is test additional information.",
"status": "SUBMITTED"
}Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
3fa85f64-5717-4562-b3fc-2c963f66afa6Unique identifier of a registration
PENDING_REVIEWThe verification status of the tfn.
UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKEDSUBMITTEDThe provided use case description is insufficient. Please provide more details.Reason for the given status of TFN. The reason will be empty for statuses like REGISTERED or PENDING_REVIEW.
2026-04-01T10:36:07.664896ZThe date and time of creation.
10https://example:com/resource?page_size=10&cursor=19284743Ejemplo Respuesta
{
"_embedded": {
"events": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "PENDING_REVIEW",
"reason": "The provided use case description is insufficient. Please provide more details.",
"created_at": "2026-04-01T10:36:07.664896Z"
}
]
},
"page_size": 10,
"_links": {
"self": "https://example:com/resource?page_size=10&cursor=19284743"
}
}Operaciones disponibles
Deregister a toll-free number from a registration
Removes the specified toll-free number from its associated registration. If this is the last number linked to that registration, the registration will also be automatically deleted.
De-registration is supported for the following TFN statuses: REGISTERED, REJECTED, DRAFT, PENDING_REVIEW, and CARRIERS_REVIEW.
Important Notes:
- This endpoint only removes the TFN registration association. It does not remove the number from the customer's account. The number can be reused for other purposes (e.g., re-registered under a new use case/brand).
- If the number's status is
BLOCKED, de-registration is not permitted. - If the number is actively sending or receiving SMS/MMS traffic, de-registration will immediately block all messaging on that number. Ensure there are no active messaging campaigns running on this number before calling this endpoint.
- The behaviour of de-registration differs based on the current status of the TFN (see status-specific behaviour below).
Status-Specific Behaviour:
DRAFT
- Permanently deletes the draft registration and all entered data.
- No carrier implications apply as no submission has been made.
- Start a new registration at any time.
PENDING_REVIEW
- Withdraws the submission before carrier review begins.
- Messaging remains inactive until a new registration is submitted and approved.
CARRIERS_REVIEW
- Withdraws the submission and immediately cancels the carrier review — no decision will be issued.
- The review cannot be resumed; resubmitting restarts the process from the beginning.
- Messaging remains inactive until a new registration is approved.
REGISTERED
- Removes the registration from Vonage's records and our registration carrier partner's systems.
- Messaging stops immediately and remains blocked until a new registration is approved.
REJECTED
- Removes the registration from Vonage's records and our registration carrier partner's systems.
- Messaging remains blocked until a new registration is approved.
- Carrier-level restrictions may apply for a period outside Vonage's control.
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
Consulta Parámetros
19284743Cursor for pagination
10Number of results per page
PENDING_REVIEWFilter by number status
UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKEDSUBMITTED111118001234567Filter by specific toll-free number
3fa85f64-5717-4562-b3fc-2c963f66afa6Filter by specific registration ID
500Ericsson LMFuzzy search by business name
111118001234567Must be a valid purchased TFN in E.164 international format without the + prefix. Should always start with prefix 1800, 1888, 1877, 1866, 1855, 1844, or 1833.
PENDING_REVIEWThe verification status of the tfn.
UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKEDSUBMITTED500Ericsson LM- Enter the full legal name of the content provider (end-customer) — not an ISV or reseller.
- The legal name must exactly match the name on official tax documents, such as the IRS CP 575 or 147C Letter. Even a missing period, dash, or abbreviation may result in rejection.
- If the business operates under a trade name, enter the legal name here and add the trade name in the Brand Name (DBA) field.
3fa85f64-5717-4562-b3fc-2c963f66afa6Unique identifier of a registration
2026-04-01T10:36:07.664896ZThe date and time of submission.
2026-04-16T13:15:58.07686ZDate when the current status tfn was updated
10https://example:com/resource?page_size=10&cursor=19284743https://example:com/resource?page_size=10&cursor=19284743https://example:com/resource?page_size=10&cursor=19284743https://example:com/resource?page_size=10Ejemplo Respuesta
{
"_embedded": {
"numbers": [
{
"number": "18001234567",
"status": "PENDING_REVIEW",
"business_name": "Ericsson LM",
"registration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"submission_date": "2026-04-01T10:36:07.664896Z",
"status_change_date": "2026-04-16T13:15:58.07686Z"
}
]
},
"page_size": 10,
"_links": {
"self": "https://example:com/resource?page_size=10&cursor=19284743",
"next": "https://example:com/resource?page_size=10&cursor=19284743",
"prev": "https://example:com/resource?page_size=10&cursor=19284743",
"first": "https://example:com/resource?page_size=10"
}
}