No-code docs
Resources

Toll-Free Numbers Verification API

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.

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

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.

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

List all available numbers in stock at organization level.

GET/organizations/{organizationId}/numbers-stock-items
Authorization
Path parameters
organizationId*OrganizationId (string (uuid))

The ID for the organization.

Example: "d0b85ccc-b63a-4e81-b698-c359d77d250e"
Query parameters
Response

OK

Body
results*array of NumberStockItem (object)
nextPageTokenstring

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.

Request
const response = await fetch('/organizations/{organizationId}/numbers-stock-items', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();
Response
{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "countryCode": "US",
      "type": "local",
      "numberString": "+19283764510",
      "capabilities": {
        "voice": {
          "inbound": false,
          "outbound": false
        },
        "sms": {
          "inbound": false,
          "outbound": false
        },
        "mms": {
          "inbound": false,
          "outbound": false
        }
      },
      "monthlyPrice": {
        "currencyCode": "EUR",
        "amount": 3500000,
        "exponent": -6
      },
      "backOrderRequired": false,
      "backOrderStockId": "text"
    }
  ],
  "nextPageToken": "text"
}

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.

Buy Long Code Numbers

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.

POST/workspaces/{workspaceId}/numbers-long-code
Authorization
Path parameters
workspaceId*WorkspaceId (string (uuid))

The ID for the workspace.

Example: "d386a801-ee8d-4aba-a7e4-78671bd3b11e"
Body
numberStockItemIds*array of string (uuid)

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.

Response

Created

Body
results*array of WorkspaceLongCodeNumber (object)
Request
const response = await fetch('/workspaces/{workspaceId}/numbers-long-code', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "numberStockItemIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }),
});
const data = await response.json();
Response
{
  "results": [
    {
      "id": "41e3cf43-4386-464a-a1ee-e6ef6fd6883d",
      "endpointId": "41e3cf43-4386-464a-a1ee-e6ef6fd6883d",
      "numberString": "+14155552671",
      "countryCode": "US",
      "type": "local",
      "capabilities": {
        "voice": {
          "inbound": false,
          "outbound": false
        },
        "sms": {
          "inbound": false,
          "outbound": false
        },
        "mms": {
          "inbound": false,
          "outbound": false
        }
      },
      "createdAt": "2025-01-17T11:56:30.254Z",
      "updatedAt": "2025-01-17T11:56:30.254Z",
      "order": {
        "countryCode": "US",
        "type": "local",
        "capabilities": [
          "voice"
        ],
        "prefix": "text",
        "status": "draft",
        "createdAt": "2025-01-17T11:56:30.254Z",
        "updatedAt": "2025-01-17T11:56:30.254Z"
      },
      "deprovisionAt": "2025-01-17T11:56:30.254Z",
      "endpoint": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "long-code-number",
        "instanceId": "1551f382-6870-4480-8f9b-f5ab34936288",
        "name": "+14155552671",
        "capabilities": [
          {
            "name": "sms",
            "inbound": {
              "status": "active",
              "issues": [
                "subscription-is-not-active"
              ]
            },
            "outbound": {
              "status": "active",
              "destinationStatuses": {
                "active": 0,
                "inactive": 0,
                "available": 0,
                "unavailable": 0
              },
              "supportsDestinations": false,
              "issues": [
                "subscription-is-not-active"
              ]
            }
          }
        ],
        "dependencies": [
          {
            "type": "connector",
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text",
            "capabilities": [
              "voice"
            ]
          }
        ],
        "issues": [
          "subscription-is-not-active"
        ],
        "provisioningStatus": "provisioned",
        "createdAt": "2025-01-17T11:56:30.254Z",
        "updatedAt": "2025-01-17T11:56:30.254Z"
      }
    }
  ]
}

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

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

  • Check this article for tips on how to write an effective useCaseSummary

  • Check this article on how to write an effective optInWorkflowDescription

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

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.

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.

Create TfnVerification

POST/workspaces/{workspaceId}/tfn-verifications
Authorization
Path parameters
workspaceId*WorkspaceId (string (uuid))

The ID for the workspace.

Example: "d386a801-ee8d-4aba-a7e4-78671bd3b11e"
Query parameters
Body
phoneNumbersarray of string
businessName*string
businessAddr1*string
businessAddr2string
businessZip*string
businessCity*string
businessState*string
businessCountry*string
businessContactFirstName*string
businessContactLastName*string
businessContactEmail*string
businessContactPhone*string
corporateWebsite*string
messageVolume*enum
101001000100001000002500005000007500001000000500000010000000+
useCase*string
useCaseSummary*string
productionMessageContent*string
optInWorkflowDescription*string
optInWorkflowImageUrLs*array of string
additionalInformationstring
isvResellerstring
phoneNumbers*array of string (uuid)
testModeboolean
brandKycFormEntryIdstring (uuid)
Response

Validation Response

