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/workspaces/{workspaceId}/numbers-alpha

Authorization

useraccessKey

Path parameters

workspaceId*string

Query parameters

Response

200404

OK

Body

application/json

nextPageTokenstring

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

results*array of WorkspaceAlphaNumber (object)

Request

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/numbers-alpha', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

{
  "nextPageToken": "text",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "endpointId": "123e4567-e89b-12d3-a456-426614174000",
      "alphaString": "text",
      "createdAt": "2024-04-29T10:04:35.535Z",
      "updatedAt": "2024-04-29T10:04:35.535Z",
      "order": {
        "countryCodes": [
          "text"
        ],
        "status": "draft",
        "createdAt": "2024-04-29T10:04:35.535Z",
        "updatedAt": "2024-04-29T10:04:35.535Z"
      },
      "endpoint": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "long-code-number",
        "instanceId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "capabilities": [
          {
            "name": "sms",
            "inbound": {
              "status": "active",
              "issues": [
                "subscription-is-not-active"
              ]
            },
            "outbound": {
              "status": "active",
              "destinationStatuses": {
                "active": 0,
                "inactive": 0,
                "available": 0,
                "unavailable": 0
              },
              "supportsDestinations": false,
              "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": "2024-04-29T10:04:35.535Z",
        "updatedAt": "2024-04-29T10:04:35.535Z"
      }
    }
  ]
}

Request

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-alpha/" \
     -H 'Authorization: Bearer <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/workspaces/{workspaceId}/numbers-alpha/{alphaNumberId}

Authorization

useraccessKey

Path parameters

workspaceId*string

alphaNumberId*string

Response

200404

OK

Body

application/json

id*string (uuid)

endpointId*string (uuid)

alphaString*string

createdAt*string (date-time)

updatedAt*string (date-time)

orderAlphaNumberOrder (object)

endpoint*EndpointFragment (object)

Request

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/numbers-alpha/{alphaNumberId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "endpointId": "123e4567-e89b-12d3-a456-426614174000",
  "alphaString": "text",
  "createdAt": "2024-04-29T10:04:35.535Z",
  "updatedAt": "2024-04-29T10:04:35.535Z",
  "order": {
    "countryCodes": [
      "text"
    ],
    "status": "draft",
    "createdAt": "2024-04-29T10:04:35.535Z",
    "updatedAt": "2024-04-29T10:04:35.535Z"
  },
  "endpoint": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "long-code-number",
    "instanceId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "capabilities": [
      {
        "name": "sms",
        "inbound": {
          "status": "active",
          "issues": [
            "subscription-is-not-active"
          ]
        },
        "outbound": {
          "status": "active",
          "destinationStatuses": {
            "active": 0,
            "inactive": 0,
            "available": 0,
            "unavailable": 0
          },
          "supportsDestinations": false,
          "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": "2024-04-29T10:04:35.535Z",
    "updatedAt": "2024-04-29T10:04:35.535Z"
  }
}

Resquest

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-alpha/{alphaNumberID}" \
     -H 'Authorization: Bearer <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"
                }
            }
        ]
    }
}