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.

GET

/workspaces/{workspaceId}/numbers-alpha

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

Parámetros de consulta

limit

integer

Limits the number of results to return.

pageToken

string

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

reverse

boolean

Reverses the order in which the results are returned.

Cuerpo de la respuesta

nextPageToken

string

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.

results

array of object

obligatorio

Mostrar atributos secundarios

results.id

string

obligatorio

The unique identifier of the alpha number.

results.endpointId

string

obligatorio

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

results.alphaString

string

obligatorio

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

results.createdAt

string

obligatorio

results.updatedAt

string

obligatorio

results.order

object

An alpha number order. It contains the country codes for which the alpha number is ordered, the order status and more.

Mostrar atributos secundarios

results.order.countryCodes

array of string

obligatorio

results.order.status

string

The status of an alpha number order.

Possible values: draft, submitted, processing, fulfilled, rejected, cancelled

results.order.createdAt

string

obligatorio

results.order.updatedAt

string

obligatorio

results.endpoint

object

obligatorio

A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.

Mostrar atributos secundarios

results.endpoint.id

string

obligatorio

The ID of the endpoint.

results.endpoint.type

string

obligatorio

The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.

Possible values: long-code-number, short-code-number, alpha-number, ip-pool, rcs-google-agent

results.endpoint.instanceId

string

obligatorio

The unique identifier of the instance.

results.endpoint.name

string

obligatorio

The name of the endpoint. For some cases it will be the number in international format as string.

results.endpoint.capabilities

array of object

obligatorio

Mostrar atributos secundarios

results.endpoint.capabilities.name

string

obligatorio

Possible values: sms

results.endpoint.capabilities.inbound

object

Mostrar atributos secundarios

results.endpoint.capabilities.inbound.status

string

obligatorio

Possible values: active, inactive, available, unavailable

results.endpoint.capabilities.inbound.issues

array of string

results.endpoint.capabilities.outbound

object

Mostrar atributos secundarios

results.endpoint.capabilities.outbound.status

string

obligatorio

Possible values: active, inactive, available, unavailable

results.endpoint.capabilities.outbound.destinationStatuses

object

Mostrar atributos secundarios

results.endpoint.capabilities.outbound.destinationStatuses.active

number

results.endpoint.capabilities.outbound.destinationStatuses.inactive

number

results.endpoint.capabilities.outbound.destinationStatuses.available

number

results.endpoint.capabilities.outbound.destinationStatuses.unavailable

number

results.endpoint.capabilities.outbound.supportsDestinations

boolean

Whether the number supports destinations

results.endpoint.capabilities.outbound.issues

array of string

results.endpoint.dependencies

array of object

The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.

Mostrar atributos secundarios

results.endpoint.dependencies.type

string

Possible values: connector

results.endpoint.dependencies.connectorId

string

obligatorio

results.endpoint.dependencies.connectorTemplateRef

string

obligatorio

results.endpoint.dependencies.capabilities

array of string

results.endpoint.issues

array of string

results.endpoint.provisioningStatus

string

obligatorio

Possible values: provisioned, provisioning, deprovisioned, deprovisioning

results.endpoint.whatsApp

object

WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.

Mostrar atributos secundarios

results.endpoint.whatsApp.whatsAppId

string

results.endpoint.whatsApp.status

string

WhatsApp number status

Possible values: unknown, already-exists, installed, verified, not-verified, expired

results.endpoint.whatsApp.stage

string

results.endpoint.whatsApp.attempt

integer

results.endpoint.whatsApp.nextAttemptAt

string

results.endpoint.whatsApp.verificationExpiresAt

string

results.endpoint.whatsApp.requestedCodeAt

string

results.endpoint.whatsApp.createdAt

string

results.endpoint.whatsApp.updatedAt

string

results.endpoint.createdAt

string

obligatorio

results.endpoint.updatedAt

string

obligatorio

Ejemplo de código

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/numbers-alpha' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Ejemplo de código

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

Ejemplo de código

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

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

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

Cuerpo de la respuesta

string

obligatorio

The unique identifier of the alpha number.

endpointId

string

obligatorio

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

alphaString

string

obligatorio

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

createdAt

string

obligatorio

updatedAt

string

obligatorio

order

object

An alpha number order. It contains the country codes for which the alpha number is ordered, the order status and more.

Mostrar atributos secundarios

order.countryCodes

array of string

obligatorio

order.status

string

The status of an alpha number order.

Possible values: draft, submitted, processing, fulfilled, rejected, cancelled

order.createdAt

string

obligatorio

order.updatedAt

string

obligatorio

endpoint

object

obligatorio

A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.

Mostrar atributos secundarios

endpoint.id

string

obligatorio

The ID of the endpoint.

endpoint.type

string

obligatorio

The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.

Possible values: long-code-number, short-code-number, alpha-number, ip-pool, rcs-google-agent

endpoint.instanceId

string

obligatorio

The unique identifier of the instance.

endpoint.name

string

obligatorio

The name of the endpoint. For some cases it will be the number in international format as string.

endpoint.capabilities

array of object

obligatorio

Mostrar atributos secundarios

endpoint.capabilities.name

string

obligatorio

Possible values: sms

endpoint.capabilities.inbound

object

Mostrar atributos secundarios

endpoint.capabilities.inbound.status

string

obligatorio

Possible values: active, inactive, available, unavailable

endpoint.capabilities.inbound.issues

array of string

endpoint.capabilities.outbound