Body
brandKycFromIdstring (uuid)
fieldsTfnVerificationFields (object)
errorValidationError (object)
Request
const response = await fetch('/workspaces/{workspaceId}/tfn-verifications', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "businessName": "text",
      "businessAddr1": "text",
      "businessZip": "text",
      "businessCity": "text",
      "businessState": "text",
      "businessCountry": "text",
      "businessContactFirstName": "text",
      "businessContactLastName": "text",
      "businessContactEmail": "text",
      "businessContactPhone": "text",
      "corporateWebsite": "text",
      "messageVolume": "10",
      "useCase": "text",
      "useCaseSummary": "text",
      "productionMessageContent": "text",
      "optInWorkflowDescription": "text",
      "optInWorkflowImageUrLs": [
        "text"
      ],
      "phoneNumbers": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }),
});
const data = await response.json();
Response
{
  "brandKycFromId": "123e4567-e89b-12d3-a456-426614174000",
  "fields": {
    "phoneNumbers": [
      "text"
    ],
    "businessName": "text",
    "businessAddr1": "text",
    "businessAddr2": "text",
    "businessZip": "text",
    "businessCity": "text",
    "businessState": "text",
    "businessCountry": "text",
    "businessContactFirstName": "text",
    "businessContactLastName": "text",
    "businessContactEmail": "text",
    "businessContactPhone": "text",
    "corporateWebsite": "text",
    "messageVolume": "10",
    "useCase": "text",
    "useCaseSummary": "text",
    "productionMessageContent": "text",
    "optInWorkflowDescription": "text",
    "optInWorkflowImageUrLs": [
      "text"
    ],
    "additionalInformation": "text",
    "isvReseller": "text"
  },
  "error": {
    "code": "text",
    "message": "service."
  }
}
{
  "businessName": "string", 
  "businessAddr1": "string",
  "businessAddr2": "string",
  "businessZip": "string",
  "businessCity": "string",
  "businessState": "string",
  "businessCountry": "string",
  "businessContactFirstName": "string",
  "businessContactLastName": "string",
  "businessContactEmail": "string",
  "businessContactPhone": "string",
  "corporateWebsite": "string",
  "messageVolume": "10",
  "useCase": "string",
  "useCaseSummary": "string",
  "productionMessageContent": "string",
  "optInWorkflowDescription": "string",
  "optInWorkflowImageURLs": [
    "string"
  ],
  "additionalInformation": "string",
  "isvReseller": "string",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "phoneNumbers": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6" 
  ],
  "testMode": true 
}

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.

UseCase categories must only be of these types

[
    "2FA",
    "App Notifications",
    "Appointments",
    "Auctions",
    "Auto Repair Services",
    "Bank Transfers",
    "Billing",
    "Booking Confirmations",
    "Business Updates",
    "Career Training",
    "Chatbot",
    "Contests",
    "Courier Services & Deliveries",
    "Emergency Alerts",
    "Events & Planning",
    "Financial Services",
    "Fraud Alerts",
    "Fundraising",
    "General Marketing",
    "General School Updates",
    "HR / Staffing",
    "Healthcare Services",
    "Housing Community Updates",
    "Insurance Services",
    "Job Dispatch",
    "Mixed",
    "Motivational Reminders",
    "Notary Notifications",
    "Order Notifications",
    "Public Works",
    "Real Estate Services",
    "Religious Services",
    "Repair and Diagnostics Alerts",
    "Rewards Program",
    "Surveys",
    "System Alerts",
    "Voting Reminders",
    "Webinar Reminders",
    "Workshop Alerts",
    "Zipwhip Testing"
]

Message Volume can only be of this type:

10; 100; 1,000; 10,000; 100,000; 250,000; 500,000; 750,000; 1,000,000; 5,000,000; 10,000,000+

Fields below are not required for the submission:

businessAddr2, additionalInformation, isvReseller

Responses

201: Created

{
  "businessName": "string",
  "businessAddr1": "string",
  "businessAddr2": "string",
  "businessZip": "string",
  "businessCity": "string",
  "businessState": "string",
  "businessCountry": "string",
  "businessContactFirstName": "string",
  "businessContactLastName": "string",
  "businessContactEmail": "string",
  "businessContactPhone": "string",
  "corporateWebsite": "string",
  "messageVolume": "10",
  "useCase": "string",
  "useCaseSummary": "string",
  "productionMessageContent": "string",
  "optInWorkflowDescription": "string",
  "optInWorkflowImageURLs": [
    "string"
  ],
  "additionalInformation": "string",
  "isvReseller": "string",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "phoneNumbers": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "testMode": true
}

422: Unprocessable Entity (Invalid verification submission)

