# Manage Endpoint Subscriptions
Manage your Number/ Sender ID subscription status, all sender types are considered "endpoints".
## List Workspace Endpoint Subscriptions
> This route returns all associated subscriptions of a given endpoint.
```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":{"get":{"operationId":"listWorkspaceEndpointSubscriptions","description":"This route returns all associated subscriptions of a given endpoint.\n","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"results":{"items":{"$ref":"#/components/schemas/EndpointSubscription"},"type":"array"}},"required":["results"],"type":"object"}]}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Endpoint not found"}},"summary":"List Workspace Endpoint Subscriptions","tags":["endpoints"]}}}}
```
## Get Workspace Endpoint Subscription
> This route returns a specific subscription for a specific endpoint.
```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}":{"get":{"operationId":"getWorkspaceEndpointSubscription","description":"This route returns a specific subscription for a specific endpoint.\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":"Get Workspace Endpoint Subscription","tags":["endpoints"]}}}}
```
## Activate Workspace Endpoint Subscription
> Use this endpoint to active a subscription to be able to send messages and be compliant with requirements.\
> There may be charges associated with the subscription for certain 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":{"ActivateEndpointSubscription":{"type":"object","required":["quantity"],"properties":{"quantity":{"type":"integer","minimum":1}}},"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}/activate":{"post":{"operationId":"activateWorkspaceEndpointSubscription","description":"Use this endpoint to active a subscription to be able to send messages and be compliant with requirements.\nThere may be charges associated with the subscription for certain destinations.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateEndpointSubscription"}}},"required":false},"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":"Activate Workspace Endpoint Subscription","tags":["endpoints"]}}}}
```
## 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"]}}}}
```
---
# 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.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.