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

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

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.

404

Not found

application/json

get

/workspaces/{workspaceId}/numbers-alpha

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-03-27T18:00:28.426Z",
      "updatedAt": "2026-03-27T18:00:28.426Z",
      "order": {
        "countryCodes": [
          "US"
        ],
        "status": "draft",
        "createdAt": "2026-03-27T18:00:28.426Z",
        "updatedAt": "2026-03-27T18:00:28.426Z"
      },
      "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-27T18:00:28.426Z",
          "verificationExpiresAt": "2026-03-27T18:00:28.426Z",
          "requestedCodeAt": "2026-03-27T18:00:28.426Z",
          "createdAt": "2026-03-27T18:00:28.426Z",
          "updatedAt": "2026-03-27T18:00:28.426Z"
        },
        "createdAt": "2026-03-27T18:00:28.426Z",
        "updatedAt": "2026-03-27T18:00:28.426Z"
      }
    }
  ]
}

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

{
    "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

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

alphaNumberIdstringRequired

Responses

200

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

Not found

application/json

get

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

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-03-27T18:00:28.426Z",
  "updatedAt": "2026-03-27T18:00:28.426Z",
  "order": {
    "countryCodes": [
      "US"
    ],
    "status": "draft",
    "createdAt": "2026-03-27T18:00:28.426Z",
    "updatedAt": "2026-03-27T18:00:28.426Z"
  },
  "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-27T18:00:28.426Z",
      "verificationExpiresAt": "2026-03-27T18:00:28.426Z",
      "requestedCodeAt": "2026-03-27T18:00:28.426Z",
      "createdAt": "2026-03-27T18:00:28.426Z",
      "updatedAt": "2026-03-27T18:00:28.426Z"
    },
    "createdAt": "2026-03-27T18:00:28.426Z",
    "updatedAt": "2026-03-27T18:00:28.426Z"
  }
}

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

{
    "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

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

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

201

application/json

400

Error

application/json

404

Not Found

application/json

post

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

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

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

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

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

Not Found

application/json

post

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

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-03-27T18:00:28.426Z",
    "updatedAt": "2026-03-27T18:00:28.426Z",
    "canceledAt": "2026-03-27T18:00:28.426Z",
    "startAt": "2026-03-27T18:00:28.426Z",
    "endAt": "2026-03-27T18:00:28.426Z"
  }
}

Remove country destination from an Alphanumeric Sender

Deactivate Workspace Endpoint Destinations

post

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

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

application/json

400

Error

application/json

404

Not Found

application/json

post

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

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 6 months ago

Was this helpful?

hashtagOverview

hashtagAPI Access

hashtagList Alphanumeric Senders

hashtagList Workspace Alpha Numbers

hashtagGet an Alphanumeric Sender

hashtagGet Workspace Alpha Number

hashtagAdd country destination to an Alphanumeric Sender

hashtagActivate Workspace Endpoint Destinations

hashtagCancel country destination from an Alphanumeric Sender

hashtagCancel Workspace Endpoint Subscription

hashtagRemove country destination from an Alphanumeric Sender

hashtagDeactivate Workspace Endpoint Destinations

Overview

API Access

List Alphanumeric Senders

List Workspace Alpha Numbers

Get an Alphanumeric Sender

Get Workspace Alpha Number

Add country destination to an Alphanumeric Sender

Activate Workspace Endpoint Destinations

Cancel country destination from an Alphanumeric Sender

Cancel Workspace Endpoint Subscription

Remove country destination from an Alphanumeric Sender

Deactivate Workspace Endpoint Destinations