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.

Paramètres de requête

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.

Corps de la réponse

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

obligatoire

Afficher les attributs enfants

results.id

string

obligatoire

The unique identifier of the alpha number.

results.endpointId

string

obligatoire

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

results.alphaString

string

obligatoire

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

results.createdAt

string

obligatoire

results.updatedAt

string

obligatoire

results.order

object

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

Afficher les attributs enfants

results.order.countryCodes

array of string

obligatoire

results.order.status

string

The status of an alpha number order.

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

results.order.createdAt

string

obligatoire

results.order.updatedAt

string

obligatoire

results.endpoint

object

obligatoire

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

Afficher les attributs enfants

results.endpoint.id

string

obligatoire

The ID of the endpoint.

results.endpoint.type

string

obligatoire

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

obligatoire

The unique identifier of the instance.

results.endpoint.name

string

obligatoire

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

results.endpoint.capabilities

array of object

obligatoire

Afficher les attributs enfants

results.endpoint.capabilities.name

string

obligatoire

Possible values: sms

results.endpoint.capabilities.inbound

object

Afficher les attributs enfants

results.endpoint.capabilities.inbound.status

string

obligatoire

Possible values: active, inactive, available, unavailable

results.endpoint.capabilities.inbound.issues

array of string

results.endpoint.capabilities.outbound

object

Afficher les attributs enfants

results.endpoint.capabilities.outbound.status

string

obligatoire

Possible values: active, inactive, available, unavailable

results.endpoint.capabilities.outbound.destinationStatuses

object

Afficher les attributs enfants

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.

Afficher les attributs enfants

results.endpoint.dependencies.type

string

Possible values: connector

results.endpoint.dependencies.connectorId

string

obligatoire

results.endpoint.dependencies.connectorTemplateRef

string

obligatoire

results.endpoint.dependencies.capabilities

array of string

results.endpoint.issues

array of string

results.endpoint.provisioningStatus

string

obligatoire

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.

Afficher les attributs enfants

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

obligatoire

results.endpoint.updatedAt

string

obligatoire

Exemple de code

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

Exemple de code

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

Exemple de code

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

Corps de la réponse

string

obligatoire

The unique identifier of the alpha number.

endpointId

string

obligatoire

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

alphaString

string

obligatoire

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

createdAt

string

obligatoire

updatedAt

string

obligatoire

order

object

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

Afficher les attributs enfants

order.countryCodes

array of string

obligatoire

order.status

string

The status of an alpha number order.

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

order.createdAt

string

obligatoire

order.updatedAt

string

obligatoire

endpoint

object

obligatoire

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

Afficher les attributs enfants

endpoint.id

string

obligatoire

The ID of the endpoint.

endpoint.type

string

obligatoire

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

obligatoire

The unique identifier of the instance.

endpoint.name

string

obligatoire

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

endpoint.capabilities

array of object

obligatoire

Afficher les attributs enfants

endpoint.capabilities.name

string

obligatoire

Possible values: sms

endpoint.capabilities.inbound

object

Afficher les attributs enfants

endpoint.capabilities.inbound.status

string

obligatoire

Possible values: active, inactive, available, unavailable

endpoint.capabilities.inbound.issues

array of string

endpoint.capabilities.outbound

object

Afficher les attributs enfants

endpoint.capabilities.outbound.status

string

obligatoire

Possible values: active, inactive, available, unavailable

endpoint.capabilities.outbound.destinationStatuses

object

Afficher les attributs enfants

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.

Afficher les attributs enfants

endpoint.dependencies.type

string

Possible values: connector

endpoint.dependencies.connectorId

string

obligatoire

endpoint.dependencies.connectorTemplateRef

string

obligatoire

endpoint.dependencies.capabilities

array of string

endpoint.issues

array of string

endpoint.provisioningStatus

string

obligatoire

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.

Afficher les attributs enfants

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

obligatoire

endpoint.updatedAt

string

obligatoire

Exemple de code

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

Exemple de code

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

Exemple de code

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

Paramètres de chemin

workspaceId

string

The unique identifier of the workspace.

Paramètres de requête

validate

boolean

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

Corps de la requête

capability

string

obligatoire

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

countryCodes

array of string

obligatoire

Corps de la réponse

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.

Afficher les attributs enfants

error.code

string

obligatoire

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

obligatoire

A human-readable message that describes the error.

Exemple de code

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.

Corps de la réponse

name

string

obligatoire

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

obligatoire

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.

Afficher les attributs enfants

price.currencyCode

string

obligatoire

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

obligatoire

price.exponent

integer

obligatoire

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

subscription

object

Afficher les attributs enfants

subscription.id

string

obligatoire

The subscription unique identifier.

subscription.correlationId

string

obligatoire

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

subscription.status

string

obligatoire

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.

Exemple de code

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

Corps de la requête

capability

string

obligatoire

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

countryCodes

array of string

obligatoire

Corps de la réponse

results

array of object

obligatoire

Afficher les attributs enfants

results.name

string

obligatoire

results.countryCode

string

obligatoire

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

results.immutable

boolean

results.capabilities

array of object

Afficher les attributs enfants

results.capabilities.name

string

obligatoire

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

results.capabilities.status

string

obligatoire

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.

Afficher les attributs enfants

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

Exemple de code

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