DocumentazioneEngagement Platform API
Sign inGet started
Guides
API

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
GET
/organizations/{organizationId}/numbers-stock-items
List all available numbers in stock.
Parametri di query
limit
integer
Limits the number of results to return.
pageToken
string
The cursor that keeps track of the current position in the results.
countryCodes
array
types
array
The number type depending on its purpose. Local for regional use, national for countrywide use, mobile for mobile networks, or toll-free for caller-free charging.
features
array
The number capabilities, which can be voice, SMS, and MMS for inbound, outbound, or two-way communication, plus WhatsApp.
prefix
string
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.
testing
boolean
Payload della risposta
results
array of object
obbligatorio
Mostra attributi secondari
results.id
string
obbligatorio
The unique identifier of the stock item.
results.countryCode
string
obbligatorio
The country code in ISO 3166-1 alpha-2 format.
results.type
string
obbligatorio
The type of long code number.
Possible values: local, national, toll-free, mobile
results.numberString
string
obbligatorio
results.capabilities
object
obbligatorio
Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.
Mostra attributi secondari
results.capabilities.voice
object
obbligatorio
Mostra attributi secondari
results.capabilities.voice.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.voice.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.sms
object
obbligatorio
Mostra attributi secondari
results.capabilities.sms.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.sms.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.mms
object
obbligatorio
Mostra attributi secondari
results.capabilities.mms.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.mms.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.whatsapp
object
Mostra attributi secondari
results.capabilities.whatsapp.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.whatsapp.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.monthlyPrice
object
obbligatorio
Money combines an amount of money with its currency.
Mostra attributi secondari
results.monthlyPrice.currencyCode
string
obbligatorio
Currency as ISO 4217 code (three digits). An example would be EUR for Euro.
Possible values: EUR, USD, GBP, AUD, SGD, IDR, INR, MXN
results.monthlyPrice.amount
integer
obbligatorio
results.monthlyPrice.exponent
integer
obbligatorio
Usually a negative number to specify the exponent for decimal precision. e.g., 1540 * (10^-2) = 15.4
results.backOrderRequired
boolean
Whether back order is required for this item, available but it is not in the local inventory
results.backOrderStockId
string
The stock id of the back order item, to be used when creating back order
nextPageToken
string
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.
Esempio di codice
curl -X GET 'https://api.bird.com/organizations/{organizationId}/numbers-stock-items' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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.
POST
/workspaces/{workspaceId}/numbers-long-code
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.
Payload della richiesta
numberStockItemIds
array of string
obbligatorio
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.
Payload della risposta
results
array of object
obbligatorio
Mostra attributi secondari
results.id
string
obbligatorio
The unique identifier of the long code number. The endpoint ID is the same.
results.endpointId
string
obbligatorio
The unique identifier of the endpoint. The long conde ID is the same.
results.numberString
string
obbligatorio
The phone number in E.164 format.
results.countryCode
string
obbligatorio
The country code in ISO 3166-1 alpha-2 format.
results.type
string
The type of long code number.
Possible values: local, national, toll-free, mobile
results.capabilities
object
obbligatorio
Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.
Mostra attributi secondari
results.capabilities.voice
object
obbligatorio
Mostra attributi secondari
results.capabilities.voice.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.voice.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.sms
object
obbligatorio
Mostra attributi secondari
results.capabilities.sms.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.sms.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.mms
object
obbligatorio
Mostra attributi secondari
results.capabilities.mms.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.mms.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.capabilities.whatsapp
object
Mostra attributi secondari
results.capabilities.whatsapp.inbound
boolean
obbligatorio
Whether the number supports inbound use cases.
results.capabilities.whatsapp.outbound
boolean
obbligatorio
Whether the number supports outbound use cases.
results.createdAt
string
obbligatorio
results.updatedAt
string
obbligatorio
results.order
object
The order that created this long code number. It contains information such as the capabilities, order status and type.
Mostra attributi secondari
results.order.countryCode
string
obbligatorio
The country code in ISO 3166-1 alpha-2 format.
results.order.type
string
obbligatorio
The type of long code number.
Possible values: local, national, toll-free, mobile
results.order.capabilities
array of string
obbligatorio
results.order.prefix
string
results.order.status
string
obbligatorio
Possible values: draft, submitted, processing, fulfilled, rejected, cancelled
results.order.createdAt
string
obbligatorio
results.order.updatedAt
string
obbligatorio
results.deprovisionAt
string
The date and time when the long code number should be deprovisioned.
results.endpoint
object
obbligatorio
A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.
Mostra attributi secondari
results.endpoint.id
string
obbligatorio
The ID of the endpoint.
results.endpoint.type
string
obbligatorio
The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.
Possible values: long-code-number, short-code-number, alpha-number, ip-pool, rcs-google-agent
results.endpoint.instanceId
string
obbligatorio
The unique identifier of the instance.
results.endpoint.name
string
obbligatorio
The name of the endpoint. For some cases it will be the number in international format as string.
results.endpoint.capabilities
array of object
obbligatorio
Mostra attributi secondari
results.endpoint.capabilities.name
string
obbligatorio
Possible values: sms
results.endpoint.capabilities.inbound
object
Mostra attributi secondari
results.endpoint.capabilities.inbound.status
string
obbligatorio
Possible values: active, inactive, available, unavailable
results.endpoint.capabilities.inbound.issues
array of string
results.endpoint.capabilities.outbound
object
Mostra attributi secondari
results.endpoint.capabilities.outbound.status
string
obbligatorio
Possible values: active, inactive, available, unavailable
results.endpoint.capabilities.outbound.destinationStatuses
object
Mostra attributi secondari
results.endpoint.capabilities.outbound.destinationStatuses.active
number
results.endpoint.capabilities.outbound.destinationStatuses.inactive
number
results.endpoint.capabilities.outbound.destinationStatuses.available
number
results.endpoint.capabilities.outbound.destinationStatuses.unavailable
number
results.endpoint.capabilities.outbound.supportsDestinations
boolean
Whether the number supports destinations
results.endpoint.capabilities.outbound.issues
array of string
results.endpoint.dependencies
array of object
The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.
Mostra attributi secondari
results.endpoint.dependencies.type
string
Possible values: connector
results.endpoint.dependencies.connectorId
string
obbligatorio
results.endpoint.dependencies.connectorTemplateRef
string
obbligatorio
results.endpoint.dependencies.capabilities
array of string
results.endpoint.issues
array of string
results.endpoint.provisioningStatus
string
obbligatorio
Possible values: provisioned, provisioning, deprovisioned, deprovisioning
results.endpoint.whatsApp
object
WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.
Mostra attributi secondari
results.endpoint.whatsApp.whatsAppId
string
results.endpoint.whatsApp.status
string
WhatsApp number status
Possible values: unknown, already-exists, installed, verified, not-verified, expired
results.endpoint.whatsApp.stage
string
results.endpoint.whatsApp.attempt
integer
results.endpoint.whatsApp.nextAttemptAt
string
results.endpoint.whatsApp.verificationExpiresAt
string
results.endpoint.whatsApp.requestedCodeAt
string
results.endpoint.whatsApp.createdAt
string
results.endpoint.whatsApp.updatedAt
string
results.endpoint.createdAt
string
obbligatorio
results.endpoint.updatedAt
string
obbligatorio
Esempio di codice
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/numbers-long-code' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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.
POST
/workspaces/{workspaceId}/tfn-verifications
Create TfnVerification
Parametri di query
validate
boolean
When set, only validates the request payload without mutating any data.
Payload della richiesta
phoneNumbers
array of string
obbligatorio
businessName
string
obbligatorio
businessRegistrationNumber
string
Optional business registration number (TaxID). Used for toll-free verification.
businessRegistrationIssuingCountry
string
Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted.
Possible values: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW
businessRegistrationType
string
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: EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER
entityType
string
Type of business entity. Required if businessRegistrationNumber is provided.
Possible values: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT
businessAddr1
string
obbligatorio
businessAddr2
string
businessZip
string
obbligatorio
businessCity
string
obbligatorio
businessState
string
obbligatorio
businessCountry
string
obbligatorio
businessContactFirstName
string
obbligatorio
businessContactLastName
string
obbligatorio
businessContactEmail
string
obbligatorio
businessContactPhone
string
obbligatorio
corporateWebsite
string
obbligatorio
privacyPolicyUrl
string
URL of the business's privacy policy, as presented to consumers at opt-in.
termsAndConditionUrl
string
URL of the business's terms and conditions, as presented to consumers at opt-in.
messageVolume
string
obbligatorio
Possible values: 10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000, 10000000+
useCase
string
obbligatorio
useCaseSummary
string
obbligatorio
productionMessageContent
string
obbligatorio
optInWorkflowDescription
string
obbligatorio
optInWorkflowImageUrLs
array of string
obbligatorio
additionalInformation
string
isvReseller
string
testMode
boolean
brandKycFormEntryId
string
Payload della risposta
brandKycFromId
string
fields
object
Mostra attributi secondari
fields.phoneNumbers
array of string
fields.businessName
string
obbligatorio
fields.businessRegistrationNumber
string
Optional business registration number (TaxID). Used for toll-free verification.
fields.businessRegistrationIssuingCountry
string
Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted.
Possible values: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW
fields.businessRegistrationType
string
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: EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER
fields.entityType
string
Type of business entity. Required if businessRegistrationNumber is provided.
Possible values: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT
fields.businessAddr1
string
obbligatorio
fields.businessAddr2
string
fields.businessZip
string
obbligatorio
fields.businessCity
string
obbligatorio
fields.businessState
string
obbligatorio
fields.businessCountry
string
obbligatorio
fields.businessContactFirstName
string
obbligatorio
fields.businessContactLastName
string
obbligatorio
fields.businessContactEmail
string
obbligatorio
fields.businessContactPhone
string
obbligatorio
fields.corporateWebsite
string
obbligatorio
fields.privacyPolicyUrl
string
URL of the business's privacy policy, as presented to consumers at opt-in.
fields.termsAndConditionUrl
string
URL of the business's terms and conditions, as presented to consumers at opt-in.
fields.messageVolume
string
obbligatorio
Possible values: 10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000, 10000000+
fields.useCase
string
obbligatorio
fields.useCaseSummary
string
obbligatorio
fields.productionMessageContent
string
obbligatorio
fields.optInWorkflowDescription
string
obbligatorio
fields.optInWorkflowImageUrLs
array of string
obbligatorio
fields.additionalInformation
string
fields.isvReseller
string
error
object
A validation error returned from the API. The details map keys are JSON paths pointing into the request body / parameters; values are arrays of human-readable messages describing each problem with that path.
Mostra attributi secondari
error.code
string
obbligatorio
A unique code that identifies the error. This code can be used to programmatically identify the error.
error.details
object
Per-field validation messages keyed by JSON path.
error.message
string
obbligatorio
A human-readable message that describes the error.
Esempio di codice
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/tfn-verifications' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Esempio di codice
{
  "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:
ParameterDescription
businessNameThe name of the Business using Toll Free Number.
businessAddr1The address of the Business using Toll Free Number.
businessAddr2 (optional field)The address of the Business using Toll Free Number.
businessCityThe city of the Business using Toll Free Number.
businessStateThe state of the Business using Toll Free Number.
businessZipThe zip/postal code of the Business using Toll Free Number.
businessCountryCountry of the Business using Toll Free Number.
corporateWebsiteThe website of the Business using Toll Free Number.
businessContactFirstNameBusiness contact first name.
businessContactLastNameBusiness contact last name.
businessContactEmailBusiness contact email address.
businessContactPhoneBusiness contact phone number.
messageVolumeEstimate monthly volume of messages from the Toll Free Number. See more details below.
phoneNumbersIDs of Toll-Free numbers.
useCaseThe Category of the use case. See below types of UseCases
useCaseSummaryPlease provide a general idea of the use case and customer.
productionMessageContentExample of message content.
optInWorkflowDescriptionDescription of the opt in workflow.
optInWorkflowImageURLsImages showing the opt in workflow.
additionalInformation (optional field)Any additional information.
isvReseller (optional field)ISV Name.

UseCase categories must only be of these types

Esempio di codice
[
    "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:
Esempio di codice
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:
Esempio di codice
businessAddr2, additionalInformation, isvReseller

Responses

201: Created
Esempio di codice
{
  "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)
Esempio di codice
{
  "code": "string",
  "message": "string",
  "details": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}
400: Bad request
Esempio di codice
{
    "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
SubmittedVerification is submitted and waiting to be reviewed
InProgressVerification is being reviewed by authority. Additional information may be requested. In case of API integration please inspect the `statusMessage` object for more information.
Verified<p>Verification submission has been approved, and the number is ready to be used.</p><p>
</p>
RejectedVerification submission has been rejected.
GET
/workspaces/{workspaceId}/tfn-verifications/{verificationId}
Get Workspace TfnVerification
Payload della risposta
id
string
organizationId
string
workspaceId
string
verificationRequestId
string
longCodeNumberIds
array of string
verificationRequestData
object
Mostra attributi secondari
verificationRequestData.phoneNumbers
array of string
verificationRequestData.businessName
string
obbligatorio
verificationRequestData.businessRegistrationNumber
string
Optional business registration number (TaxID). Used for toll-free verification.
verificationRequestData.businessRegistrationIssuingCountry
string
Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted.
Possible values: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW
verificationRequestData.businessRegistrationType
string
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: EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER
verificationRequestData.entityType
string
Type of business entity. Required if businessRegistrationNumber is provided.
Possible values: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT
verificationRequestData.businessAddr1
string
obbligatorio
verificationRequestData.businessAddr2
string
verificationRequestData.businessZip
string
obbligatorio
verificationRequestData.businessCity
string
obbligatorio
verificationRequestData.businessState
string
obbligatorio
verificationRequestData.businessCountry
string
obbligatorio
verificationRequestData.businessContactFirstName
string
obbligatorio
verificationRequestData.businessContactLastName
string
obbligatorio
verificationRequestData.businessContactEmail
string
obbligatorio
verificationRequestData.businessContactPhone
string
obbligatorio
verificationRequestData.corporateWebsite
string
obbligatorio
verificationRequestData.privacyPolicyUrl
string
URL of the business's privacy policy, as presented to consumers at opt-in.
verificationRequestData.termsAndConditionUrl
string
URL of the business's terms and conditions, as presented to consumers at opt-in.
verificationRequestData.messageVolume
string
obbligatorio
Possible values: 10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000, 10000000+
verificationRequestData.useCase
string
obbligatorio
verificationRequestData.useCaseSummary
string
obbligatorio
verificationRequestData.productionMessageContent
string
obbligatorio
verificationRequestData.optInWorkflowDescription
string
obbligatorio
verificationRequestData.optInWorkflowImageUrLs
array of string
obbligatorio
verificationRequestData.additionalInformation
string
verificationRequestData.isvReseller
string
status
string
Possible values: submitted, in-progress, verified, rejected
statusMessage
object
Mostra attributi secondari
statusMessage.statusCode
string
statusMessage.declineReasonDescription
string
statusMessage.resubmitAllowed
boolean
testMode
boolean
createdAt
string
updatedAt
string
Esempio di codice
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/tfn-verifications/{verificationId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Responses

200 OK:
Esempio di codice
{
  "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:
Esempio di codice
{
  "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.
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.
PUT
/workspaces/{workspaceId}/tfn-verifications/{verificationId}
Update Workspace TfnVerification submission, and submit updates to 3rd party TfnVerification API
Payload della richiesta
phoneNumbers
array of string
businessName
string
obbligatorio
businessRegistrationNumber
string
Optional business registration number (TaxID). Used for toll-free verification.
businessRegistrationIssuingCountry
string
Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted.
Possible values: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW
businessRegistrationType
string
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: EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER
entityType
string
Type of business entity. Required if businessRegistrationNumber is provided.
Possible values: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT
businessAddr1
string
obbligatorio
businessAddr2
string
businessZip
string
obbligatorio
businessCity
string
obbligatorio
businessState
string
obbligatorio
businessCountry
string
obbligatorio
businessContactFirstName
string
obbligatorio
businessContactLastName
string
obbligatorio
businessContactEmail
string
obbligatorio
businessContactPhone
string
obbligatorio
corporateWebsite
string
obbligatorio
privacyPolicyUrl
string
URL of the business's privacy policy, as presented to consumers at opt-in.
termsAndConditionUrl
string
URL of the business's terms and conditions, as presented to consumers at opt-in.
messageVolume
string
obbligatorio
Possible values: 10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000, 10000000+
useCase
string
obbligatorio
useCaseSummary
string
obbligatorio
productionMessageContent
string
obbligatorio
optInWorkflowDescription
string
obbligatorio
optInWorkflowImageUrLs
array of string
obbligatorio
additionalInformation
string
isvReseller
string
Payload della risposta
id
string
organizationId
string
workspaceId
string
verificationRequestId
string
longCodeNumberIds
array of string
verificationRequestData
object
Mostra attributi secondari
verificationRequestData.phoneNumbers
array of string
verificationRequestData.businessName
string
obbligatorio
verificationRequestData.businessRegistrationNumber
string
Optional business registration number (TaxID). Used for toll-free verification.
verificationRequestData.businessRegistrationIssuingCountry
string
Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted.
Possible values: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW
verificationRequestData.businessRegistrationType
string
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: EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER
verificationRequestData.entityType
string
Type of business entity. Required if businessRegistrationNumber is provided.
Possible values: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT
verificationRequestData.businessAddr1
string
obbligatorio
verificationRequestData.businessAddr2
string
verificationRequestData.businessZip
string
obbligatorio
verificationRequestData.businessCity
string
obbligatorio
verificationRequestData.businessState
string
obbligatorio
verificationRequestData.businessCountry
string
obbligatorio
verificationRequestData.businessContactFirstName
string
obbligatorio
verificationRequestData.businessContactLastName
string
obbligatorio
verificationRequestData.businessContactEmail
string
obbligatorio
verificationRequestData.businessContactPhone
string
obbligatorio
verificationRequestData.corporateWebsite
string
obbligatorio
verificationRequestData.privacyPolicyUrl
string
URL of the business's privacy policy, as presented to consumers at opt-in.
verificationRequestData.termsAndConditionUrl
string
URL of the business's terms and conditions, as presented to consumers at opt-in.
verificationRequestData.messageVolume
string
obbligatorio
Possible values: 10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000, 10000000+
verificationRequestData.useCase
string
obbligatorio
verificationRequestData.useCaseSummary
string
obbligatorio
verificationRequestData.productionMessageContent
string
obbligatorio
verificationRequestData.optInWorkflowDescription
string
obbligatorio
verificationRequestData.optInWorkflowImageUrLs
array of string
obbligatorio
verificationRequestData.additionalInformation
string
verificationRequestData.isvReseller
string
status
string
Possible values: submitted, in-progress, verified, rejected
statusMessage
object
Mostra attributi secondari
statusMessage.statusCode
string
statusMessage.declineReasonDescription
string
statusMessage.resubmitAllowed
boolean
testMode
boolean
createdAt
string
updatedAt
string
Esempio di codice
curl -X PUT 'https://api.bird.com/workspaces/{workspaceId}/tfn-verifications/{verificationId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Esempio di codice
{
  "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",
  "testMode": true
}

Responses

200 OK:
Esempio di codice
{
  "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:44:03.004Z",
  "updatedAt": "2023-10-12T13:44:03.004Z"
}
```

#### 400: Bad request 
Error processing the request
```json
{
    "code": "string",
    "message": "string"
}
404 Not Found:
Esempio di codice
{
  "code": "string",
  "message": "string"
}
422: Unprocessable Entity
Esempio di codice
{
  "code": "string",
  "message": "string",
  "details": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}