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

Authorizations

accessKey

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 belonging to a specific local area-code. It MUST be used in conjunction with the countryCodes filter. Always provide prefixes in full international format.

Example: +1212

testingbooleanOptional

Responses

200

OK

application/json

422

Invalid filter

application/json

get

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

HTTPcURLJavaScriptPython

GET /organizations/{organizationId}/numbers-stock-items HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "countryCode": "US",
      "type": "local",
      "numberString": "[phone]",
      "capabilities": {
        "voice": {
          "inbound": true,
          "outbound": true
        },
        "sms": {
          "inbound": true,
          "outbound": true
        },
        "mms": {
          "inbound": true,
          "outbound": true
        },
        "whatsapp": {
          "inbound": true,
          "outbound": true
        }
      },
      "monthlyPrice": {
        "currencyCode": "EUR",
        "amount": 3500000,
        "exponent": -6
      },
      "backOrderRequired": true,
      "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

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

accessKey

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

application/json

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

201

Created

application/json

404

Long Code Number not found

application/json

422

Validation error

application/json

post

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

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/numbers-long-code HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "numberStockItemIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

{
  "results": [
    {
      "id": "41e3cf43-4386-464a-a1ee-e6ef6fd6883d",
      "endpointId": "41e3cf43-4386-464a-a1ee-e6ef6fd6883d",
      "numberString": "[phone]",
      "countryCode": "US",
      "type": "local",
      "capabilities": {
        "voice": {
          "inbound": true,
          "outbound": true
        },
        "sms": {
          "inbound": true,
          "outbound": true
        },
        "mms": {
          "inbound": true,
          "outbound": true
        },
        "whatsapp": {
          "inbound": true,
          "outbound": true
        }
      },
      "createdAt": "2026-01-22T13:24:11.446Z",
      "updatedAt": "2026-01-22T13:24:11.446Z",
      "order": {
        "countryCode": "US",
        "type": "local",
        "capabilities": [
          "voice"
        ],
        "prefix": "text",
        "status": "draft",
        "createdAt": "2026-01-22T13:24:11.446Z",
        "updatedAt": "2026-01-22T13:24:11.446Z"
      },
      "deprovisionAt": "2026-01-22T13:24:11.446Z",
      "endpoint": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "long-code-number",
        "instanceId": "1551f382-6870-4480-8f9b-f5ab34936288",
        "name": "[phone]",
        "capabilities": [
          {
            "name": "sms",
            "inbound": {
              "status": "active",
              "issues": [
                "subscription-is-not-active"
              ]
            },
            "outbound": {
              "status": "active",
              "destinationStatuses": {
                "active": 1,
                "inactive": 1,
                "available": 1,
                "unavailable": 1
              },
              "supportsDestinations": true,
              "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": "2026-01-22T13:24:11.446Z",
        "updatedAt": "2026-01-22T13:24:11.446Z"
      }
    }
  ]
}

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

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.

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

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

Authorizations

accessKey

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

application/json

Responses

200

Validation Response

application/json

201

Created

application/json

400

Bad request

application/json

422

Validation error

application/json

post

/workspaces/{workspaceId}/tfn-verifications

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/tfn-verifications HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 804

{
  "phoneNumbers": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "businessName": "text",
  "businessRegistrationNumber": "text",
  "businessRegistrationIssuingCountry": "US",
  "businessRegistrationType": "EIN",
  "entityType": "SOLE_PROPRIETOR",
  "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",
  "testMode": true,
  "brandKycFormEntryId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "brandKycFromId": "123e4567-e89b-12d3-a456-426614174000",
  "fields": {
    "phoneNumbers": [
      "text"
    ],
    "businessName": "text",
    "businessRegistrationNumber": "text",
    "businessRegistrationIssuingCountry": "US",
    "businessRegistrationType": "EIN",
    "entityType": "SOLE_PROPRIETOR",
    "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.",
    "details": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Request

{
  "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 the status of a toll-free number verification

Once you submit your verification request, you must wait for it 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

Authorizations

accessKey

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

200

OK

application/json

404

TfnVerification not found

application/json

get

/workspaces/{workspaceId}/tfn-verifications/{verificationId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/tfn-verifications/{verificationId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "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",
    "businessRegistrationNumber": "text",
    "businessRegistrationIssuingCountry": "US",
    "businessRegistrationType": "EIN",
    "entityType": "SOLE_PROPRIETOR",
    "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": true
  },
  "testMode": true,
  "createdAt": "2026-01-22T13:24:11.446Z",
  "updatedAt": "2026-01-22T13:24:11.446Z"
}

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

Verification status Message

If verification is rejected, some information will be provided in the DeclineReasonDescription if is in Progress, and any additional details have been required by the reviewing authority, you can find details in the Message field

  "statusMessage": {
    "StatusCode": "string",
    "DeclineReasonDescription": "string",
    "ResubmitAllowed": "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. Always check the ResubmissionAllow filed in the StatusMessage before using this method

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

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

put

Authorizations

accessKey

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

application/json

Responses

200

OK

application/json

400

Bad request

application/json

404

TfnVerification not found

application/json

422

Validation error

application/json

put

/workspaces/{workspaceId}/tfn-verifications/{verificationId}

HTTPcURLJavaScriptPython

PUT /workspaces/{workspaceId}/tfn-verifications/{verificationId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 695

{
  "phoneNumbers": [
    "text"
  ],
  "businessName": "text",
  "businessRegistrationNumber": "text",
  "businessRegistrationIssuingCountry": "US",
  "businessRegistrationType": "EIN",
  "entityType": "SOLE_PROPRIETOR",
  "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"
}

{
  "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",
    "businessRegistrationNumber": "text",
    "businessRegistrationIssuingCountry": "US",
    "businessRegistrationType": "EIN",
    "entityType": "SOLE_PROPRIETOR",
    "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": true
  },
  "testMode": true,
  "createdAt": "2026-01-22T13:24:11.446Z",
  "updatedAt": "2026-01-22T13:24:11.446Z"
}

Request

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

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

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

422: Unprocessable Entity

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

Retrieve all Verification of a Workspaces

List Workspace TfnVerifications

get

Authorizations

accessKey

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

Responses

200

OK

application/json

404

TfnVerification not found

application/json

get

/workspaces/{workspaceId}/tfn-verifications

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/tfn-verifications HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "nextPageToken": "text",
  "results": [
    {
      "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",
        "businessRegistrationNumber": "text",
        "businessRegistrationIssuingCountry": "US",
        "businessRegistrationType": "EIN",
        "entityType": "SOLE_PROPRIETOR",
        "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": true
      },
      "testMode": true,
      "createdAt": "2026-01-22T13:24:11.446Z",
      "updatedAt": "2026-01-22T13:24:11.446Z"
    }
  ]
}

A TFN may have multiple verifications (example the firs submission was rejected by the reviewing authority ) but only one of them can be active