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.

Download OpenAPI Specification

Registrations

Endpoints allowing to create, get and update TFN registrations and get events.

Available Operations

Create a TFN registration

posthttps://api.nexmo.com/tfn/v1/registrations

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Request Body
Content Type
application/json

business
object
Required

The content creator, not an ISV or reseller

name
string
Required
Max500
exampleEricsson LM

Parent company or organization full name.

address
object
Required
street
string
Required
Max500
example101 Crawfords Corner Rd

Street number and name.

city
string
Required
Max500
exampleHolmdel

City name

state
string
Required
Max500
exampleCA

State or province. For the United States, use 2-character codes, e.g., ‘CA’ for California.

postal_code
string
Required
Max10
example21012

Zip Code or postal code. For the United States, use a 5-digit ZIP code

country
string
Required
exampleUS

Two-letter country code following the ISO 3166-2 standard

company_website
string
Required
Max500
examplehttps://www.vonage.com

Provide a publicly available website link for the company/organization. Must be a valid URL.

contact
object
Required
first_name
string
Required
Max500
exampleJohn

First name of business contact.

last_name
string
Required
Max500
exampleSmith

Last name of business contact.

email
string
Required
Max500
examplejohn.smith@vonage.com

Email address must match the company, organization or brand (DBA) name if entered.

phone
string(e164)
Required
Max500
example12125551212

Phone number of business contact. Must be a valid phone number in E.164 format without the + prefix.

dba
string
Max500
exampleVonage Holdings Corp

If applicable, the Brand name ‘Doing Business As (DBA)’.

terms_and_conditions_url
string
Max500
examplehttps://www.vonage.com/legal/messaging-service-supplementary-terms/

Provide Terms link for the company/organization. Must be a valid URL.

privacy_policy_url
string
Max500
examplehttps://www.vonage.com/legal/privacy-policy/

Provide a Privacy Policy link for the company/organization. Must be a valid URL.

entity_type
string
Required
examplePRIVATE_PROFIT

Legal classification for the company/organization.

Must be one of:SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENT
tax_id_type
string
Required
DefaultEIN
exampleEIN
  • For the US, a Federal Tax ID or Employee Identification Number (EIN) is required.
  • For Canada, the Canada Business Number (CBN) is required.
  • Sole Proprietorship may apply without an EIN/CBN, but there will be additional checks to validate that the provided information is accurate.
  • For other country-specific registration, select the relevant option or Other.
Must be one of:EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER
tax_id
string
Required
Max500
example12-3456789
  • For the US, provide the Employee Identification Number (EIN) for the company/organization.
  • For Canada, provide the Canada Business Number (CBN) for the company/organization.
  • For Sole Proprietorship, you may leave this field blank.
  • For country-specific registration types, provide the relevant Tax ID number.
tax_id_issuing_country
string
Required
Max2
exampleUS

Relevant issuing country. Two-letter ISO-2 country code.

estimated_monthly_volume
string
Required
example10,000

Estimated monthly message volume.

Must be one of:101001,00010,000100,000250,000500,000750,0001,000,0005,000,00010,000,000+
isv_reseller
object

ISV/Reseller initiating the registration on behalf of the customer.

Note: This is only required for ISV and resellers.

name
string
Max500
exampleReseller ABC

If you are an ISV/Reseller, enter the name of your business.

contact_email
string
Max500
examplejohn.doe@resellerabc.com

Vonage will only communicate with this email address for ISV/Reseller submissions. Must be a valid email.

requested_numbers
array
Required

List all toll-free phone numbers to be registered. Add up to 5 TFNs.

number
string(e164)
Required
Min11
Max11
example18001234567

Must 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.

business_reason
string
Max149
exampleTwo 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.

use_case
object
Required

Describes the use case.

category
string
Required
examplePolitical

Use case category that represents your business industry; choose “Mixed” if marketing and alerts.

Must be one of: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 Alerts
description
string
Required
Max500
exampleThis 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.

campaign_verify_auth_token
string
Max500
examplecv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgR

Note: 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.
message_content
object
Required
content
string
Required
Max1000
example[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.

age_gated
boolean

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:

  1. Provide the end user's birth date (MM/DD/YYYY) to receive promotional/alert messages.
  2. 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:

  1. 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.
opt_in
object
Required
workflow
string
Required
exampleOther

Select consent method collected from the message recipient.

Must be one of:Online (website, Mobile app/browser)Text-to-joinPoint of saleOther
workflow_description
string
Max494
examplePaper-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.

images
array
Required
url
string
Required
  • Provide a shared link or publicly accessible link to a screenshot
  • Do not add any additional content, i.e. "here's a list"
keywords
array

Provide one or more opt-in keywords that trigger an auto-response message to the recipient.

confirmation_message
string
Max160
example[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.

help_message
string
Max160
example[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.com

The 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.

additional_information
string
Required
Max350
exampleThis is test additional information.

Provide any additional information.

status
string

The submission status of the registration.

Must be one of:SUBMITTEDDRAFT

Example Request

{
   "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"
}

Responses
Content Type
application/hal+json

Successful response

id
string(uuid)
example3fa85f64-5717-4562-b3fc-2c963f66afa6

Unique identifier of a registration

Example Response

Example preview is currently not supported for content type: application/hal+json

Get the registration details by registration ID

gethttps://api.nexmo.com/tfn/v1/registrations/:id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

id
string(uuid)
Required
example3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses
Content Type
application/hal+json

Successful response

id
string(uuid)
example3fa85f64-5717-4562-b3fc-2c963f66afa6

Unique identifier of a registration

business
object

The content creator, not an ISV or reseller

name
string
Required
Max500
exampleEricsson LM

Parent company or organization full name.

address
object
Required
street
string
Required
Max500
example101 Crawfords Corner Rd

Street number and name.

city
string
Required
Max500
exampleHolmdel

City name

state
string
Required
Max500
exampleCA

State or province. For the United States, use 2-character codes, e.g., ‘CA’ for California.

postal_code
string
Required
Max10
example21012

Zip Code or postal code. For the United States, use a 5-digit ZIP code

country
string
Required
exampleUS

Two-letter country code following the ISO 3166-2 standard

company_website
string
Required
Max500
examplehttps://www.vonage.com

Provide a publicly available website link for the company/organization. Must be a valid URL.

contact
object
Required
first_name
string
Required
Max500
exampleJohn

First name of business contact.

last_name
string
Required
Max500
exampleSmith

Last name of business contact.

email
string
Required
Max500
examplejohn.smith@vonage.com

Email address must match the company, organization or brand (DBA) name if entered.

phone
string(e164)
Required
Max500
example12125551212

Phone number of business contact. Must be a valid phone number in E.164 format without the + prefix.

dba
string
Max500
exampleVonage Holdings Corp

If applicable, the Brand name ‘Doing Business As (DBA)’.

terms_and_conditions_url
string
Max500
examplehttps://www.vonage.com/legal/messaging-service-supplementary-terms/

Provide Terms link for the company/organization. Must be a valid URL.

privacy_policy_url
string
Max500
examplehttps://www.vonage.com/legal/privacy-policy/

Provide a Privacy Policy link for the company/organization. Must be a valid URL.

entity_type
string
Required
examplePRIVATE_PROFIT

Legal classification for the company/organization.

Must be one of:SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENT
tax_id_type
string
Required
DefaultEIN
exampleEIN
  • For the US, a Federal Tax ID or Employee Identification Number (EIN) is required.
  • For Canada, the Canada Business Number (CBN) is required.
  • Sole Proprietorship may apply without an EIN/CBN, but there will be additional checks to validate that the provided information is accurate.
  • For other country-specific registration, select the relevant option or Other.
Must be one of:EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER
tax_id
string
Required
Max500
example12-3456789
  • For the US, provide the Employee Identification Number (EIN) for the company/organization.
  • For Canada, provide the Canada Business Number (CBN) for the company/organization.
  • For Sole Proprietorship, you may leave this field blank.
  • For country-specific registration types, provide the relevant Tax ID number.
tax_id_issuing_country
string
Required
Max2
exampleUS

Relevant issuing country. Two-letter ISO-2 country code.

isv_reseller
object

ISV/Reseller initiating the registration on behalf of the customer.

Note: This is only required for ISV and resellers.

name
string
Max500
exampleReseller ABC

If you are an ISV/Reseller, enter the name of your business.

contact_email
string
Max500
examplejohn.doe@resellerabc.com

Vonage will only communicate with this email address for ISV/Reseller submissions. Must be a valid email.

estimated_monthly_volume
string
example10,000

Estimated monthly message volume.

Must be one of:101001,00010,000100,000250,000500,000750,0001,000,0005,000,00010,000,000+
requested_numbers
array

TFN number details

number
string(e164)
Min11
Max11
example18001234567

Must 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.

status
string

The verification status of the tfn.

Must be one of:UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKED
rejected_reason
string
exampleDisallowedContent - Gambling

Reason the number is rejected for tfn registration

business_reason
string
Max149
exampleTwo 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.

use_case
object

Describes the use case.

category
string
Required
examplePolitical

Use case category that represents your business industry; choose “Mixed” if marketing and alerts.

Must be one of: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 Alerts
description
string
Required
Max500
exampleThis 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.

campaign_verify_auth_token
string
Max500
examplecv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgR

Note: 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.
campaign_verify_expiry_date
string(date-time)

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.

message_content
object
content
string
Required
Max1000
example[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.

age_gated
boolean

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:

  1. Provide the end user's birth date (MM/DD/YYYY) to receive promotional/alert messages.
  2. 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:

  1. 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.
opt_in
object
workflow
string
Required
exampleOther

Select consent method collected from the message recipient.

Must be one of:Online (website, Mobile app/browser)Text-to-joinPoint of saleOther
workflow_description
string
Max494
examplePaper-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.

images
array
Required
url
string
Required
  • Provide a shared link or publicly accessible link to a screenshot
  • Do not add any additional content, i.e. "here's a list"
keywords
array

Provide one or more opt-in keywords that trigger an auto-response message to the recipient.

confirmation_message
string
Max160
example[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.

help_message
string
Max160
example[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.com

The 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.

additional_information
string
Max350
exampleThis is test additional information.

Provide any additional information.

status
string

The submission status of the registration.

Must be one of:SUBMITTEDDRAFT
creation_date
string(date-time)

The date and time of creation.

last_update_date
string(date-time)

The date and time of last update.

submission_date
string(date-time)

The date and time of submission.

Example Response

Example preview is currently not supported for content type: application/hal+json

Update a registration

Registration can be updated if on of the following conditions is met:

  • Submission status is DRAFT or
  • Submission status is SUBMITTED and all number statuses are UPDATES_REQUIRED
patchhttps://api.nexmo.com/tfn/v1/registrations/:id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

id
string(uuid)
Required
example3fa85f64-5717-4562-b3fc-2c963f66afa6

Request Body
Content Type
application/json

business
object

The content creator, not an ISV or reseller

name
string
Required
Max500
exampleEricsson LM

Parent company or organization full name.

address
object
Required
street
string
Required
Max500
example101 Crawfords Corner Rd

Street number and name.

city
string
Required
Max500
exampleHolmdel

City name

state
string
Required
Max500
exampleCA

State or province. For the United States, use 2-character codes, e.g., ‘CA’ for California.

postal_code
string
Required
Max10
example21012

Zip Code or postal code. For the United States, use a 5-digit ZIP code

country
string
Required
exampleUS

Two-letter country code following the ISO 3166-2 standard

company_website
string
Required
Max500
examplehttps://www.vonage.com

Provide a publicly available website link for the company/organization. Must be a valid URL.

contact
object
Required
first_name
string
Required
Max500
exampleJohn

First name of business contact.

last_name
string
Required
Max500
exampleSmith

Last name of business contact.

email
string
Required
Max500
examplejohn.smith@vonage.com

Email address must match the company, organization or brand (DBA) name if entered.

phone
string(e164)
Required
Max500
example12125551212

Phone number of business contact. Must be a valid phone number in E.164 format without the + prefix.

dba
string
Max500
exampleVonage Holdings Corp

If applicable, the Brand name ‘Doing Business As (DBA)’.

terms_and_conditions_url
string
Max500
examplehttps://www.vonage.com/legal/messaging-service-supplementary-terms/

Provide Terms link for the company/organization. Must be a valid URL.

privacy_policy_url
string
Max500
examplehttps://www.vonage.com/legal/privacy-policy/

Provide a Privacy Policy link for the company/organization. Must be a valid URL.

entity_type
string
Required
examplePRIVATE_PROFIT

Legal classification for the company/organization.

Must be one of:SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENT
tax_id_type
string
Required
DefaultEIN
exampleEIN
  • For the US, a Federal Tax ID or Employee Identification Number (EIN) is required.
  • For Canada, the Canada Business Number (CBN) is required.
  • Sole Proprietorship may apply without an EIN/CBN, but there will be additional checks to validate that the provided information is accurate.
  • For other country-specific registration, select the relevant option or Other.
Must be one of:EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER
tax_id
string
Required
Max500
example12-3456789
  • For the US, provide the Employee Identification Number (EIN) for the company/organization.
  • For Canada, provide the Canada Business Number (CBN) for the company/organization.
  • For Sole Proprietorship, you may leave this field blank.
  • For country-specific registration types, provide the relevant Tax ID number.
tax_id_issuing_country
string
Required
Max2
exampleUS

Relevant issuing country. Two-letter ISO-2 country code.

isv_reseller
object

ISV/Reseller initiating the registration on behalf of the customer.

Note: This is only required for ISV and resellers.

name
string
Max500
exampleReseller ABC

If you are an ISV/Reseller, enter the name of your business.

contact_email
string
Max500
examplejohn.doe@resellerabc.com

Vonage will only communicate with this email address for ISV/Reseller submissions. Must be a valid email.

estimated_monthly_volume
string
example10,000

Estimated monthly message volume.

Must be one of:101001,00010,000100,000250,000500,000750,0001,000,0005,000,00010,000,000+
requested_numbers
array

List all toll-free phone numbers to be registered. Add up to 5 TFNs.

number
string(e164)
Required
Min11
Max11
example18001234567

Must 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.

business_reason
string
Max149
exampleTwo 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.

use_case
object

Describes the use case.

category
string
Required
examplePolitical

Use case category that represents your business industry; choose “Mixed” if marketing and alerts.

Must be one of: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 Alerts
description
string
Required
Max500
exampleThis 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.

campaign_verify_auth_token
string
Max500
examplecv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgR

Note: 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.
message_content
object
content
string
Required
Max1000
example[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.

age_gated
boolean

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:

  1. Provide the end user's birth date (MM/DD/YYYY) to receive promotional/alert messages.
  2. 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:

  1. 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.
opt_in
object
workflow
string
Required
exampleOther

Select consent method collected from the message recipient.

Must be one of:Online (website, Mobile app/browser)Text-to-joinPoint of saleOther
workflow_description
string
Max494
examplePaper-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.

images
array
Required
url
string
Required
  • Provide a shared link or publicly accessible link to a screenshot
  • Do not add any additional content, i.e. "here's a list"
keywords
array

Provide one or more opt-in keywords that trigger an auto-response message to the recipient.

confirmation_message
string
Max160
example[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.

help_message
string
Max160
example[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.com

The 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.

additional_information
string
Max350
exampleThis is test additional information.

Provide any additional information.

status
string

Set to SUBMITTED to submit DRAFT registration. If omitted, the previous status is maintained.

Must be one of:SUBMITTED

Example Request

{
   "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"
}

Responses

Successful response

Get events associated with registration and toll free number

Get events for a registration. Only the account holder can retrieve events for the tfn. Events are returned in descending order with the latest events on top.

gethttps://api.nexmo.com/tfn/v1/registrations/:id/number/:number/events

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

id
string(uuid)
Required
example3fa85f64-5717-4562-b3fc-2c963f66afa6
number
string(e164)
Required
Min11
Max11
example18001234567

Responses
Content Type
application/hal+json

Successful response

_embedded
object
events
array
id
string(uuid)
example3fa85f64-5717-4562-b3fc-2c963f66afa6

Unique identifier of a registration

status
string

The verification status of the tfn.

Must be one of:UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKED
reason
string
exampleThe 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.

created_at
string(date-time)

The date and time of creation.

page_size
integer
example10
_links
object
self
string
examplehttps://example:com/resource?page_size=10&cursor=19284743

Example Response

Example preview is currently not supported for content type: application/hal+json

Numbers

Endpoints allowing to manage TFN numbers.

Available Operations

Get a list of number registrations

gethttps://api.nexmo.com/tfn/v1/numbers

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Query Parameters

cursor
string
example19284743

Cursor for pagination

page_size
integer
example10

Number of results per page

status
string

Filter by number status

Must be one of:UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKED
number
string(e164)
Min11
Max11
example18001234567

Filter by specific toll-free number

registration_id
string(uuid)
example3fa85f64-5717-4562-b3fc-2c963f66afa6

Filter by specific registration ID

business_name
string
Max500
exampleEricsson LM

Fuzzy search by business name

Responses
Content Type
application/json

List of number registrations

_embedded
object
numbers
array
number
string(e164)
Min11
Max11
example18001234567

Must 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.

status
string

The verification status of the tfn.

Must be one of:UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKED
business_name
string
Max500
exampleEricsson LM

Parent company or organization full name.

registration_id
string(uuid)
example3fa85f64-5717-4562-b3fc-2c963f66afa6

Unique identifier of a registration

submission_date
string(date-time)

The date and time of submission.

status_change_date
string(date-time)

Date when the current status tfn was updated

page_size
integer
example10
_links
object
self
string
examplehttps://example:com/resource?page_size=10&cursor=19284743
next
string
examplehttps://example:com/resource?page_size=10&cursor=19284743
prev
string
examplehttps://example:com/resource?page_size=10&cursor=19284743
first
string
examplehttps://example:com/resource?page_size=10

Example Response

{
   "_embedded": {
      "numbers": [
         {
            "number": "18001234567",
            "status": "UPDATES_REQUIRED",
            "business_name": "Ericsson LM",
            "registration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "submission_date": "2019-08-24T14:15:22Z",
            "status_change_date": "2019-08-24T14:15:22Z"
         }
      ]
   },
   "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"
   }
}