{
  "code": "string",
  "message": "string",
  "details": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

400: Bad request

{
    "code": "string",
    "message": "string"
}

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.

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.

Get Workspace TfnVerification

GET/workspaces/{workspaceId}/tfn-verifications/{verificationId}
Authorization
Path parameters
workspaceId*WorkspaceId (string (uuid))

The ID for the workspace.

Example: "d386a801-ee8d-4aba-a7e4-78671bd3b11e"
verificationId*string
Response

OK

Body
idstring (uuid)
organizationIdstring (uuid)
workspaceIdstring (uuid)
verificationRequestIdstring
longCodeNumberIdsarray of string (uuid)
verificationRequestDataobject
statusenum
submittedin-progressverifiedrejected
statusMessageStatusMessage (object)
testModeboolean
createdAtstring (date-time)
updatedAtstring (date-time)
Request
const response = await fetch('/workspaces/{workspaceId}/tfn-verifications/{verificationId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "verificationRequestId": "text",
  "longCodeNumberIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "verificationRequestData": {
    "phoneNumbers": [
      "text"
    ],
    "businessName": "text",
    "businessAddr1": "text",
    "businessAddr2": "text",
    "businessZip": "text",
    "businessCity": "text",
    "businessState": "text",
    "businessCountry": "text",
    "businessContactFirstName": "text",
    "businessContactLastName": "text",
    "businessContactEmail": "text",
    "businessContactPhone": "text",
    "corporateWebsite": "text",
    "messageVolume": "10",
    "useCase": "text",
    "useCaseSummary": "text",
    "productionMessageContent": "text",
    "optInWorkflowDescription": "text",
    "optInWorkflowImageUrLs": [
      "text"
    ],
    "additionalInformation": "text",
    "isvReseller": "text"
  },
  "status": "submitted",
  "statusMessage": {
    "statusCode": "text",
    "declineReasonDescription": "text",
    "resubmitAllowed": false
  },
  "testMode": false,
  "createdAt": "2025-01-17T11:56:30.254Z",
  "updatedAt": "2025-01-17T11:56:30.254Z"
}

Responses

200 OK:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "verificationRequestId": "string",
  "phoneNumbers": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "verificationRequestData": {
    "businessName": "string",
    "businessAddr1": "string",
    "businessAddr2": "string",
    "businessZip": "string",
    "businessCity": "string",
    "businessState": "string",
    "businessCountry": "string",
    "businessContactFirstName": "string",
    "businessContactLastName": "string",
    "businessContactEmail": "string",
    "businessContactPhone": "string",
    "corporateWebsite": "string",
    "messageVolume": "10",
    "useCase": "string",
    "useCaseSummary": "string",
    "productionMessageContent": "string",
    "optInWorkflowDescription": "string",
    "optInWorkflowImageURLs": [
      "string"
    ],
    "additionalInformation": "string",
    "isvReseller": "string"
  },
  "status": "submitted",
  "statusMessage": {
    "StatusCode": "string",
    "DeclineReasonDescription": "string",
    "ResubmitAllowed": "string",
    "Message": "string"
  },
  "testMode": true,
  "createdAt": "2023-10-12T13:13:15.161Z",
  "updatedAt": "2023-10-12T13:13:15.161Z"
}

404 Not Found:

{
  "code": "string",
  "message": "string"
}

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.

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

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

PUT/workspaces/{workspaceId}/tfn-verifications/{verificationId}
Authorization
Path parameters
workspaceId*WorkspaceId (string (uuid))

The ID for the workspace.

Example: "d386a801-ee8d-4aba-a7e4-78671bd3b11e"
verificationId*string
Body
phoneNumbersarray of string
businessName*string
businessAddr1*string
businessAddr2string
businessZip*string
businessCity*string
businessState*string
businessCountry*string
businessContactFirstName*string
businessContactLastName*string
businessContactEmail*string
businessContactPhone*string
corporateWebsite*string
messageVolume*enum
101001000100001000002500005000007500001000000500000010000000+
useCase*string
useCaseSummary*string
productionMessageContent*string
optInWorkflowDescription*string
optInWorkflowImageUrLs*array of string
additionalInformationstring
isvResellerstring
Response

OK

Body
idstring (uuid)
organizationIdstring (uuid)
workspaceIdstring (uuid)
verificationRequestIdstring
longCodeNumberIdsarray of string (uuid)
verificationRequestDataobject
statusenum
submittedin-progressverifiedrejected
statusMessageStatusMessage (object)
testModeboolean
createdAtstring (date-time)
updatedAtstring (date-time)
Request
const response = await fetch('/workspaces/{workspaceId}/tfn-verifications/{verificationId}', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "businessName": "text",
      "businessAddr1": "text",
      "businessZip": "text",
      "businessCity": "text",
      "businessState": "text",
      "businessCountry": "text",
      "businessContactFirstName": "text",
      "businessContactLastName": "text",
      "businessContactEmail": "text",
      "businessContactPhone": "text",
      "corporateWebsite": "text",
      "messageVolume": "10",
      "useCase": "text",
      "useCaseSummary": "text",
      "productionMessageContent": "text",
      "optInWorkflowDescription": "text",
      "optInWorkflowImageUrLs": [
        "text"
      ]
    }),
});
const data = await response.json();
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "verificationRequestId": "text",
  "longCodeNumberIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "verificationRequestData": {
    "phoneNumbers": [
      "text"
    ],
    "businessName": "text",
    "businessAddr1": "text",
    "businessAddr2": "text",
    "businessZip": "text",
    "businessCity": "text",
    "businessState": "text",
    "businessCountry": "text",
    "businessContactFirstName": "text",
    "businessContactLastName": "text",