No-code docs

List your Numbers

Get a list of all Long code numbers assigned to your workspace.

You can filter your list of numbers using any of th following attributes:

  • countryCode: 2 digit ISO code of the country, example: US for United States, we follow iso3166-1 standard.

  • types: types of numbers your are searching for. Check API spec for allowed values.

  • capabilities: the capabilities of the number (sms, mms, voice, whatsapp). Check API spec for allowed values..

  • numberString: search numbers by their leading digits.

List Numbers in Workspace

get

List all purchased numbers assigned to the workspace. This endpoint provides various filtering options, including Country, Number Type and Capabilities.

Authorizations
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
prefixstring · min: 1 · max: 250Optional

Used to filter numbers belonging to a specific local area-code. It MUST be used in conjunction with the countryCodes filter. Always provide prefixes in full international format.

Example: +1212
searchTermstring · min: 1 · max: 250Optional

Used to filter for numbers containing the search term.

statusstring · enumOptional

The status of the number.

Possible values:
typestring · enumOptional

The type of the number.

Possible values:
countrystring · iso3166-1Optional

The country of the number.

smsstring · enumOptional

Include the SMS capability in the search filter.

Possible values:
voicestring · enumOptional

Include the Voice capability in the search filter.

Possible values:
mmsstring · enumOptional

Include the MMS capability in the search filter.

Possible values:
faxstring · enumOptional

Include the Fax capability in the search filter.

Possible values:
Responses
200
OK
application/json
Responseall of
get
GET /workspaces/{workspaceId}/numbers HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "type": "local",
      "capabilities": {
        "sms": {
          "inbound": true,
          "outbound": true
        },
        "voice": {
          "inbound": true,
          "outbound": true
        },
        "mms": {
          "inbound": true,
          "outbound": true
        },
        "fax": {
          "inbound": true,
          "outbound": true
        }
      },
      "number": "+14155552671",
      "country": "text",
      "monthlyRecurringPrice": {
        "currencyCode": "EUR",
        "amount": 3500000,
        "exponent": -6
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "subscription": {
        "status": "none",
        "subscribedAt": "2025-07-26T10:57:53.841Z",
        "updatedAt": "2025-07-26T10:57:53.841Z",
        "cancelledAt": "2025-07-26T10:57:53.841Z"
      },
      "endpointSubscription": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "correlationId": "123e4567-e89b-12d3-a456-426614174000",
        "status": "none",
        "subscribedAt": "2025-07-26T10:57:53.841Z",
        "updatedAt": "2025-07-26T10:57:53.841Z",
        "canceledAt": "2025-07-26T10:57:53.841Z",
        "startAt": "2025-07-26T10:57:53.841Z",
        "endAt": "2025-07-26T10:57:53.841Z"
      },
      "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": "2025-07-26T10:57:53.841Z",
      "updatedAt": "2025-07-26T10:57:53.841Z",
      "activatedAt": "2025-07-26T10:57:53.841Z",
      "deactivatedAt": "2025-07-26T10:57:53.841Z",
      "deactivatesAt": "2025-07-26T10:57:53.841Z",
      "requirements": [
        {
          "requirement": {
            "name": "text",
            "type": "kycForm",
            "scope": "number-activation",
            "selector": {
              "scope": "text",
              "numberType": "local",
              "countryCode": "US"
            }
          },
          "status": "ok",
          "reference": "text",
          "notOkSince": "2025-07-26T10:57:53.841Z"
        }
      ],
      "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",
        "createdAt": "2025-07-26T10:57:53.841Z",
        "updatedAt": "2025-07-26T10:57:53.841Z"
      },
      "whatsApp": {
        "whatsAppId": "text",
        "status": "verified",
        "stage": "text",
        "attempt": 1,
        "nextAttemptAt": "2025-07-26T10:57:53.841Z",
        "verificationExpiresAt": "2025-07-26T10:57:53.841Z",
        "requestedCodeAt": "2025-07-26T10:57:53.841Z",
        "createdAt": "2025-07-26T10:57:53.841Z",
        "updatedAt": "2025-07-26T10:57:53.841Z"
      }
    }
  ],
  "nextPageToken": "text"
}

Last updated

Was this helpful?