# Alphanumeric Senders

## Overview <a href="#summary" id="summary"></a>

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  <a href="#api-access" id="api-access"></a>

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](https://docs.messagebird.com/api/api-access).

## List Alphanumeric Senders <a href="#list-alphanumbers" id="list-alphanumbers"></a>

In order to retrieve all alpha numbers available in your workspace you can use this request.

## List Workspace Alpha Numbers

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

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage alpha numbers.","name":"alpha_numbers"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"parameters":{"pagination.param.limit":{"description":"Limits the number of results to return.","in":"query","name":"limit","schema":{"default":25,"maximum":100,"type":"integer"}},"pagination.param.pageToken":{"description":"The cursor that keeps track of the current position in the results.","in":"query","name":"pageToken","schema":{"type":"string"}},"pagination.param.reverse":{"description":"Reverses the order in which the results are returned.","in":"query","name":"reverse","schema":{"default":false,"type":"boolean"}}},"schemas":{"pagination":{"properties":{"nextPageToken":{"description":"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.","type":"string"}},"type":"object"},"WorkspaceAlphaNumber":{"type":"object","allOf":[{"$ref":"#/components/schemas/AlphaNumberFragment"},{"type":"object","required":["endpoint"],"properties":{"endpoint":{"$ref":"#/components/schemas/EndpointFragment"}}}]},"AlphaNumberFragment":{"type":"object","description":"A representation of an alpha number. It contains details such as the endpoint it is associated with and more.","required":["id","endpointId","alphaString","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the alpha number."},"endpointId":{"type":"string","format":"uuid","description":"The unique identifier of the endpoint that the alpha number is associated with."},"alphaString":{"type":"string","description":"The alpha string of the alpha number. This is usually the phone number in string format following the international format."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"order":{"$ref":"#/components/schemas/AlphaNumberOrder"}}},"AlphaNumberOrder":{"type":"object","description":"An alpha number order. It contains the country codes for which the alpha number is ordered, the order status and more.","required":["countryCodes","createdAt","updatedAt"],"properties":{"countryCodes":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/NumbersCountryCode"}},"status":{"$ref":"#/components/schemas/AlphaNumberOrderStatus"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"AlphaNumberOrderStatus":{"type":"string","description":"The status of an alpha number order.","enum":["draft","submitted","processing","fulfilled","rejected","cancelled"]},"EndpointFragment":{"type":"object","description":"A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.","required":["id","type","instanceId","name","capabilities","provisioningStatus","createdAt","updatedAt"],"properties":{"id":{"$ref":"#/components/schemas/EndpointId"},"type":{"$ref":"#/components/schemas/EndpointType"},"instanceId":{"$ref":"#/components/schemas/InstanceId"},"name":{"$ref":"#/components/schemas/EndpointName"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapability"}},"dependencies":{"type":"array","description":"The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.","items":{"$ref":"#/components/schemas/EndpointDependency"}},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}},"provisioningStatus":{"$ref":"#/components/schemas/EndpointProvisioningStatus"},"whatsApp":{"description":"WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.","nullable":true,"$ref":"#/components/schemas/WorkspaceWhatsAppNumber"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EndpointId":{"type":"string","format":"uuid","description":"The ID of the endpoint."},"EndpointType":{"type":"string","description":"The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.","enum":["long-code-number","short-code-number","alpha-number","ip-pool","rcs-google-agent"]},"InstanceId":{"type":"string","format":"uuid","description":"The unique identifier of the instance."},"EndpointName":{"type":"string","description":"The name of the endpoint. For some cases it will be the number in international format as string."},"EndpointCapability":{"type":"object","description":"The capability of the endpoint. It shows what capabilities the endpoint supports and which direction (inbound, which means receiving messages, and outbound, which means sending messages). Also, it shows the status for that capability/direction combination.","discriminator":{"propertyName":"name","mapping":{"sms":"#/components/schemas/EndpointCapabilitySMS","mms":"#/components/schemas/EndpointCapabilityMMS","voice":"#/components/schemas/EndpointCapabilityVoice","whatsapp":"#/components/schemas/EndpointCapabilityWhatsapp","email":"#/components/schemas/EndpointCapabilityEmail","rcs-google":"#/components/schemas/EndpointCapabilityRcsGoogle"}},"oneOf":[{"$ref":"#/components/schemas/EndpointCapabilitySMS"},{"$ref":"#/components/schemas/EndpointCapabilityMMS"},{"$ref":"#/components/schemas/EndpointCapabilityVoice"},{"$ref":"#/components/schemas/EndpointCapabilityWhatsapp"},{"$ref":"#/components/schemas/EndpointCapabilityEmail"},{"$ref":"#/components/schemas/EndpointCapabilityRcsGoogle"}]},"EndpointCapabilitySMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["sms"]}}}]},"EndpointCapabilityFields":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/EndpointCapabilityName"},"inbound":{"$ref":"#/components/schemas/InboundEndpointCapability"},"outbound":{"$ref":"#/components/schemas/OutboundEndpointCapability"}}},"EndpointCapabilityName":{"type":"string","enum":["voice","sms","mms","whatsapp","email","rcs-google"]},"InboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityStatus":{"type":"string","enum":["active","inactive","available","unavailable"]},"EndpointIssue":{"type":"string","description":"The issue of the endpoint. It indicates what's wrong with the endpoint and the reason why traffic is deactivated in that case.","enum":["subscription-is-not-active","setup-fee-is-not-paid","capability-is-not-supported","compliance-requirement-not-satisfied","brand-not-ready","destination-brand-not-ready","use-case-not-ready","kyc-form-grace-period-has-ended","whatsapp-not-pre-verified"]},"OutboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"destinationStatuses":{"type":"object","properties":{"active":{"type":"number"},"inactive":{"type":"number"},"available":{"type":"number"},"unavailable":{"type":"number"}}},"supportsDestinations":{"type":"boolean","description":"Whether the number supports destinations"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityMMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["mms"]}}}]},"EndpointCapabilityVoice":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["voice"]},"useCaseType":{"$ref":"#/components/schemas/EndpointVoiceUseCaseType"}}}]},"EndpointVoiceUseCaseType":{"type":"string","enum":["contact-centre"]},"EndpointCapabilityWhatsapp":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["whatsapp"]}}}]},"EndpointCapabilityEmail":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["email"]}}}]},"EndpointCapabilityRcsGoogle":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["rcs-google"]}}}]},"EndpointDependency":{"type":"object","discriminator":{"propertyName":"type","mapping":{"connector":"#/components/schemas/EndpointDependencyConnector"}},"oneOf":[{"$ref":"#/components/schemas/EndpointDependencyConnector"}]},"EndpointDependencyConnector":{"type":"object","required":["connectorId","connectorTemplateRef"],"properties":{"type":{"type":"string","enum":["connector"]},"connectorId":{"type":"string","format":"uuid"},"connectorTemplateRef":{"type":"string"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapabilityName"}}}},"EndpointProvisioningStatus":{"type":"string","enum":["provisioned","provisioning","deprovisioned","deprovisioning"]},"WorkspaceWhatsAppNumber":{"type":"object","description":"WhatsApp number pre-verification details.","properties":{"whatsAppId":{"type":"string"},"status":{"$ref":"#/components/schemas/WhatsAppNumberStatus"},"stage":{"type":"string"},"attempt":{"type":"integer"},"nextAttemptAt":{"type":"string","format":"date-time"},"verificationExpiresAt":{"type":"string","format":"date-time","nullable":true},"requestedCodeAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WhatsAppNumberStatus":{"type":"string","description":"WhatsApp number status","enum":["unknown","already-exists","installed","verified","not-verified","expired"]},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/numbers-alpha":{"get":{"operationId":"listWorkspaceAlphaNumbers","description":"List alpha numbers for the given workspace. This endpoint supports pagination. To learn more about pagination, refer to API Access Common Usage Page.","parameters":[{"$ref":"#/components/parameters/pagination.param.limit"},{"$ref":"#/components/parameters/pagination.param.pageToken"},{"$ref":"#/components/parameters/pagination.param.reverse"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/pagination"},{"properties":{"results":{"items":{"$ref":"#/components/schemas/WorkspaceAlphaNumber"},"type":"array"}},"required":["results"],"type":"object"}]}}},"description":"OK"},"404":{"$ref":"#/components/responses/error.response.not_found"}},"summary":"List Workspace Alpha Numbers","tags":["alpha_numbers"]}}}}
```

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}

{% tab title="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"
                        }
                    }
                ]
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get an Alphanumeric Sender <a href="#get-an-alphanumber" id="get-an-alphanumber"></a>

In order to retrieve an alpha number available in your workspace you can use this request.

## Get Workspace Alpha Number

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

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage alpha numbers.","name":"alpha_numbers"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"WorkspaceAlphaNumber":{"type":"object","allOf":[{"$ref":"#/components/schemas/AlphaNumberFragment"},{"type":"object","required":["endpoint"],"properties":{"endpoint":{"$ref":"#/components/schemas/EndpointFragment"}}}]},"AlphaNumberFragment":{"type":"object","description":"A representation of an alpha number. It contains details such as the endpoint it is associated with and more.","required":["id","endpointId","alphaString","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the alpha number."},"endpointId":{"type":"string","format":"uuid","description":"The unique identifier of the endpoint that the alpha number is associated with."},"alphaString":{"type":"string","description":"The alpha string of the alpha number. This is usually the phone number in string format following the international format."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"order":{"$ref":"#/components/schemas/AlphaNumberOrder"}}},"AlphaNumberOrder":{"type":"object","description":"An alpha number order. It contains the country codes for which the alpha number is ordered, the order status and more.","required":["countryCodes","createdAt","updatedAt"],"properties":{"countryCodes":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/NumbersCountryCode"}},"status":{"$ref":"#/components/schemas/AlphaNumberOrderStatus"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"AlphaNumberOrderStatus":{"type":"string","description":"The status of an alpha number order.","enum":["draft","submitted","processing","fulfilled","rejected","cancelled"]},"EndpointFragment":{"type":"object","description":"A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.","required":["id","type","instanceId","name","capabilities","provisioningStatus","createdAt","updatedAt"],"properties":{"id":{"$ref":"#/components/schemas/EndpointId"},"type":{"$ref":"#/components/schemas/EndpointType"},"instanceId":{"$ref":"#/components/schemas/InstanceId"},"name":{"$ref":"#/components/schemas/EndpointName"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapability"}},"dependencies":{"type":"array","description":"The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.","items":{"$ref":"#/components/schemas/EndpointDependency"}},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}},"provisioningStatus":{"$ref":"#/components/schemas/EndpointProvisioningStatus"},"whatsApp":{"description":"WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.","nullable":true,"$ref":"#/components/schemas/WorkspaceWhatsAppNumber"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EndpointId":{"type":"string","format":"uuid","description":"The ID of the endpoint."},"EndpointType":{"type":"string","description":"The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.","enum":["long-code-number","short-code-number","alpha-number","ip-pool","rcs-google-agent"]},"InstanceId":{"type":"string","format":"uuid","description":"The unique identifier of the instance."},"EndpointName":{"type":"string","description":"The name of the endpoint. For some cases it will be the number in international format as string."},"EndpointCapability":{"type":"object","description":"The capability of the endpoint. It shows what capabilities the endpoint supports and which direction (inbound, which means receiving messages, and outbound, which means sending messages). Also, it shows the status for that capability/direction combination.","discriminator":{"propertyName":"name","mapping":{"sms":"#/components/schemas/EndpointCapabilitySMS","mms":"#/components/schemas/EndpointCapabilityMMS","voice":"#/components/schemas/EndpointCapabilityVoice","whatsapp":"#/components/schemas/EndpointCapabilityWhatsapp","email":"#/components/schemas/EndpointCapabilityEmail","rcs-google":"#/components/schemas/EndpointCapabilityRcsGoogle"}},"oneOf":[{"$ref":"#/components/schemas/EndpointCapabilitySMS"},{"$ref":"#/components/schemas/EndpointCapabilityMMS"},{"$ref":"#/components/schemas/EndpointCapabilityVoice"},{"$ref":"#/components/schemas/EndpointCapabilityWhatsapp"},{"$ref":"#/components/schemas/EndpointCapabilityEmail"},{"$ref":"#/components/schemas/EndpointCapabilityRcsGoogle"}]},"EndpointCapabilitySMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["sms"]}}}]},"EndpointCapabilityFields":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/EndpointCapabilityName"},"inbound":{"$ref":"#/components/schemas/InboundEndpointCapability"},"outbound":{"$ref":"#/components/schemas/OutboundEndpointCapability"}}},"EndpointCapabilityName":{"type":"string","enum":["voice","sms","mms","whatsapp","email","rcs-google"]},"InboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityStatus":{"type":"string","enum":["active","inactive","available","unavailable"]},"EndpointIssue":{"type":"string","description":"The issue of the endpoint. It indicates what's wrong with the endpoint and the reason why traffic is deactivated in that case.","enum":["subscription-is-not-active","setup-fee-is-not-paid","capability-is-not-supported","compliance-requirement-not-satisfied","brand-not-ready","destination-brand-not-ready","use-case-not-ready","kyc-form-grace-period-has-ended","whatsapp-not-pre-verified"]},"OutboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"destinationStatuses":{"type":"object","properties":{"active":{"type":"number"},"inactive":{"type":"number"},"available":{"type":"number"},"unavailable":{"type":"number"}}},"supportsDestinations":{"type":"boolean","description":"Whether the number supports destinations"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityMMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["mms"]}}}]},"EndpointCapabilityVoice":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["voice"]},"useCaseType":{"$ref":"#/components/schemas/EndpointVoiceUseCaseType"}}}]},"EndpointVoiceUseCaseType":{"type":"string","enum":["contact-centre"]},"EndpointCapabilityWhatsapp":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["whatsapp"]}}}]},"EndpointCapabilityEmail":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["email"]}}}]},"EndpointCapabilityRcsGoogle":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["rcs-google"]}}}]},"EndpointDependency":{"type":"object","discriminator":{"propertyName":"type","mapping":{"connector":"#/components/schemas/EndpointDependencyConnector"}},"oneOf":[{"$ref":"#/components/schemas/EndpointDependencyConnector"}]},"EndpointDependencyConnector":{"type":"object","required":["connectorId","connectorTemplateRef"],"properties":{"type":{"type":"string","enum":["connector"]},"connectorId":{"type":"string","format":"uuid"},"connectorTemplateRef":{"type":"string"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapabilityName"}}}},"EndpointProvisioningStatus":{"type":"string","enum":["provisioned","provisioning","deprovisioned","deprovisioning"]},"WorkspaceWhatsAppNumber":{"type":"object","description":"WhatsApp number pre-verification details.","properties":{"whatsAppId":{"type":"string"},"status":{"$ref":"#/components/schemas/WhatsAppNumberStatus"},"stage":{"type":"string"},"attempt":{"type":"integer"},"nextAttemptAt":{"type":"string","format":"date-time"},"verificationExpiresAt":{"type":"string","format":"date-time","nullable":true},"requestedCodeAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WhatsAppNumberStatus":{"type":"string","description":"WhatsApp number status","enum":["unknown","already-exists","installed","verified","not-verified","expired"]},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/numbers-alpha/{alphaNumberId}":{"get":{"operationId":"getWorkspaceAlphaNumber","description":"Get a specific alpha number for a given workspace by id.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceAlphaNumber"}}},"description":"OK"},"404":{"$ref":"#/components/responses/error.response.not_found"}},"summary":"Get Workspace Alpha Number","tags":["alpha_numbers"]}}}}
```

{% tabs %}
{% tab title="Resquest" %}

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

{% endtab %}

{% tab title="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"
                }
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

## Add country destination to an Alphanumeric Sender

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

> Activate Workspace Endpoint Destinations

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage endpoints.","name":"endpoints"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"parameters":{"path.workspaceId":{"description":"The unique identifier of the workspace.","in":"path","name":"workspaceId","required":true,"schema":{"format":"uuid","type":"string"}},"queryValidate":{"description":"When set, only validates the request payload without mutating any data.","in":"query","name":"validate","schema":{"type":"boolean"}}},"schemas":{"ActivateEndpointDestinations":{"type":"object","required":["capability","countryCodes"],"properties":{"capability":{"$ref":"#/components/schemas/EndpointCapabilityName"},"countryCodes":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"iso3166-1"}}}},"EndpointCapabilityName":{"type":"string","enum":["voice","sms","mms","whatsapp","email","rcs-google"]},"ActivateEndpointDestinationsValidationResponse":{"type":"object","properties":{"subscriptionPrices":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Money"}},"error":{"$ref":"#/components/schemas/error.validation"}}},"Money":{"type":"object","title":"Money","additionalProperties":false,"description":"Money combines an amount of money with its currency.","nullable":true,"properties":{"currencyCode":{"$ref":"#/components/schemas/Currency"},"amount":{"$ref":"#/components/schemas/Amount"},"exponent":{"$ref":"#/components/schemas/Exponent"}},"required":["currencyCode","amount","exponent"]},"Currency":{"title":"Currency Code","description":"Currency as ISO 4217 code (three digits). An example would be `EUR` for Euro.","type":"string","enum":["EUR","USD","GBP","AUD","SGD","IDR","INR","MXN"]},"Amount":{"type":"integer","format":"int64"},"Exponent":{"description":"Usually a negative number to specify the exponent for decimal precision. e.g., `1540 * (10^-2) = 15.4`","type":"integer","format":"int32","minimum":-10},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"},"EndpointDestination":{"type":"object","required":["name","countryCode"],"properties":{"name":{"type":"string"},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"immutable":{"type":"boolean"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointDestinationCapability"}},"isBlockedForCapability":{"$ref":"#/components/schemas/IsBlockedForCapability"}}},"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"EndpointDestinationCapability":{"type":"object","required":["name","status"],"properties":{"name":{"$ref":"#/components/schemas/EndpointCapabilityName"},"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityStatus":{"type":"string","enum":["active","inactive","available","unavailable"]},"EndpointIssue":{"type":"string","description":"The issue of the endpoint. It indicates what's wrong with the endpoint and the reason why traffic is deactivated in that case.","enum":["subscription-is-not-active","setup-fee-is-not-paid","capability-is-not-supported","compliance-requirement-not-satisfied","brand-not-ready","destination-brand-not-ready","use-case-not-ready","kyc-form-grace-period-has-ended","whatsapp-not-pre-verified"]},"IsBlockedForCapability":{"type":"object","description":"Indicates whether specific capabilities are blocked for a given number.","properties":{"voice":{"type":"boolean"},"sms":{"type":"boolean"},"mms":{"type":"boolean"},"whatsapp":{"type":"boolean"},"email":{"type":"boolean"},"rcs-google":{"type":"boolean"}},"additionalProperties":false},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.bad_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The request was malformed."},"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/activate":{"post":{"operationId":"activateWorkspaceEndpointDestinations","parameters":[{"$ref":"#/components/parameters/path.workspaceId"},{"$ref":"#/components/parameters/queryValidate"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateEndpointDestinations"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateEndpointDestinationsValidationResponse"}}},"description":"Validation Response"},"201":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"$ref":"#/components/schemas/EndpointDestination"},"type":"array"}},"required":["results"],"type":"object"}}},"description":"OK"},"400":{"$ref":"#/components/responses/error.response.bad_request"},"404":{"$ref":"#/components/responses/error.response.not_found"}},"summary":"Activate Workspace Endpoint Destinations","tags":["endpoints"]}}}}
```

## Cancel country destination from an Alphanumeric Sender

## Cancel Workspace Endpoint Subscription

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

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage endpoints.","name":"endpoints"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"EndpointSubscription":{"type":"object","required":["name","status"],"properties":{"name":{"type":"string","description":"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":{"$ref":"#/components/schemas/EndpointSubscriptionStatus"},"price":{"$ref":"#/components/schemas/Money"},"subscription":{"$ref":"#/components/schemas/EndpointSubscriptionDetails"}}},"EndpointSubscriptionStatus":{"type":"string","description":"The status of the endpoint subscription. It can be active or inactive.","enum":["active","inactive"]},"Money":{"type":"object","title":"Money","additionalProperties":false,"description":"Money combines an amount of money with its currency.","nullable":true,"properties":{"currencyCode":{"$ref":"#/components/schemas/Currency"},"amount":{"$ref":"#/components/schemas/Amount"},"exponent":{"$ref":"#/components/schemas/Exponent"}},"required":["currencyCode","amount","exponent"]},"Currency":{"title":"Currency Code","description":"Currency as ISO 4217 code (three digits). An example would be `EUR` for Euro.","type":"string","enum":["EUR","USD","GBP","AUD","SGD","IDR","INR","MXN"]},"Amount":{"type":"integer","format":"int64"},"Exponent":{"description":"Usually a negative number to specify the exponent for decimal precision. e.g., `1540 * (10^-2) = 15.4`","type":"integer","format":"int32","minimum":-10},"EndpointSubscriptionDetails":{"type":"object","required":["id","correlationId","status"],"properties":{"id":{"type":"string","format":"uuid","description":"The subscription unique identifier."},"correlationId":{"type":"string","format":"uuid","description":"The correlation links the subscription to its number. Hence, the correlationId is the numberId."},"status":{"$ref":"#/components/schemas/AccountingSubscriptionStatus"},"subscribedAt":{"type":"string","format":"date-time","description":"The date and time when the subscription was created."},"updatedAt":{"type":"string","format":"date-time"},"canceledAt":{"type":"string","format":"date-time","description":"The date and time when the subscription was canceled."},"startAt":{"type":"string","format":"date-time","description":"The date and time when the subscription should start."},"endAt":{"type":"string","format":"date-time","description":"The date and time when the subscription should end."}}},"AccountingSubscriptionStatus":{"type":"string","enum":["none","active","inactive","canceling","canceled","planned"],"description":"The status of the accounting subscription. It can be none, active, canceling, canceled, or planned."},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/cancel":{"post":{"operationId":"cancelWorkspaceEndpointSubscription","description":"Use this endpoint to deactivate a subscription. That will stop charges and messages from being sent.\n","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointSubscription"}}},"description":"OK"},"404":{"$ref":"#/components/responses/error.response.not_found"}},"summary":"Cancel Workspace Endpoint Subscription","tags":["endpoints"]}}}}
```

## Remove country destination from an Alphanumeric Sender

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

> Deactivate Workspace Endpoint Destinations

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage endpoints.","name":"endpoints"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"DeactivateEndpointDestinations":{"type":"object","required":["capability","countryCodes"],"properties":{"capability":{"$ref":"#/components/schemas/EndpointCapabilityName"},"countryCodes":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","format":"iso3166-1"}}}},"EndpointCapabilityName":{"type":"string","enum":["voice","sms","mms","whatsapp","email","rcs-google"]},"EndpointDestination":{"type":"object","required":["name","countryCode"],"properties":{"name":{"type":"string"},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"immutable":{"type":"boolean"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointDestinationCapability"}},"isBlockedForCapability":{"$ref":"#/components/schemas/IsBlockedForCapability"}}},"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"EndpointDestinationCapability":{"type":"object","required":["name","status"],"properties":{"name":{"$ref":"#/components/schemas/EndpointCapabilityName"},"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityStatus":{"type":"string","enum":["active","inactive","available","unavailable"]},"EndpointIssue":{"type":"string","description":"The issue of the endpoint. It indicates what's wrong with the endpoint and the reason why traffic is deactivated in that case.","enum":["subscription-is-not-active","setup-fee-is-not-paid","capability-is-not-supported","compliance-requirement-not-satisfied","brand-not-ready","destination-brand-not-ready","use-case-not-ready","kyc-form-grace-period-has-ended","whatsapp-not-pre-verified"]},"IsBlockedForCapability":{"type":"object","description":"Indicates whether specific capabilities are blocked for a given number.","properties":{"voice":{"type":"boolean"},"sms":{"type":"boolean"},"mms":{"type":"boolean"},"whatsapp":{"type":"boolean"},"email":{"type":"boolean"},"rcs-google":{"type":"boolean"}},"additionalProperties":false},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.bad_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The request was malformed."},"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/deactivate":{"post":{"operationId":"deactivateWorkspaceEndpointDestinations","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeactivateEndpointDestinations"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"$ref":"#/components/schemas/EndpointDestination"},"type":"array"}},"required":["results"],"type":"object"}}},"description":"OK"},"400":{"$ref":"#/components/responses/error.response.bad_request"},"404":{"$ref":"#/components/responses/error.response.not_found"}},"summary":"Deactivate Workspace Endpoint Destinations","tags":["endpoints"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/numbers-api/api-reference/alphanumeric-senders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.