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 available Numbers in Inventory

Retrieve a list of available inventory numbers

GET/workspaces/{workspaceId}/numbers-available

Authorization

useraccessKey

Path parameters

workspaceId*string

Query parameters

Response

200400

OK

Body

application/json

results*array of NumberAvailable (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.

Request

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/numbers-available', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

{
  "results": [
    {
      "type": "local",
      "capabilities": {
        "sms": {
          "inbound": false,
          "outbound": false
        },
        "voice": {
          "inbound": false,
          "outbound": false
        },
        "mms": {
          "inbound": false,
          "outbound": false
        },
        "fax": {
          "inbound": false,
          "outbound": false
        }
      },
      "number": "text",
      "country": "text",
      "monthlyRecurringPrice": {
        "currencyCode": "EUR"
      },
      "complianceRequirements": [
        {
          "name": "text",
          "type": "kycForm",
          "scope": "number-activation",
          "selector": {
            "scope": "text",
            "numberType": "local",
            "countryCode": "text"
          }
        }
      ]
    }
  ],
  "nextPageToken": "text"
}

Example

Request

The following example will return the first available US local number available to purchase

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/numbers-available?limit=1&country=US&type=local' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>'

Purchase a number

Once you have found an available number you can purchase this by providing the number (in E.1624 format) and the country (using a two digit ISO code).

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

Create Number

Purchase numbers and assign them to the workspace. Purchasing of the numbers requires sufficient balance in the workspace wallet.

POST/workspaces/{workspaceId}/numbers

Authorization

useraccessKey

Path parameters

workspaceId*string

Body

application/json

numbers*array of object

Response

201400402404409422

Created

Body

application/json

numbers*array of Number (object)

Request

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/numbers', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "numbers": [
        {
          "number": "text",
          "country": "text"
        }
      ]
    }),
});
const data = await response.json();

Response

{
  "numbers": [
    {
      "type": "local",
      "capabilities": {
        "sms": {
          "inbound": false,
          "outbound": false
        },
        "voice": {
          "inbound": false,
          "outbound": false
        },
        "mms": {
          "inbound": false,
          "outbound": false
        },
        "fax": {
          "inbound": false,
          "outbound": false
        }
      },
      "number": "text",
      "country": "text",
      "monthlyRecurringPrice": {
        "currencyCode": "EUR"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "subscription": {
        "status": "active",
        "subscribedAt": "2024-07-27T06:55:38.982Z",
        "updatedAt": "2024-07-27T06:55:38.982Z",
        "cancelledAt": "2024-07-27T06:55:38.982Z"
      },
      "endpointSubscription": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "correlationId": "123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "subscribedAt": "2024-07-27T06:55:38.982Z",
        "updatedAt": "2024-07-27T06:55:38.982Z",
        "canceledAt": "2024-07-27T06:55:38.982Z",
        "startAt": "2024-07-27T06:55:38.982Z",
        "endAt": "2024-07-27T06:55:38.982Z"
      },
      "configurations": {
        "voice": {
          "inbound": {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text"
          },
          "outbound": {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text"
          }
        },
        "sms": {
          "inbound": {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text"
          },
          "outbound": {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text"
          }
        },
        "mms": {
          "inbound": {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text"
          },
          "outbound": {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text"
          }
        },
        "fax": {
          "inbound": {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text"
          },
          "outbound": {
            "connectorId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
            "connectorTemplateRef": "text"
          }
        },
        "whatsapp": {
          "connectorId": "123e4567-e89b-12d3-a456-426614174000",
          "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
          "connectorTemplateRef": "text"
        }
      },
      "createdAt": "2024-07-27T06:55:38.982Z",
      "updatedAt": "2024-07-27T06:55:38.982Z",
      "activatedAt": "2024-07-27T06:55:38.982Z",
      "deactivatedAt": "2024-07-27T06:55:38.982Z",
      "deactivatesAt": "2024-07-27T06:55:38.982Z",
      "requirements": [
        {
          "requirement": {
            "name": "text",
            "type": "kycForm",
            "scope": "number-activation",
            "selector": {
              "scope": "text",
              "numberType": "local",
              "countryCode": "text"
            }
          },
          "status": "ok",
          "reference": "text",
          "notOkSince": "2024-07-27T06:55:38.982Z"
        }
      ],
      "endpoint": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "long-code-number",
        "instanceId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "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": "2024-07-27T06:55:38.982Z",
        "updatedAt": "2024-07-27T06:55:38.982Z"
      },
      "whatsApp": {
        "whatsAppId": "text",
        "status": "verified",
        "stage": "text",
        "nextAttemptAt": "2024-07-27T06:55:38.982Z",
        "verificationExpiresAt": "2024-07-27T06:55:38.982Z",
        "requestedCodeAt": "2024-07-27T06:55:38.982Z",
        "createdAt": "2024-07-27T06:55:38.982Z",
        "updatedAt": "2024-07-27T06:55:38.982Z"
      }
    }
  ]
}

Request

The following example will purchase the number if it still available and you have sufficient balance in your workspace wallet. Provide number in E.1624 format and country in 2 digit ISO code (e.g. US)

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/numbers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
  "numbers": [
    {
      "number": "",
      "country": ""
    }
  ]
}'

Subscribing to channel created webhooks