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.

Originator Restrictions

• If you use a company or brand name as the originator, the number of characters needs to be between 3 and 11.

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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

Query parameters

limitinteger · max: 100Optional

Limits the number of results to return.

Default: 25

pageTokenstringOptional

The cursor that keeps track of the current position in the results.

reversebooleanOptional

Reverses the order in which the results are returned.

Default: false

Responses

200

OK

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.

404

The requested resource was not found.

application/json

get/workspaces/{workspaceId}/numbers-alpha

HTTPcURLJavaScriptPython

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": "2026-08-10T21:49:25.597Z",
      "updatedAt": "2026-08-10T21:49:25.597Z",
      "order": {
        "countryCodes": [
          "US"
        ],
        "status": "draft",
        "createdAt": "2026-08-10T21:49:25.597Z",
        "updatedAt": "2026-08-10T21:49:25.597Z"
      },
      "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",
        "whatsApp": {
          "whatsAppId": "text",
          "status": "verified",
          "stage": "text",
          "attempt": 1,
          "nextAttemptAt": "2026-08-10T21:49:25.597Z",
          "verificationExpiresAt": "2026-08-10T21:49:25.597Z",
          "requestedCodeAt": "2026-08-10T21:49:25.597Z",
          "createdAt": "2026-08-10T21:49:25.597Z",
          "updatedAt": "2026-08-10T21:49:25.597Z"
        },
        "createdAt": "2026-08-10T21:49:25.597Z",
        "updatedAt": "2026-08-10T21:49:25.597Z"
      }
    }
  ]
}

Request

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

Response

{
    "results": [
        {
            "id": "uuid",
            "alphaString": "string",
            "endpointId": "uuid",
            "createdAt": "2023-10-20T11:49:47.436-03:00",
            "updatedAt": "2023-10-20T11:49:47.479-03:00",
            "endpoint": {
                "id": "uuid",
                "type": "alpha-number",
                "instanceId": "uuid",
                "name": "string",
                "createdAt": "2023-10-20T11:49:47.436-03:00",
                "updatedAt": "2023-10-20T11:49:47.436-03:00",
                "capabilities": [
                    {
                        "name": "sms",
                        "inbound": null,
                        "outbound": {
                            "status": "active"
                        }
                    }
                ]
            }
        },
        {
            "id": "uuid",
            "alphaString": "string",
            "endpointId": "uuid",
            "createdAt": "2023-10-20T11:49:47.392-03:00",
            "updatedAt": "2023-10-20T11:49:47.392-03:00",
            "endpoint": {
                "id": "uuid",
                "type": "alpha-number",
                "instanceId": "uuid",
                "name": "string",
                "createdAt": "2023-10-20T11:49:47.392-03:00",
                "updatedAt": "2023-10-20T11:49:47.392-03:00",
                "capabilities": [
                    {
                        "name": "sms",
                        "inbound": null,
                        "outbound": {
                            "status": "active"
                        }
                    }
                ]
            }
        }
    ]
}

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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

alphaNumberIdstringRequired

Responses

200

OK

application/json

A representation of an alpha number. It contains details such as the endpoint it is associated with and more.

idstring · uuidRequired

The unique identifier of the alpha number.

endpointIdstring · uuidRequired

The unique identifier of the endpoint that the alpha number is associated with.

alphaStringstringRequired

The alpha string of the alpha number. This is usually the phone number in string format following the international format.

Example: +05060

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

404

The requested resource was not found.

application/json

get/workspaces/{workspaceId}/numbers-alpha/{alphaNumberId}

HTTPcURLJavaScriptPython

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": "2026-08-10T21:49:25.597Z",
  "updatedAt": "2026-08-10T21:49:25.597Z",
  "order": {
    "countryCodes": [
      "US"
    ],
    "status": "draft",
    "createdAt": "2026-08-10T21:49:25.597Z",
    "updatedAt": "2026-08-10T21:49:25.597Z"
  },
  "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",
    "whatsApp": {
      "whatsAppId": "text",
      "status": "verified",
      "stage": "text",
      "attempt": 1,
      "nextAttemptAt": "2026-08-10T21:49:25.597Z",
      "verificationExpiresAt": "2026-08-10T21:49:25.597Z",
      "requestedCodeAt": "2026-08-10T21:49:25.597Z",
      "createdAt": "2026-08-10T21:49:25.597Z",
      "updatedAt": "2026-08-10T21:49:25.597Z"
    },
    "createdAt": "2026-08-10T21:49:25.597Z",
    "updatedAt": "2026-08-10T21:49:25.597Z"
  }
}

Resquest

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

Response

{
    "id": "uuid",
    "alphaString": "string",
    "endpointId": "uuid",
    "createdAt": "2023-10-20T11:49:47.436-03:00",
    "updatedAt": "2023-10-20T11:49:47.479-03:00",
    "endpoint": {
        "id": "uuid",
        "type": "alpha-number",
        "instanceId": "uuid",
        "name": "string",
        "createdAt": "2023-10-20T11:49:47.436-03:00",
        "updatedAt": "2023-10-20T11:49:47.436-03:00",
        "capabilities": [
            {
                "name": "sms",
                "inbound": null,
                "outbound": {
                    "status": "active"
                }
            }
        ]
    }
}

Add country destination to an Alphanumeric Sender

Activate Workspace Endpoint Destinations

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

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 unique identifier of the workspace.

Query parameters

validatebooleanOptional

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

Body

application/json

capabilitystring · enumRequiredPossible values:

countryCodesstring · iso3166-1[] · min: 1 · max: 100Required

Responses

200

Validation Response

application/json

201

OK

application/json

400

The request was malformed.

application/json

404

The requested resource was not found.

application/json

post/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/activate

HTTPcURLJavaScriptPython

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",
    "details": {
      "ANY_ADDITIONAL_PROPERTY": [
        "text"
      ]
    },
    "message": "text"
  }
}

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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

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

namestringRequired

The name of the subscription. For long codes, this value will be main. For alpha and short code numbers, this value will be the destination country code.

statusstring · enumRequired

The status of the endpoint subscription. It can be active or inactive.

Possible values:

404

The requested resource was not found.

application/json

post/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/cancel

HTTPcURLJavaScriptPython

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": "2026-08-10T21:49:25.597Z",
    "updatedAt": "2026-08-10T21:49:25.597Z",
    "canceledAt": "2026-08-10T21:49:25.597Z",
    "startAt": "2026-08-10T21:49:25.597Z",
    "endAt": "2026-08-10T21:49:25.597Z"
  }
}

Remove country destination from an Alphanumeric Sender

Deactivate Workspace Endpoint Destinations

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

endpointIdstringRequired

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

Body

application/json

capabilitystring · enumRequiredPossible values:

countryCodesstring · iso3166-1[] · min: 1 · max: 25Required

Responses

200

OK

application/json

400

The request was malformed.

application/json

404

The requested resource was not found.

application/json

post/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/deactivate

HTTPcURLJavaScriptPython

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
      }
    }
  ]
}