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.

Abfrageparameter

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.

Antwort-Payload

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

erforderlich

Untergeordnete Attribute anzeigen

results.id

string

erforderlich

The unique identifier of the alpha number.

results.endpointId

string

erforderlich

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

results.alphaString

string

erforderlich

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

results.createdAt

string

erforderlich

results.updatedAt

string

erforderlich

results.order

object

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

Untergeordnete Attribute anzeigen

results.order.countryCodes

array of string

erforderlich

results.order.status

string

The status of an alpha number order.

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

results.order.createdAt

string

erforderlich

results.order.updatedAt

string

erforderlich

results.endpoint

object

erforderlich

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

Untergeordnete Attribute anzeigen

results.endpoint.id

string

erforderlich

The ID of the endpoint.

results.endpoint.type

string

erforderlich

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

erforderlich

The unique identifier of the instance.

results.endpoint.name

string

erforderlich

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

results.endpoint.capabilities

array of object

erforderlich

Untergeordnete Attribute anzeigen

results.endpoint.capabilities.name

string

erforderlich

Possible values: sms

results.endpoint.capabilities.inbound

object

Untergeordnete Attribute anzeigen

results.endpoint.capabilities.inbound.status

string

erforderlich

Possible values: active, inactive, available, unavailable

results.endpoint.capabilities.inbound.issues

array of string

results.endpoint.capabilities.outbound

object

Untergeordnete Attribute anzeigen

results.endpoint.capabilities.outbound.status

string

erforderlich

Possible values: active, inactive, available, unavailable

results.endpoint.capabilities.outbound.destinationStatuses

object

Untergeordnete Attribute anzeigen

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.

Untergeordnete Attribute anzeigen

results.endpoint.dependencies.type

string

Possible values: connector

results.endpoint.dependencies.connectorId

string

erforderlich

results.endpoint.dependencies.connectorTemplateRef

string

erforderlich

results.endpoint.dependencies.capabilities

array of string

results.endpoint.issues

array of string

results.endpoint.provisioningStatus

string

erforderlich

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.

Untergeordnete Attribute anzeigen

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

erforderlich

results.endpoint.updatedAt

string

erforderlich

Codebeispiel

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

Codebeispiel

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

Codebeispiel

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

Antwort-Payload

string

erforderlich

The unique identifier of the alpha number.

endpointId

string

erforderlich

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

alphaString

string

erforderlich

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

createdAt

string

erforderlich

updatedAt

string

erforderlich

order

object

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

Untergeordnete Attribute anzeigen

order.countryCodes

array of string

erforderlich

order.status

string

The status of an alpha number order.

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

order.createdAt

string

erforderlich

order.updatedAt

string

erforderlich

endpoint

object

erforderlich

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

Untergeordnete Attribute anzeigen

endpoint.id

string

erforderlich

The ID of the endpoint.

endpoint.type

string

erforderlich

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

erforderlich

The unique identifier of the instance.

endpoint.name

string

erforderlich

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

endpoint.capabilities

array of object

erforderlich

Untergeordnete Attribute anzeigen

endpoint.capabilities.name

string

erforderlich

Possible values: sms

endpoint.capabilities.inbound

object

Untergeordnete Attribute anzeigen

endpoint.capabilities.inbound.status

string

erforderlich

Possible values: active, inactive, available, unavailable

endpoint.capabilities.inbound.issues

array of string

endpoint.capabilities.outbound

object

Untergeordnete Attribute anzeigen

endpoint.capabilities.outbound.status

string

erforderlich

Possible values: active, inactive, available, unavailable

endpoint.capabilities.outbound.destinationStatuses

object

Untergeordnete Attribute anzeigen

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.

Untergeordnete Attribute anzeigen

endpoint.dependencies.type

string

Possible values: connector

endpoint.dependencies.connectorId

string

erforderlich

endpoint.dependencies.connectorTemplateRef

string

erforderlich

endpoint.dependencies.capabilities

array of string

endpoint.issues

array of string

endpoint.provisioningStatus

string

erforderlich

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.

Untergeordnete Attribute anzeigen

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

erforderlich

endpoint.updatedAt

string

erforderlich

Codebeispiel

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

Codebeispiel

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

Codebeispiel

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

Pfadparameter

workspaceId

string

The unique identifier of the workspace.

Abfrageparameter

validate

boolean

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

Anfrage-Payload

capability

string

erforderlich

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

countryCodes

array of string

erforderlich

Antwort-Payload

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.

Untergeordnete Attribute anzeigen

error.code

string

erforderlich

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

erforderlich

A human-readable message that describes the error.

Codebeispiel

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.

Antwort-Payload

name

string

erforderlich

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

erforderlich

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.

Untergeordnete Attribute anzeigen

price.currencyCode

string

erforderlich

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

erforderlich

price.exponent

integer

erforderlich

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

subscription

object

Untergeordnete Attribute anzeigen

subscription.id

string

erforderlich

The subscription unique identifier.

subscription.correlationId

string

erforderlich

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

subscription.status

string

erforderlich

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.

Codebeispiel

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

Anfrage-Payload

capability

string

erforderlich

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

countryCodes

array of string

erforderlich

Antwort-Payload

results

array of object

erforderlich

Untergeordnete Attribute anzeigen

results.name

string

erforderlich

results.countryCode

string

erforderlich

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

results.immutable

boolean

results.capabilities

array of object

Untergeordnete Attribute anzeigen

results.capabilities.name

string

erforderlich

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

results.capabilities.status

string

erforderlich

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.

Untergeordnete Attribute anzeigen

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

Codebeispiel

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