# Cancel Number Subscription

{% hint style="info" %}
"**Cancel Number Subscription**" API endpoint is deprecated, we suggest you to use [Manage Endpoint Subscriptions](/api/numbers-api/api-reference/manage-endpoint-subscriptions.md) APIs to cancel the subscription. You can use `numberId` as `endpointId` parameter and use `main` as a subscription name to achieve identical behavior.
{% endhint %}

## POST /workspaces/{workspaceId}/numbers/{numberId}/cancel-subscription

> Cancel Number Subscription

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage a number within a workspace.","name":"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":{"Number":{"type":"object","required":["id","status","createdAt","updatedAt"],"properties":{"type":{"$ref":"#/components/schemas/NumberInventoryType"},"capabilities":{"$ref":"#/components/schemas/NumberInventoryCapabilities"},"number":{"$ref":"#/components/schemas/PhoneNumber"},"country":{"type":"string","format":"iso3166-1"},"monthlyRecurringPrice":{"$ref":"#/components/schemas/Money"},"complianceRequirements":{"deprecated":true,"type":"array","items":{"$ref":"#/components/schemas/ComplianceRequirement"}},"id":{"type":"string","description":"The ID of the number.","format":"uuid"},"status":{"$ref":"#/components/schemas/NumberStatus"},"subscription":{"$ref":"#/components/schemas/NumberSubscriptionStatus"},"endpointSubscription":{"$ref":"#/components/schemas/EndpointSubscriptionDetails"},"configurations":{"$ref":"#/components/schemas/NumberConfigurations"},"createdAt":{"type":"string","description":"Timestamp (UTC) when the number was created.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the number was last updated.","nullable":true,"format":"date-time"},"activatedAt":{"type":"string","description":"Timestamp (UTC) of the last time the number was activated.","nullable":true,"format":"date-time"},"deactivatedAt":{"type":"string","description":"Timestamp (UTC) of the last time the number was deactivated.","nullable":true,"format":"date-time"},"deactivatesAt":{"type":"string","description":"Timestamp (UTC) when the number will be deactivated.","nullable":true,"format":"date-time"},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/ComplianceRequirementStatus"}},"endpoint":{"$ref":"#/components/schemas/EndpointFragment"},"whatsApp":{"$ref":"#/components/schemas/WorkspaceWhatsAppNumber"}}},"NumberInventoryType":{"type":"string","description":"The type of the number.","enum":["local","national","tollfree","mobile","shortcode"]},"NumberInventoryCapabilities":{"type":"object","description":"The capabilities of the number.","additionalProperties":false,"required":["sms","voice","mms","fax"],"properties":{"sms":{"$ref":"#/components/schemas/NumberInventoryCapability"},"voice":{"$ref":"#/components/schemas/NumberInventoryCapability"},"mms":{"$ref":"#/components/schemas/NumberInventoryCapability"},"fax":{"$ref":"#/components/schemas/NumberInventoryCapability"},"whatsapp":{"$ref":"#/components/schemas/NumberInventoryCapability"}}},"NumberInventoryCapability":{"type":"object","required":["inbound","outbound"],"properties":{"inbound":{"type":"boolean","description":"Whether the number supports inbound use cases."},"outbound":{"type":"boolean","description":"Whether the number supports outbound use cases."}}},"PhoneNumber":{"type":"string","description":"The phone number in E.164 format.","minLength":1,"maxLength":30},"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},"ComplianceRequirement":{"description":"Compliance requirement for a number. It may be a KYC form, use case, or WhatsApp verification. In some cases, a destination may require multiple compliance requirements to be satisfied to be able to send traffic.","oneOf":[{"$ref":"#/components/schemas/ComplianceKYCFormRequirement"},{"$ref":"#/components/schemas/ComplianceUseCaseRequirement"},{"$ref":"#/components/schemas/ComplianceWhatsAppVerificationRequirement"}],"discriminator":{"propertyName":"type","mapping":{"kycForm":"#/components/schemas/ComplianceKYCFormRequirement","useCase":"#/components/schemas/ComplianceUseCaseRequirement","whatsappVerification":"#/components/schemas/ComplianceWhatsAppVerificationRequirement"}}},"ComplianceKYCFormRequirement":{"description":"Know Your Customer (KYC) form requirement for a number.","allOf":[{"$ref":"#/components/schemas/ComplianceBaseRequirement"},{"type":"object","required":["selector"],"properties":{"selector":{"type":"object","required":["scope","numberType","countryCode"],"properties":{"scope":{"type":"string"},"numberType":{"$ref":"#/components/schemas/NumberInventoryType"},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"}}}}}]},"ComplianceBaseRequirement":{"type":"object","required":["name","type","scope"],"properties":{"name":{"type":"string"},"type":{"$ref":"#/components/schemas/ComplianceRequirementType"},"scope":{"$ref":"#/components/schemas/ComplianceRequirementScope"}}},"ComplianceRequirementType":{"type":"string","enum":["kycForm","useCase","whatsappVerification"]},"ComplianceRequirementScope":{"type":"string","enum":["number-activation","sms-outbound","whatsapp"]},"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"ComplianceUseCaseRequirement":{"allOf":[{"$ref":"#/components/schemas/ComplianceBaseRequirement"},{"type":"object","required":["selector"],"properties":{"selector":{"type":"object","required":["numberType","countryCode","platform"],"properties":{"numberType":{"$ref":"#/components/schemas/NumberInventoryType"},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"platform":{"type":"string"}}}}}]},"ComplianceWhatsAppVerificationRequirement":{"allOf":[{"$ref":"#/components/schemas/ComplianceBaseRequirement"},{"type":"object","required":["inventoryId"],"properties":{"inventoryId":{"type":"string","format":"uuid"}}}]},"NumberStatus":{"type":"string","description":"The status of the number.","enum":["active","inactive"]},"NumberSubscriptionStatus":{"type":"object","title":"NumberSubscriptionStatus","additionalProperties":false,"description":"Describes status of Number Subscription","nullable":true,"properties":{"status":{"type":"string","$ref":"#/components/schemas/AccountingSubscriptionStatus"},"subscribedAt":{"type":"string","description":"Timestamp (UTC) when the subscription became active.","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp (UTC) when the subscription was last updated.","nullable":true,"format":"date-time"},"cancelledAt":{"type":"string","description":"Timestamp (UTC) when the subscription was cancelled.","nullable":true,"format":"date-time"}}},"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."},"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."}}},"NumberConfigurations":{"type":"object","additionalProperties":false,"properties":{"voice":{"$ref":"#/components/schemas/NumberConfigOptions"},"sms":{"$ref":"#/components/schemas/NumberConfigOptions"},"mms":{"$ref":"#/components/schemas/NumberConfigOptions"},"fax":{"$ref":"#/components/schemas/NumberConfigOptions"},"whatsapp":{"$ref":"#/components/schemas/ConnectorConfiguration"}}},"NumberConfigOptions":{"type":"object","additionalProperties":false,"properties":{"inbound":{"$ref":"#/components/schemas/ConnectorConfiguration"},"outbound":{"$ref":"#/components/schemas/ConnectorConfiguration"}}},"ConnectorConfiguration":{"type":"object","additionalProperties":false,"properties":{"connectorId":{"type":"string","format":"uuid"},"connectorTemplateId":{"type":"string","format":"uuid"},"connectorTemplateRef":{"type":"string","nullable":true}}},"ComplianceRequirementStatus":{"type":"object","required":["requirement","status","reference"],"description":"Compliance requirement status for a number.","properties":{"requirement":{"$ref":"#/components/schemas/ComplianceRequirement"},"status":{"$ref":"#/components/schemas/ComplianceStatus"},"reference":{"type":"string","nullable":true},"notOkSince":{"type":"string","description":"Timestamp (UTC) when the number didn't meet the requirement.","format":"date-time"}}},"ComplianceStatus":{"type":"string","enum":["ok","pending","not-valid","not-found","error","no-reference"]},"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/{numberId}/cancel-subscription":{"post":{"operationId":"cancelNumberSubscription","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Number"}}},"description":"Updated Number"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Number not found"}},"summary":"Cancel Number Subscription","tags":["numbers"]}}}}
```


---

# 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/manage-endpoint-subscriptions/cancel-number-subscription.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.