search
No-code docs

Toll-Free Numbers Verification API

hashtag
Overview

A toll-free number can be used to send messages in US & Canada once it passes an additional verification process. Users who don’t verify their toll-free numbers will be blocked from sending messages as of November 8, 2023.

A verified toll-free number ensures that the business owning the number is identified, and that the message's content has been reviewed and does not oppose the Disallowed Content Policy. This process ensures better deliverability and less filtration.

To set up a new channel to send SMS messages using a toll-free number the following steps are required.

hashtag
API Access

The following API requests can only be made using a valid access key, and attached to an access role, with an access policy that at least specifies the permissions to the resources outlined in each section below. Learn more about API accessarrow-up-right.

hashtag
Find an available number

If you do not already have a US or Canadian toll-free number available in your workspace you can find one to purchase.

circle-info

use the search parameter types=toll-free to only search for Toll Free Numbers

hashtag
List all available numbers in stock.

get
Authorizations
HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters
organizationIdstring · uuidRequired

The ID for the organization.

Example: d0b85ccc-b63a-4e81-b698-c359d77d250e
Query parameters
limitinteger · min: 1 · max: 99Optional

Limits the number of results to return per page. The default value is 10 and maximum is 99. If the nextPageToken is defined on response, you can use it to get remaining numbers. To know more, refer to the pagination section.

Default: 10
pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list. Use it to query remaining results. If not provided, the first page is returned. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.

countryCodesstring · iso3166-1[]Optional

A 2-digit ISO 3166-1 country code array.

Example: ["US","NL"]
prefixstring · min: 1 · max: 250Optional

Used to filter numbers by area code. Accepts either bare area code digits (e.g. 205 for Alabama) or a full E.164 prefix (e.g. +1205). Partial prefixes are supported for autocomplete use cases (e.g. +120 matches all numbers in area codes 202, 203, 205, 206, 207, 208, 209). Must be used together with the countryCodes filter.

Example: +1212
testingbooleanOptional
Responses
chevron-right
200

OK

application/json
nextPageTokenstringOptional

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display. To know more, refer to the pagination section.

get
/organizations/{organizationId}/numbers-stock-items

hashtag
Purchase a number

Once you have found an available number you can purchase this by providing the numberStockItemIds matching the id your previous call returned

A successful request to this endpoint will start a recurring monthly subscription based on the monthly cost of the number.

hashtag
Buy Long Code Numbers

post

Assigns Long Code Numbers to the current workspace, charging the wallet for their subscription price. When creating LCNs as a User, all specified Number Stock Items should be reserved.

Authorizations
HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
Body
numberStockItemIdsstring · uuid[] · max: 25Required

The unique identifiers of the numbers you want to buy. You can buy up to 25 numbers at a time. This operation will incur wallet charges for the numbers. Before buying the number, you must reserve it.

Responses
post
/workspaces/{workspaceId}/numbers-long-code

hashtag
Submit a verification application for a toll-free number(s)

triangle-exclamation

To reduce the likelihood of rejection, ensure you are familiar with TFN registration examples and best practices. Specifically

Most TFN rejections are caused by unclear or incomplete useCaseSummary and/or optInWorkflowDescription

circle-info

A-Sync : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result .

Before you can use a toll-free number to send SMS messages, you must submit a toll-free number verification request and wait for it to be approved.

circle-info

You can submit one toll-free number per verification request.

You are not allowed to submit the same number twice, unless the previous submission was resolved with status Rejected or Verified.

hashtag
Create TfnVerification

post
Authorizations
HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
Query parameters
validatebooleanOptional

When set, only validates the request payload without mutating any data.

Body
phoneNumbersstring · uuid[]Required
businessNamestring · max: 500Required
businessRegistrationNumberstring · max: 100Optional

Optional business registration number (TaxID). Used for toll-free verification.

businessRegistrationIssuingCountrystring · enumOptional

Country that issued the business registration (ISO 3166-1 alpha-2 code).

Possible values:
businessRegistrationTypestring · enumOptional

