Buy a 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-22T17:07:13.399Z",
      "updatedAt": "2026-01-22T17:07:13.399Z",
      "order": {
        "countryCode": "US",
        "type": "local",
        "capabilities": [
          "voice"
        ],
        "prefix": "text",
        "status": "draft",
        "createdAt": "2026-01-22T17:07:13.399Z",
        "updatedAt": "2026-01-22T17:07:13.399Z"
      },
      "deprovisionAt": "2026-01-22T17:07:13.399Z",
      "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-22T17:07:13.399Z",
        "updatedAt": "2026-01-22T17:07:13.399Z"
      }
    }
  ]
}

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

MessageBird_userMessageBird_accessKey

AuthorizationstringRequired

An access token issued to a user.

Path parameters

workspaceIdstringRequired

Body

application/json

numberStockItemIdsstring · uuid[] · max: 25Required

Responses

201

Created

application/json

422

Validation error

application/json

post

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

HTTPcURLJavaScriptPython

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

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

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "endpointId": "123e4567-e89b-12d3-a456-426614174000",
      "numberString": "text",
      "countryCode": "text",
      "type": "local",
      "capabilities": {
        "voice": {
          "inbound": true,
          "outbound": true
        },
        "sms": {
          "inbound": true,
          "outbound": true
        },
        "mms": {
          "inbound": true,
          "outbound": true
        }
      },
      "createdAt": "2026-01-22T17:07:13.399Z",
      "updatedAt": "2026-01-22T17:07:13.399Z",
      "order": {
        "countryCode": "text",
        "type": "local",
        "capabilities": [
          "voice"
        ],
        "prefix": "text",
        "status": "draft",
        "createdAt": "2026-01-22T17:07:13.399Z",
        "updatedAt": "2026-01-22T17:07:13.399Z"
      },
      "deprovisionAt": "2026-01-22T17:07:13.399Z",
      "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": 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-22T17:07:13.399Z",
        "updatedAt": "2026-01-22T17:07:13.399Z"
      }
    }
  ]
}