Long Code Numbers

Overview

The current concept of Number represents the so-called Long Code Number. Long Code Number always relates to the Number purchased or ordered from the Inventory. This is any number, that has a country prefix at the beginning. The term Number is renamed to LongCodeNumber.

API Access

The following API requests can only be made using a valid access key, and attached to an access role, with an access policy that at least specifies the permissions to the resources outlined in each section below. Learn more about API access.

List Long Code Numbers

In order to retrieve a list of long code numbers available in your workspace you can use this request.

List Workspace Long Code Numbers

get

Get a list of all Long code numbers assigned to your workspace. You can filter your list of numbers by country code, types (e.g. a local, mobile, or toll-free number), supported capabilities and the number leading digits. The results can be paginated. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.

Authorizations

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

Query parameters

limitinteger · min: 1 · max: 99Optional

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.

Default: 10

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.

reversebooleanOptional

Order in which to retrieve the results. By default, the orders are in ascending order date. To get the results in descending order, set this parameter to true.

Default: false

numberStringstringOptional

Used to filter numbers by their leading digits. The "+" prefix is optional, but the country code is required.

Example: +1212

countryCodesstring · iso3166-1[]Optional

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

Example: ["US","NL"]

providerIdsstring · uuid[]OptionalExample: f6606a78-e48e-4026-b5e8-4fb9c3ed3bbb

Responses

200

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.

get

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

GET /workspaces/{workspaceId}/numbers-long-code HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

200

{
  "nextPageToken": "text",
  "results": [
    {
      "id": "41e3cf43-4386-464a-a1ee-e6ef6fd6883d",
      "endpointId": "41e3cf43-4386-464a-a1ee-e6ef6fd6883d",
      "numberString": "+14155552671",
      "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-03-23T23:29:07.795Z",
      "updatedAt": "2026-03-23T23:29:07.795Z",
      "order": {
        "countryCode": "US",
        "type": "local",
        "capabilities": [
          "voice"
        ],
        "prefix": "text",
        "status": "draft",
        "createdAt": "2026-03-23T23:29:07.795Z",
        "updatedAt": "2026-03-23T23:29:07.795Z"
      },
      "deprovisionAt": "2026-03-23T23:29:07.795Z",
      "endpoint": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "long-code-number",
        "instanceId": "1551f382-6870-4480-8f9b-f5ab34936288",
        "name": "+14155552671",
        "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-03-23T23:29:07.795Z",
          "verificationExpiresAt": "2026-03-23T23:29:07.795Z",
          "requestedCodeAt": "2026-03-23T23:29:07.795Z",
          "createdAt": "2026-03-23T23:29:07.795Z",
          "updatedAt": "2026-03-23T23:29:07.795Z"
        },
        "createdAt": "2026-03-23T23:29:07.795Z",
        "updatedAt": "2026-03-23T23:29:07.795Z"
      }
    }
  ]
}

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-long-code/"
-H 'Authorization: Bearer '