Type of business registration:

  • EIN: Employer Identification Number (US)
  • CBN: Canada Business Number (CA)
  • NEQ: Quebec Enterprise Number (CA)
  • PROVINCIAL_NUMBER: Provincial Business Number (CA)
  • CRN: Company Registration Number (GB, HK)
  • VAT: Value-added Tax Identification Number (GB, IE, BR, NL)
  • ACN: Australian Company Number (AU)
  • ABN: Australian Business Number (AU)
  • BRN: Business Registration Number (HK)
  • SIREN: INSEE identification number (FR)
  • SIRET: Establishment identification number (FR)
  • NZBN: New Zealand Business Number (NZ)
  • UST_IDNR: Umsatzsteuer-Identifikationsnummer (DE)
  • CIF: Código de Identificación Fiscal (ES)
  • NIF: Número de Identificación Fiscal (ES)
  • CNPJ: Cadastro Nacional Da Pessoa Jurídica (BR)
  • UID: Unternehmens-Identifikationsnummer (CH)
  • OTHER: Other registration types (covers additional countries including SE)
Possible values:
entityTypestring · enumOptional

Type of business entity. Required if businessRegistrationNumber is provided.

Possible values:
businessAddr1string · max: 500Required
businessAddr2string · max: 500Optional
businessZipstring · max: 500Required
businessCitystring · max: 500Required
businessStatestring · max: 500Required
businessCountrystring · max: 500Required
businessContactFirstNamestring · max: 500Required
businessContactLastNamestring · max: 500Required
businessContactEmailstring · max: 500Required
businessContactPhonestring · max: 500Required
corporateWebsitestring · max: 500Required
messageVolumestring · enumRequiredPossible values:
useCasestring · max: 500Required
useCaseSummarystring · max: 500Required
productionMessageContentstring · max: 1000Required
optInWorkflowDescriptionstring · max: 500Required
optInWorkflowImageUrLsstring[]Required
additionalInformationstring · max: 500Optional
isvResellerstring · max: 500Optional
testModebooleanOptional
brandKycFormEntryIdstring · uuidOptional
Responses
chevron-right
200

Validation Response

application/json
brandKycFromIdstring · uuidOptional
post
/workspaces/{workspaceId}/tfn-verifications

To make this call, you must provide following parameters:

Parameter
Description

businessName

The name of the Business using Toll Free Number.

businessAddr1

The address of the Business using Toll Free Number.

businessAddr2 (optional field)

The address of the Business using Toll Free Number.

businessCity

The city of the Business using Toll Free Number.

businessState

The state of the Business using Toll Free Number.

businessZip

The zip/postal code of the Business using Toll Free Number.

businessCountry

Country of the Business using Toll Free Number.

corporateWebsite

The website of the Business using Toll Free Number.

businessContactFirstName

Business contact first name.

businessContactLastName

Business contact last name.

businessContactEmail

Business contact email address.

businessContactPhone

Business contact phone number.

messageVolume

Estimate monthly volume of messages from the Toll Free Number. See more details below.

phoneNumbers

IDs of Toll-Free numbers.

useCase

The Category of the use case. See below types of UseCases

useCaseSummary

Please provide a general idea of the use case and customer.

productionMessageContent

Example of message content.

optInWorkflowDescription

Description of the opt in workflow.

optInWorkflowImageURLs

Images showing the opt in workflow.

additionalInformation (optional field)

Any additional information.

isvReseller (optional field)

ISV Name.

hashtag
UseCase categories must only be of these types

Message Volume can only be of this type:

Fields below are not required for the submission:

hashtag
Responses

201: Created

422: Unprocessable Entity (Invalid verification submission)

400: Bad request

hashtag
Fetch status of a toll-free number verification

Once you submit your verification request, you have to wait for the submission to be reviewed. You will be informed about the status of your submission in the portal, but you can also use the API to fetch your verification request status.

hashtag
Statuses

Statuses

Submitted

Verification is submitted and waiting to be reviewed

InProgress

Verification is being reviewed by authority. Additional information may be requested. In case of API integration please inspect the `statusMessage` object for more information.

