# Alphanumeric Senders ## Overview Alphanumeric originators are combinations of letters (alphabets) and numbers (digits) for sending SMS messages to mobile phones. Alphanumerics work one way and are the most common form of originator worldwide except for the USA and Canada. Alphanumeric originators do not have a country of origin and have to be registered in destination countries individually. Some countries may require additional registration processes to ensure the alphanumeric sender ID meets local compliance requirements. ## API Access The following API requests can only be made using a valid access key, and attached to an access role, with an access policy that at least specifies the permissions to the resources outlined in each section below. Learn more about [API access](https://docs.messagebird.com/api/api-access). ## List Alphanumeric Senders In order to retrieve all alpha numbers available in your workspace you can use this request. ## List Workspace Alpha Numbers > 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 (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"queryLimit":{"description":"Limits the number of results to return per page. The default value is 10 and maximum is 99. If the nextPageToken is defined on response, you can use it to get remaining numbers. To know more, refer to the pagination section.\n","in":"query","name":"limit","schema":{"default":10,"maximum":99,"minimum":1,"type":"integer"}},"queryCursor":{"description":"Pagination token that keeps of track of the current position in the list. Use it to query remaining results. If not provided, the first page is returned. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.","in":"query","name":"pageToken","schema":{"maxLength":8000,"type":"string"}},"queryDirection":{"description":"Order in which to retrieve the results. By default, the orders are in ascending order date. To get the results in descending order, set this parameter to true.","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":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"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/queryLimit"},{"$ref":"#/components/parameters/queryCursor"},{"$ref":"#/components/parameters/queryDirection"}],"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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"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 ' ``` {% 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 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 (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","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":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"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 ' ``` {% 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 (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"workspaceId":{"allowEmptyValue":true,"in":"path","name":"workspaceId","required":true,"schema":{"$ref":"#/components/schemas/WorkspaceId"}},"queryValidate":{"description":"When set, only validates the request payload without mutating any data.","in":"query","name":"validate","schema":{"type":"boolean"}}},"schemas":{"WorkspaceId":{"type":"string","format":"uuid","description":"The ID for the workspace."},"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/ValidationError"}}},"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},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}},"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":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/activate":{"post":{"operationId":"activateWorkspaceEndpointDestinations","parameters":[{"$ref":"#/components/parameters/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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"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.
```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 (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","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":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"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 (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","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":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"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= ``` 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.