No-code docs
Resources

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
Path parameters
workspaceId*string
Query parameters
Response

OK

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

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
Path parameters
workspaceId*string
Body
numbers*array of object
Response

Created

Body
numbers*array of Number (object)
Request
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-09-07T23:32:26.600Z",
        "updatedAt": "2024-09-07T23:32:26.600Z",
        "cancelledAt": "2024-09-07T23:32:26.600Z"
      },
      "endpointSubscription": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "correlationId": "123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "subscribedAt": "2024-09-07T23:32:26.600Z",
        "updatedAt": "2024-09-07T23:32:26.600Z",
        "canceledAt": "2024-09-07T23:32:26.600Z",
        "startAt": "2024-09-07T23:32:26.600Z",
        "endAt": "2024-09-07T23:32:26.600Z"
      },
      "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-09-07T23:32:26.600Z",
      "updatedAt": "2024-09-07T23:32:26.600Z",
      "activatedAt": "2024-09-07T23:32:26.600Z",
      "deactivatedAt": "2024-09-07T23:32:26.600Z",
      "deactivatesAt": "2024-09-07T23:32:26.600Z",
      "requirements": [
        {
          "requirement": {
            "name": "text",
            "type": "kycForm",
            "scope": "number-activation",
            "selector": {
              "scope": "text",
              "numberType": "local",
              "countryCode": "text"
            }
          },
          "status": "ok",
          "reference": "text",
          "notOkSince": "2024-09-07T23:32:26.600Z"
        }
      ],
      "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-09-07T23:32:26.600Z",
        "updatedAt": "2024-09-07T23:32:26.600Z"
      },
      "whatsApp": {
        "whatsAppId": "text",
        "status": "verified",
        "stage": "text",
        "nextAttemptAt": "2024-09-07T23:32:26.600Z",
        "verificationExpiresAt": "2024-09-07T23:32:26.600Z",
        "requestedCodeAt": "2024-09-07T23:32:26.600Z",
        "createdAt": "2024-09-07T23:32:26.600Z",
        "updatedAt": "2024-09-07T23:32:26.600Z"
      }
    }
  ]
}

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

Last updated