Buying a number through Bird

If you require a number for your customer, these are available to acquire through Bird CRM using our numbers API. Once you purchase the number this will automatically be verified on WhatsApp for use in the embedded signup flow.

Find an available number

If you do not already have a number available in your workspace you can find one to purchase

List all available numbers in stock at organization level.

get

Authorizations

Path parameters

organizationIdstring · uuidrequired

The ID for the organization.

Example: d0b85ccc-b63a-4e81-b698-c359d77d250e

Query parameters

limitinteger · min: 1 · max: 99 · default: 10optional

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.

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

typesstring · enum[]optional

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.

Example: ["toll-free"]

featuresstring · enum[] · min: 1optional

The number capabilities, which can be voice, SMS, and MMS for inbound, outbound, or two-way communication, plus WhatsApp.

Example: ["sms-outbound"]

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/organizations/{organizationId}/numbers-stock-items' \
  --header 'Authorization: Bearer jwt'

200

422

200

{
  "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
        }
      },
      "monthlyPrice": {
        "currencyCode": "EUR",
        "amount": 3500000,
        "exponent": -6
      },
      "backOrderRequired": true,
      "backOrderStockId": "text"
    }
  ],
  "nextPageToken": "text"
}

OK

Purchase a number

Once you have found an available number, you can purchase it by providing the number (using the unique identifier provided by the endpoint above).

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

Path parameters

workspaceIdstring · uuidrequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e

Body

numberStockItemIdsstring · uuid[] · max: 25required

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

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/workspaces/{workspaceId}/numbers-long-code' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{
    "numberStockItemIds": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  }'

201

422

201

{
  "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
        }
      },
      "createdAt": "2025-03-28T19:31:10.501Z",
      "updatedAt": "2025-03-28T19:31:10.501Z",
      "order": {
        "countryCode": "US",
        "type": "local",
        "capabilities": [
          "voice"
        ],
        "prefix": "text",
        "status": "draft",
        "createdAt": "2025-03-28T19:31:10.501Z",
        "updatedAt": "2025-03-28T19:31:10.501Z"
      },
      "deprovisionAt": "2025-03-28T19:31:10.501Z",
      "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": "2025-03-28T19:31:10.501Z",
        "updatedAt": "2025-03-28T19:31:10.501Z"
      }
    }
  ]
}

Created

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

Subscribing to channel created webhooks