object

Mostrar atributos secundarios

endpoint.capabilities.outbound.status

string

obligatorio

Possible values: active, inactive, available, unavailable

endpoint.capabilities.outbound.destinationStatuses

object

Mostrar atributos secundarios

endpoint.capabilities.outbound.destinationStatuses.active

number

endpoint.capabilities.outbound.destinationStatuses.inactive

number

endpoint.capabilities.outbound.destinationStatuses.available

number

endpoint.capabilities.outbound.destinationStatuses.unavailable

number

endpoint.capabilities.outbound.supportsDestinations

boolean

Whether the number supports destinations

endpoint.capabilities.outbound.issues

array of string

endpoint.dependencies

array of object

The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.

Mostrar atributos secundarios

endpoint.dependencies.type

string

Possible values: connector

endpoint.dependencies.connectorId

string

obligatorio

endpoint.dependencies.connectorTemplateRef

string

obligatorio

endpoint.dependencies.capabilities

array of string

endpoint.issues

array of string

endpoint.provisioningStatus

string

obligatorio

Possible values: provisioned, provisioning, deprovisioned, deprovisioning

endpoint.whatsApp

object

WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.

Mostrar atributos secundarios

endpoint.whatsApp.whatsAppId

string

endpoint.whatsApp.status

string

WhatsApp number status

Possible values: unknown, already-exists, installed, verified, not-verified, expired

endpoint.whatsApp.stage

string

endpoint.whatsApp.attempt

integer

endpoint.whatsApp.nextAttemptAt

string

endpoint.whatsApp.verificationExpiresAt

string

endpoint.whatsApp.requestedCodeAt

string

endpoint.whatsApp.createdAt

string

endpoint.whatsApp.updatedAt

string

endpoint.createdAt

string

obligatorio

endpoint.updatedAt

string

obligatorio

Ejemplo de código

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/numbers-alpha/{alphaNumberId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Ejemplo de código

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

Ejemplo de código

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

POST

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

Activate Workspace Endpoint Destinations

Parámetros de ruta

workspaceId

string

The unique identifier of the workspace.

Parámetros de consulta

validate

boolean

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

Cuerpo de la solicitud

capability

string

obligatorio

Possible values: voice, sms, mms, whatsapp, email, rcs-google

countryCodes

array of string

obligatorio

Cuerpo de la respuesta

subscriptionPrices

object

error

object

A validation error returned from the API. The details map keys are JSON paths pointing into the request body / parameters; values are arrays of human-readable messages describing each problem with that path.

Mostrar atributos secundarios

error.code

string

obligatorio

A unique code that identifies the error. This code can be used to programmatically identify the error.

error.details

object

Per-field validation messages keyed by JSON path.

error.message

string

obligatorio

A human-readable message that describes the error.

Ejemplo de código

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/activate' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Cancel country destination from an Alphanumeric Sender

POST

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

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

Cuerpo de la respuesta

name

string

obligatorio

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.

status

string

obligatorio

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

Possible values: active, inactive

price

object

Money combines an amount of money with its currency.

Mostrar atributos secundarios

price.currencyCode

string

obligatorio

Currency as ISO 4217 code (three digits). An example would be EUR for Euro.

Possible values: EUR, USD, GBP, AUD, SGD, IDR, INR, MXN

price.amount

integer

obligatorio

price.exponent

integer

obligatorio

Usually a negative number to specify the exponent for decimal precision. e.g., 1540 * (10^-2) = 15.4

subscription

object

Mostrar atributos secundarios

subscription.id

string

obligatorio

The subscription unique identifier.

subscription.correlationId

string

obligatorio

The correlation links the subscription to its number. Hence, the correlationId is the numberId.

subscription.status

string

obligatorio

The status of the accounting subscription. It can be none, active, canceling, canceled, or planned.

Possible values: none, active, inactive, canceling, canceled, planned

subscription.subscribedAt

string

The date and time when the subscription was created.

subscription.updatedAt

string

subscription.canceledAt

string

The date and time when the subscription was canceled.

subscription.startAt

string

The date and time when the subscription should start.

subscription.endAt

string

The date and time when the subscription should end.

Ejemplo de código

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/cancel' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Remove country destination from an Alphanumeric Sender

POST

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

Deactivate Workspace Endpoint Destinations

Cuerpo de la solicitud

capability

string

obligatorio

Possible values: voice, sms, mms, whatsapp, email, rcs-google

countryCodes

array of string

obligatorio

Cuerpo de la respuesta

results

array of object

obligatorio

Mostrar atributos secundarios

results.name

string

obligatorio

results.countryCode

string

obligatorio

The country code in ISO 3166-1 alpha-2 format.

results.immutable

boolean

results.capabilities

array of object

Mostrar atributos secundarios

results.capabilities.name

string

obligatorio

Possible values: voice, sms, mms, whatsapp, email, rcs-google

results.capabilities.status

string

obligatorio

Possible values: active, inactive, available, unavailable

results.capabilities.issues

array of string

results.isBlockedForCapability

object

Indicates whether specific capabilities are blocked for a given number.

Mostrar atributos secundarios

results.isBlockedForCapability.voice

boolean

results.isBlockedForCapability.sms

boolean

results.isBlockedForCapability.mms

boolean

results.isBlockedForCapability.whatsapp

boolean

results.isBlockedForCapability.email

boolean

results.isBlockedForCapability.rcs-google

boolean

Ejemplo de código

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/deactivate' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'