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.

get

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

organizationIdstring · uuidRequired

The unique identifier of the organization.

Query parameters

limitinteger · max: 100Optional

Limits the number of results to return.

Default: 25

pageTokenstringOptional

The cursor that keeps track of the current position in the results.

countryCodesstring · iso3166-1[]Optional

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

Example: ["US","NL"]

prefixstring · min: 1 · max: 250Optional

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

Example: +1212

testingbooleanOptional

Responses

200

OK

application/json

nextPageTokenstringOptional

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

422

The request contains invalid parameters or body fields.

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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

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

402

An error.

application/json

404

The requested resource was not found.

application/json

422

The request contains invalid parameters or body fields.

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-07-18T22:33:33.061Z",
      "updatedAt": "2026-07-18T22:33:33.061Z",
      "order": {
        "countryCode": "US",
        "type": "local",
        "capabilities": [
          "voice"
        ],
        "prefix": "text",
        "status": "draft",
        "createdAt": "2026-07-18T22:33:33.061Z",
        "updatedAt": "2026-07-18T22:33:33.061Z"
      },
      "deprovisionAt": "2026-07-18T22:33:33.061Z",
      "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",
        "whatsApp": {
          "whatsAppId": "text",
          "status": "verified",
          "stage": "text",
          "attempt": 1,
          "nextAttemptAt": "2026-07-18T22:33:33.061Z",
          "verificationExpiresAt": "2026-07-18T22:33:33.061Z",
          "requestedCodeAt": "2026-07-18T22:33:33.061Z",
          "createdAt": "2026-07-18T22:33:33.061Z",
          "updatedAt": "2026-07-18T22:33:33.061Z"
        },
        "createdAt": "2026-07-18T22:33:33.061Z",
        "updatedAt": "2026-07-18T22:33:33.061Z"
      }
    }
  ]
}

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