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.

OpenAPI-Spezifikation herunterladen

Registrations

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

Create a TFN registration

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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

Headers

Basic <base64>

Anfrage Körper
Inhalt Typ
application/json

business
object
Erforderlich

The content creator, not an ISV or reseller

name
string
Erforderlich
Max500
BeispielEricsson LM

Parent company or organization full name.

address
object
Erforderlich
street
string
Erforderlich
Max500
Beispiel101 Crawfords Corner Rd

Street number and name.

city
string
Erforderlich
Max500
BeispielHolmdel

City name

state
string
Erforderlich
Max500
BeispielCA

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

postal_code
string
Erforderlich
Max10
Beispiel21012

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

country
string
Erforderlich
BeispielUS

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

company_website
string
Erforderlich
Max500
Beispielhttps://www.vonage.com

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

contact
object
Erforderlich
first_name
string
Erforderlich
Max500
BeispielJohn

First name of business contact.

last_name
string
Erforderlich
Max500
BeispielSmith

Last name of business contact.

email
string
Erforderlich
Max500
Beispieljohn.smith@vonage.com

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

phone
string(e164)
Erforderlich
Max500
Beispiel12125551212

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

dba
string
Max500
BeispielVonage Holdings Corp

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

terms_and_conditions_url
string
Max500
Beispielhttps://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
Beispielhttps://www.vonage.com/legal/privacy-policy/

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

entity_type
string
Erforderlich
BeispielPRIVATE_PROFIT

Legal classification for the company/organization.

Muss eines der folgenden sein:SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENT
tax_id_type
string
Erforderlich
StandardEIN
BeispielEIN
  • 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.
Muss eines der folgenden sein:EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER
tax_id
string
Erforderlich
Max500
Beispiel12-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
Erforderlich
Max2
BeispielUS

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

estimated_monthly_volume
string
Erforderlich
Beispiel10,000

Estimated monthly message volume.

Muss eines der folgenden sein: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
BeispielReseller ABC

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

contact_email
string
Max500
Beispieljohn.doe@resellerabc.com

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

requested_numbers
array
Erforderlich

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

number
string(e164)
Erforderlich
Min11
Max11
Beispiel18001234567

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
BeispielTwo 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
Erforderlich

Describes the use case.

category
string
Erforderlich
BeispielPolitical

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

