No-code docs

Alphanumeric Senders

Overview

Alphanumeric originators are combinations of letters (alphabets) and numbers (digits) for sending SMS messages to mobile phones. Alphanumerics work one way and are the most common form of originator worldwide except for the USA and Canada.

Alphanumeric originators do not have a country of origin and have to be registered in destination countries individually. Some countries may require additional registration processes to ensure the alphanumeric sender ID meets local compliance requirements.

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 Alphanumeric Senders

In order to retrieve all alpha numbers available in your workspace you can use this request.

List Workspace Alpha Numbers

get

List alpha numbers for the given workspace. This endpoint supports pagination. To learn more about pagination, refer to API Access Common Usage Page.

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
Responses
200

OK

application/json
Responseall of
get
GET /workspaces/{workspaceId}/numbers-alpha HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "nextPageToken": "text",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "endpointId": "123e4567-e89b-12d3-a456-426614174000",
      "alphaString": "+05060",
      "createdAt": "2025-09-04T10:19:58.597Z",
      "updatedAt": "2025-09-04T10:19:58.597Z",
      "order": {
        "countryCodes": [
          "US"
        ],
        "status": "draft",
        "createdAt": "2025-09-04T10:19:58.597Z",
        "updatedAt": "2025-09-04T10:19:58.597Z"
      },
      "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-09-04T10:19:58.597Z",
        "updatedAt": "2025-09-04T10:19:58.597Z"
      }
    }
  ]
}

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-alpha/" \
     -H 'Authorization: AccessKey <your-access-key>'

Get an Alphanumeric Sender

In order to retrieve an alpha number available in your workspace you can use this request.

Get Workspace Alpha Number

get

Get a specific alpha number for a given workspace by id.

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
alphaNumberIdstringRequired
Responses
200

OK

application/json
Responseall of
get
GET /workspaces/{workspaceId}/numbers-alpha/{alphaNumberId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "endpointId": "123e4567-e89b-12d3-a456-426614174000",
  "alphaString": "+05060",
  "createdAt": "2025-09-04T10:19:58.597Z",
  "updatedAt": "2025-09-04T10:19:58.597Z",
  "order": {
    "countryCodes": [
      "US"
    ],
    "status": "draft",
    "createdAt": "2025-09-04T10:19:58.597Z",
    "updatedAt": "2025-09-04T10:19:58.597Z"
  },
  "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-09-04T10:19:58.597Z",
    "updatedAt": "2025-09-04T10:19:58.597Z"
  }
}
curl "https://api.bird.com/workspaces/{workpaceId}/numbers-alpha/{alphaNumberID}" \
     -H 'Authorization: AccessKey <your-access-key>'

Add country destination to an Alphanumeric Sender

Activate Workspace Endpoint Destinations

post
Authorizations
Path parameters
endpointIdstringRequired

Your endpoint ID. In some cases (e.g. Long Code Numbers) this value is equal to the number ID.

workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
Query parameters
validatebooleanOptional

When set, only validates the request payload without mutating any data.

Body
capabilitystring · enumRequiredPossible values:
countryCodesstring · iso3166-1[] · min: 1 · max: 100Required
Responses
200

Validation Response

application/json
post
POST /workspaces/{workspaceId}/endpoints/{endpointId}/destinations/activate HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 46

{
  "capability": "voice",
  "countryCodes": [
    "text"
  ]
}
{
  "subscriptionPrices": {
    "ANY_ADDITIONAL_PROPERTY": {
      "currencyCode": "EUR",
      "amount": 3500000,
      "exponent": -6
    }
  },
  "error": {
    "code": "text",
    "message": "service.",
    "details": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Cancel country destination from an Alphanumeric Sender

Cancel Workspace Endpoint Subscription

post

Use this endpoint to deactivate a subscription. That will stop charges and messages from being sent.

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
endpointIdstringRequired

Your endpoint ID. In some cases (e.g. Long Code Numbers) this value is equal to the number ID.

subscriptionNamestringRequired

Your number subscription name. For long code numbers, the subscription name is 'main'. For short code and alpha numbers, the subscription name is the same as the country code of the destination which you want to subscribe to.

Example: main
Responses
200

OK

application/json
post
POST /workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/cancel HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "status": "active",
  "price": {
    "currencyCode": "EUR",
    "amount": 3500000,
    "exponent": -6
  },
  "subscription": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "correlationId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "none",
    "subscribedAt": "2025-09-04T10:19:58.597Z",
    "updatedAt": "2025-09-04T10:19:58.597Z",
    "canceledAt": "2025-09-04T10:19:58.597Z",
    "startAt": "2025-09-04T10:19:58.597Z",
    "endAt": "2025-09-04T10:19:58.597Z"
  }
}

Remove country destination from an Alphanumeric Sender

Deactivate Workspace Endpoint Destinations

post
Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
endpointIdstringRequired

Your endpoint ID. In some cases (e.g. Long Code Numbers) this value is equal to the number ID.

Body
capabilitystring · enumRequiredPossible values:
countryCodesstring · iso3166-1[] · min: 1 · max: 25Required
Responses
200

OK

application/json
post
POST /workspaces/{workspaceId}/endpoints/{endpointId}/destinations/deactivate HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 46

{
  "capability": "voice",
  "countryCodes": [
    "text"
  ]
}
{
  "results": [
    {
      "name": "text",
      "countryCode": "US",
      "immutable": true,
      "capabilities": [
        {
          "name": "voice",
          "status": "active",
          "issues": [
            "subscription-is-not-active"
          ]
        }
      ],
      "isBlockedForCapability": {
        "voice": true,
        "sms": false
      }
    }
  ]
}

Last updated

Was this helpful?