{
    "results": [
        {
            "id": "uuid",
            "numberString": "string",
            "countryCode": "string",
            "type": "local|mobile|toll-free|national",
            "capabilities": {
                "voice": {
                    "inbound": true,
                    "outbound": true
                },
                "sms": {
                    "inbound": true,
                    "outbound": false
                },
                "mms": {
                    "inbound": false,
                    "outbound": true
                }
            },
            "endpointId": "uuid",
            "createdAt": "2023-10-20T10:27:22.489-03:00",
            "updatedAt": "2023-10-20T10:27:22.489-03:00",
            "endpoint": {
                "id": "uuid",
                "type": "long-code-number",
                "instanceId": "uuid",
                "name": "string",
                "createdAt": "2023-10-20T10:27:22.489-03:00",
                "updatedAt": "2023-10-20T10:27:22.489-03:00",
                "capabilities": [
                    {
                        "name": "voice",
                        "inbound": {
                            "status": "inactive",
                            "subscriptions": [
                                "main"
                            ]
                        },
                        "outbound": {
                            "status": "inactive",
                            "subscriptions": [
                                "main"
                            ],
                            "destinationStatuses": {
                                "inactive": 249
                            }
                        }
                    },
                    {
                        "name": "sms",
                        "inbound": {
                            "status": "inactive",
                            "subscriptions": [
                                "main"
                            ]
                        },
                        "outbound": null
                    },
                    {
                        "name": "mms",
                        "inbound": null,
                        "outbound": {
                            "status": "inactive",
                            "subscriptions": [
                                "main"
                            ],
                            "destinationStatuses": {
                                "inactive": 249
                            }
                        }
                    }
                ]
            }
        },
        {
            "id": "uuid",
            "numberString": "string",
            "countryCode": "string",
            "type": "local|mobile|toll-free|national",
            "capabilities": {
                "voice": {
                    "inbound": true,
                    "outbound": true
                },
                "sms": {
                    "inbound": true,
                    "outbound": false
                },
                "mms": {
                    "inbound": false,
                    "outbound": true
                }
            },
            "endpointId": "uuid",
            "createdAt": "2023-10-20T10:27:22.469-03:00",
            "updatedAt": "2023-10-20T10:27:22.469-03:00",
            "endpoint": {
                "id": "uuid",
                "type": "long-code-number",
                "instanceId": "uuid",
                "name": "sting",
                "createdAt": "2023-10-20T10:27:22.469-03:00",
                "updatedAt": "2023-10-20T10:27:22.469-03:00",
                "capabilities": [
                    {
                        "name": "voice",
                        "inbound": {
                            "status": "inactive",
                            "subscriptions": [
                                "main"
                            ]
                        },
                        "outbound": {
                            "status": "inactive",
                            "subscriptions": [
                                "main"
                            ],
                            "destinationStatuses": {
                                "inactive": 249
                            }
                        }
                    },
                    {
                        "name": "sms",
                        "inbound": {
                            "status": "inactive",
                            "subscriptions": [
                                "main"
                            ]
                        },
                        "outbound": null
                    },
                    {
                        "name": "mms",
                        "inbound": null,
                        "outbound": {
                            "status": "inactive",
                            "subscriptions": [
                                "main"
                            ],
                            "destinationStatuses": {
                                "inactive": 249
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Get a Long Code Number

In order to retrieve the details of a long code number available in your workspace you can use this request.

Get Long Code number by ID

get

This endpoint returns the information of a Long Code Number assigned to the workspace given its ID. You may use the EndpointID as well to search for your long code number.

Authorizations

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

longCodeNumberIdstringRequired

Your long code number/endpoint ID.

Example: 3d7eb12b-9101-450d-923b-5ffcd9e989a9

Responses

200

application/json

idstring · uuidRequired

The unique identifier of the long code number. The endpoint ID is the same.

Example: 41e3cf43-4386-464a-a1ee-e6ef6fd6883d

endpointIdstring · uuidRequired

The unique identifier of the endpoint. The long conde ID is the same.

Example: 41e3cf43-4386-464a-a1ee-e6ef6fd6883d

numberStringstringRequired

The phone number in E.164 format.

Example: +14155552671

countryCodestring · iso3166-1Required

The country code in ISO 3166-1 alpha-2 format.

Example: US

typestring · enumOptional

The type of long code number.

Possible values:

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deprovisionAtstring · date-timeOptional

The date and time when the long code number should be deprovisioned.

404

Long Code Number not found

application/json

get

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

GET /workspaces/{workspaceId}/numbers-long-code/{longCodeNumberId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "41e3cf43-4386-464a-a1ee-e6ef6fd6883d",
  "endpointId": "41e3cf43-4386-464a-a1ee-e6ef6fd6883d",
  "numberString": "+14155552671",
  "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-03-23T23:29:07.795Z",
  "updatedAt": "2026-03-23T23:29:07.795Z",
  "order": {
    "countryCode": "US",
    "type": "local",
    "capabilities": [
      "voice"
    ],
    "prefix": "text",
    "status": "draft",
    "createdAt": "2026-03-23T23:29:07.795Z",
    "updatedAt": "2026-03-23T23:29:07.795Z"
  },
  "deprovisionAt": "2026-03-23T23:29:07.795Z",
  "endpoint": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "long-code-number",
    "instanceId": "1551f382-6870-4480-8f9b-f5ab34936288",
    "name": "+14155552671",
    "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-03-23T23:29:07.795Z",
      "verificationExpiresAt": "2026-03-23T23:29:07.795Z",
      "requestedCodeAt": "2026-03-23T23:29:07.795Z",
      "createdAt": "2026-03-23T23:29:07.795Z",
      "updatedAt": "2026-03-23T23:29:07.795Z"
    },
    "createdAt": "2026-03-23T23:29:07.795Z",
    "updatedAt": "2026-03-23T23:29:07.795Z"
  }
}

curl "https://api.bird.com/workspaces/{workspaceId}/numbers-long-code/{longCodeId}" \
     -H 'Authorization: Bearer <your-access-key>'

{
    "id": "uuid",
    "numberString": "string",
    "countryCode": "string",
    "type": "local|mobile|toll-free|national",
    "capabilities": {
        "voice": {
            "inbound": true,
            "outbound": true
        },
        "sms": {
            "inbound": true,
            "outbound": false
        },
        "mms": {
            "inbound": false,
            "outbound": true
        }
    },
    "endpointId": "uuid",
    "createdAt": "2023-10-20T10:27:22.469-03:00",
    "updatedAt": "2023-10-20T10:27:22.469-03:00",
    "endpoint": {
        "id": "uuid",
        "type": "long-code-number",
        "instanceId": "uuid",
        "name": "sting",
        "createdAt": "2023-10-20T10:27:22.469-03:00",
        "updatedAt": "2023-10-20T10:27:22.469-03:00",
        "capabilities": [
            {
                "name": "voice",
                "inbound": {
                    "status": "inactive",
                    "subscriptions": [
                        "main"
                    ]
                },
                "outbound": {
                    "status": "inactive",
                    "subscriptions": [
                        "main"
                    ],
                    "destinationStatuses": {
                        "inactive": 249
                    }
                }
            },
            {
                "name": "sms",
                "inbound": {
                    "status": "inactive",
                    "subscriptions": [
                        "main"
                    ]
                },
                "outbound": null
            },
            {
                "name": "mms",
                "inbound": null,
                "outbound": {
                    "status": "inactive",
                    "subscriptions": [
                        "main"
                    ],
                    "destinationStatuses": {
                        "inactive": 249
                    }
                }
            }
        ]
    }
}

Last updated 7 months ago

Was this helpful?

hashtagOverview

hashtagAPI Access

hashtagList Long Code Numbers

hashtagList Workspace Long Code Numbers

hashtagGet a Long Code Number

hashtagGet Long Code number by ID

Overview

API Access

List Long Code Numbers

List Workspace Long Code Numbers

Get a Long Code Number

Get Long Code number by ID