Muss eines der folgenden sein: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
Erforderlich
Max500
BeispielThis 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
Beispielcv|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
Erforderlich
content
string
Erforderlich
Max1000
Beispiel[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
Erforderlich
workflow
string
Erforderlich
BeispielOther

Select consent method collected from the message recipient.

Muss eines der folgenden sein:Online (website, Mobile app/browser)Text-to-joinPoint of saleOther
workflow_description
string
Max494
BeispielPaper-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
Erforderlich
url
string
Erforderlich
  • 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
Beispiel[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
Beispiel[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
Erforderlich
Max350
BeispielThis is test additional information.

Provide any additional information.

status
string

The submission status of the registration.

Muss eines der folgenden sein:SUBMITTEDDRAFT

Beispiel Anfrage

Antworten
Inhalt Typ
application/hal+json

Successful response

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

Unique identifier of a registration

Beispiel Antwort

Die Beispielvorschau wird derzeit für den Inhaltstyp nicht unterstützt: application/hal+json

Get the registration details by registration ID

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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

Headers

Basic <base64>

Pfad Parameter

id
string(uuid)
Erforderlich
Beispiel3fa85f64-5717-4562-b3fc-2c963f66afa6

Antworten
Inhalt Typ
application/hal+json

Successful response

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

Unique identifier of a registration

business
object

The content creator, not an ISV or reseller

name
string
Erforderlich
Max500
BeispielEricsson LM

Parent company or organization full name.

address
object
Erforderlich
street
string
Erforderlich
Max500
Beispiel101 Crawfords Corner Rd

Street number and name.

city
string
Erforderlich
Max500
BeispielHolmdel

City name

state
string
Erforderlich
Max500
BeispielCA

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

postal_code
string
Erforderlich
Max10
Beispiel21012

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

country
string
Erforderlich
BeispielUS

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

company_website
string
Erforderlich
Max500
Beispielhttps://www.vonage.com

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

contact
object
Erforderlich
first_name
string
Erforderlich
Max500
BeispielJohn

First name of business contact.

last_name
string
Erforderlich
Max500
BeispielSmith

Last name of business contact.

email
string
Erforderlich
Max500
Beispieljohn.smith@vonage.com

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

phone
string(e164)
Erforderlich
Max500
Beispiel12125551212

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

dba
string
Max500
BeispielVonage Holdings Corp

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

terms_and_conditions_url
string
Max500
Beispielhttps://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
Beispielhttps://www.vonage.com/legal/privacy-policy/

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

entity_type
string
Erforderlich
BeispielPRIVATE_PROFIT

Legal classification for the company/organization.

Muss eines der folgenden sein:SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENT
tax_id_type
string
Erforderlich
StandardEIN
BeispielEIN
  • 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.
Muss eines der folgenden sein:EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER
tax_id
string
Erforderlich
Max500
Beispiel12-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
Erforderlich
Max2
BeispielUS

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
BeispielReseller ABC

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

contact_email
string
Max500
Beispieljohn.doe@resellerabc.com

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

estimated_monthly_volume
string
Beispiel10,000

Estimated monthly message volume.

Muss eines der folgenden sein:101001,00010,000100,000250,000500,000750,0001,000,0005,000,00010,000,000+
requested_numbers
array

TFN number details

number
string(e164)
Min11
Max11
Beispiel18001234567

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.

Muss eines der folgenden sein:UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKED
rejected_reason
string
BeispielDisallowedContent - Gambling

Reason the number is rejected for tfn registration

business_reason
string
Max149
BeispielTwo 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
Erforderlich
BeispielPolitical

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

Muss eines der folgenden sein: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
Erforderlich
Max500
BeispielThis 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
Beispielcv|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
Erforderlich
Max1000
Beispiel[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
Erforderlich
BeispielOther

Select consent method collected from the message recipient.

Muss eines der folgenden sein:Online (website, Mobile app/browser)Text-to-joinPoint of saleOther
workflow_description
string
Max494
BeispielPaper-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
Erforderlich
url
string
Erforderlich
  • 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
Beispiel[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
Beispiel[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
BeispielThis is test additional information.

Provide any additional information.

status
string

The submission status of the registration.

Muss eines der folgenden sein: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.

Beispiel Antwort

Die Beispielvorschau wird derzeit für den Inhaltstyp nicht unterstützt: 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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

Headers

Basic <base64>

Pfad Parameter

id
string(uuid)
Erforderlich
Beispiel3fa85f64-5717-4562-b3fc-2c963f66afa6

Anfrage Körper
Inhalt Typ
application/json

business
object

The content creator, not an ISV or reseller

name
string
Erforderlich
Max500
BeispielEricsson LM

Parent company or organization full name.

address
object
Erforderlich
street
string
Erforderlich
Max500
Beispiel101 Crawfords Corner Rd

Street number and name.

city
string
Erforderlich
Max500
BeispielHolmdel

City name

state
string
Erforderlich
Max500
BeispielCA

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

postal_code
string
Erforderlich
Max10
Beispiel21012

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

country
string
Erforderlich
BeispielUS

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

company_website
string
Erforderlich
Max500
Beispielhttps://www.vonage.com

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

contact
object
Erforderlich
first_name
string
Erforderlich
Max500
BeispielJohn

First name of business contact.

last_name
string
Erforderlich
Max500
BeispielSmith

Last name of business contact.

email
string
Erforderlich
Max500
Beispieljohn.smith@vonage.com

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

phone
string(e164)
Erforderlich
Max500
Beispiel12125551212

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

dba
string
Max500
BeispielVonage Holdings Corp

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

terms_and_conditions_url
string
Max500
Beispielhttps://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
Beispielhttps://www.vonage.com/legal/privacy-policy/

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

entity_type
string
Erforderlich
BeispielPRIVATE_PROFIT

Legal classification for the company/organization.

Muss eines der folgenden sein:SOLE_PROPRIETORPRIVATE_PROFITPUBLIC_PROFITNON_PROFITGOVERNMENT
tax_id_type
string
Erforderlich
StandardEIN
BeispielEIN
  • 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.
Muss eines der folgenden sein:EINCBNCRNNEQPROVINCIAL_NUMBERVATACNABNBRNSIRENSIRETNZBNUST-IDNRCIFNIFCNPJUIDOTHER
tax_id
string
Erforderlich
Max500
Beispiel12-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
Erforderlich
Max2
BeispielUS

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
BeispielReseller ABC

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

contact_email
string
Max500
Beispieljohn.doe@resellerabc.com

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

estimated_monthly_volume
string
Beispiel10,000

Estimated monthly message volume.

Muss eines der folgenden sein: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)
Erforderlich
Min11
Max11
Beispiel18001234567

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
BeispielTwo 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
Erforderlich
BeispielPolitical

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

Muss eines der folgenden sein: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
Erforderlich
Max500
BeispielThis 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
Beispielcv|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
Erforderlich
Max1000
Beispiel[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
Erforderlich
BeispielOther

Select consent method collected from the message recipient.

Muss eines der folgenden sein:Online (website, Mobile app/browser)Text-to-joinPoint of saleOther
workflow_description
string
Max494
BeispielPaper-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
Erforderlich
url
string
Erforderlich
  • 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
Beispiel[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
Beispiel[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
BeispielThis is test additional information.

Provide any additional information.

status
string

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

Muss eines der folgenden sein:SUBMITTED

Beispiel Anfrage

Antworten

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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

Headers

Basic <base64>

Pfad Parameter

id
string(uuid)
Erforderlich
Beispiel3fa85f64-5717-4562-b3fc-2c963f66afa6
number
string(e164)
Erforderlich
Min11
Max11
Beispiel18001234567

Antworten
Inhalt Typ
application/hal+json

Successful response

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

Unique identifier of a registration

status
string

The verification status of the tfn.

Muss eines der folgenden sein:UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKED
reason
string
BeispielThe 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
Beispiel10
_links
object
self
string
Beispielhttps://example:com/resource?page_size=10&cursor=19284743

Beispiel Antwort

Die Beispielvorschau wird derzeit für den Inhaltstyp nicht unterstützt: application/hal+json

Numbers

Endpoints allowing to manage TFN numbers.

Verfügbare Operationen

Get a list of number registrations

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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

Headers

Basic <base64>

Abfrage Parameter

cursor
string
Beispiel19284743

Cursor for pagination

page_size
integer
Beispiel10

Number of results per page

status
string

Filter by number status

Muss eines der folgenden sein:UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKED
number
string(e164)
Min11
Max11
Beispiel18001234567

Filter by specific toll-free number

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

Filter by specific registration ID

business_name
string
Max500
BeispielEricsson LM

Fuzzy search by business name

Antworten
Inhalt Typ
application/json

List of number registrations

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

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.

Muss eines der folgenden sein:UPDATES_REQUIREDPENDING_REVIEWCARRIERS_REVIEWREGISTEREDREJECTEDDRAFTBLOCKED
business_name
string
Max500
BeispielEricsson LM

Parent company or organization full name.

registration_id
string(uuid)
Beispiel3fa85f64-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
Beispiel10
_links
object
self
string
Beispielhttps://example:com/resource?page_size=10&cursor=19284743
next
string
Beispielhttps://example:com/resource?page_size=10&cursor=19284743
prev
string
Beispielhttps://example:com/resource?page_size=10&cursor=19284743
first
string
Beispielhttps://example:com/resource?page_size=10

Beispiel Antwort