Verified

Verification submission has been approved, and the number is ready to be used.

Rejected

Verification submission has been rejected.

hashtag
Get Workspace TfnVerification

get
Authorizations
HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
verificationIdstringRequired
Responses
chevron-right
200

OK

application/json
idstring · uuidOptional
organizationIdstring · uuidOptional
workspaceIdstring · uuidOptional
verificationRequestIdstringOptional
longCodeNumberIdsstring · uuid[]Optional
statusstring · enumOptionalPossible values:
testModebooleanOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
get
/workspaces/{workspaceId}/tfn-verifications/{verificationId}

hashtag
Responses

200 OK:

404 Not Found:

hashtag
Update toll-free number verification submission

You can update verification submission with new information in two cases:

  1. Authority has requested to add additional information. Your input is required.

circle-info

Deadline for resubmission is 7 days from the moment of receiving notification from the verification authority.

  1. Provide more accurate verification information without request of an authority.

hashtag
Update Workspace TfnVerification submission, and submit updates to 3rd party TfnVerification API

put
Authorizations
HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
verificationIdstringRequired
Body
phoneNumbersstring[]Optional
businessNamestring · max: 500Required
businessRegistrationNumberstring · max: 100Optional

Optional business registration number (TaxID). Used for toll-free verification.

businessRegistrationIssuingCountrystring · enumOptional

Country that issued the business registration (ISO 3166-1 alpha-2 code).

Possible values:
businessRegistrationTypestring · enumOptional

Type of business registration:

  • EIN: Employer Identification Number (US)
  • CBN: Canada Business Number (CA)
  • NEQ: Quebec Enterprise Number (CA)
  • PROVINCIAL_NUMBER: Provincial Business Number (CA)
  • CRN: Company Registration Number (GB, HK)
  • VAT: Value-added Tax Identification Number (GB, IE, BR, NL)
  • ACN: Australian Company Number (AU)
  • ABN: Australian Business Number (AU)
  • BRN: Business Registration Number (HK)
  • SIREN: INSEE identification number (FR)
  • SIRET: Establishment identification number (FR)
  • NZBN: New Zealand Business Number (NZ)
  • UST_IDNR: Umsatzsteuer-Identifikationsnummer (DE)
  • CIF: Código de Identificación Fiscal (ES)
  • NIF: Número de Identificación Fiscal (ES)
  • CNPJ: Cadastro Nacional Da Pessoa Jurídica (BR)
  • UID: Unternehmens-Identifikationsnummer (CH)
  • OTHER: Other registration types (covers additional countries including SE)
Possible values:
entityTypestring · enumOptional

Type of business entity. Required if businessRegistrationNumber is provided.

Possible values:
businessAddr1string · max: 500Required
businessAddr2string · max: 500Optional
businessZipstring · max: 500Required
businessCitystring · max: 500Required
businessStatestring · max: 500Required
businessCountrystring · max: 500Required
businessContactFirstNamestring · max: 500Required
businessContactLastNamestring · max: 500Required
businessContactEmailstring · max: 500Required
businessContactPhonestring · max: 500Required
corporateWebsitestring · max: 500Required
messageVolumestring · enumRequiredPossible values:
useCasestring · max: 500Required
useCaseSummarystring · max: 500Required
productionMessageContentstring · max: 1000Required
optInWorkflowDescriptionstring · max: 500Required
optInWorkflowImageUrLsstring[]Required
additionalInformationstring · max: 500Optional
isvResellerstring · max: 500Optional
Responses
chevron-right
200

OK

application/json
idstring · uuidOptional
organizationIdstring · uuidOptional
workspaceIdstring · uuidOptional
verificationRequestIdstringOptional
longCodeNumberIdsstring · uuid[]Optional
statusstring · enumOptionalPossible values:
testModebooleanOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
put
/workspaces/{workspaceId}/tfn-verifications/{verificationId}

hashtag
Responses

200 OK:

404 Not Found:

422: Unprocessable Entity

Last updated

Was this helpful?