Cancel Number Subscription

"Cancel Number Subscription" API endpoint is deprecated, we suggest you to use Manage Endpoint Subscriptions APIs to cancel the subscription. You can use numberId as endpointId parameter and use main as a subscription name to achieve identical behavior.

Cancel Number Subscription

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e

numberIdstringRequired

The number/endpoint ID.

Example: e40ce70f-e7e0-45c0-9d64-2fc7d0401a16

Responses

200

Updated Number

application/json

typestring · enumOptional

The type of the number.

Possible values:

numberstring · min: 1 · max: 30Optional

The phone number in E.164 format.

Example: [phone]

countrystring · iso3166-1Optional

idstring · uuidRequired

The ID of the number.

statusstring · enumRequired

The status of the number.

Possible values:

createdAtstring · date-timeRequired

Timestamp (UTC) when the number was created.

updatedAtstring · date-time · nullableRequired

Timestamp (UTC) when the number was last updated.

activatedAtstring · date-time · nullableOptional

Timestamp (UTC) of the last time the number was activated.

deactivatedAtstring · date-time · nullableOptional

Timestamp (UTC) of the last time the number was deactivated.

deactivatesAtstring · date-time · nullableOptional

Timestamp (UTC) when the number will be deactivated.

404

Number not found

application/json

post

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

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/numbers/{numberId}/cancel-subscription HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "type": "local",
  "capabilities": {
    "sms": {
      "inbound": true,
      "outbound": true
    },
    "voice": {
      "inbound": true,
      "outbound": true
    },
    "mms": {
      "inbound": true,
      "outbound": true
    },
    "fax": {
      "inbound": true,
      "outbound": true
    },
    "whatsapp": {
      "inbound": true,
      "outbound": true
    }
  },
  "number": "[phone]",
  "country": "text",
  "monthlyRecurringPrice": {
    "currencyCode": "EUR",
    "amount": 3500000,
    "exponent": -6
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "subscription": {
    "status": "none",
    "subscribedAt": "2026-03-06T18:42:00.947Z",
    "updatedAt": "2026-03-06T18:42:00.947Z",
    "cancelledAt": "2026-03-06T18:42:00.947Z"
  },
  "endpointSubscription": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "correlationId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "none",
    "subscribedAt": "2026-03-06T18:42:00.947Z",
    "updatedAt": "2026-03-06T18:42:00.947Z",
    "canceledAt": "2026-03-06T18:42:00.947Z",
    "startAt": "2026-03-06T18:42:00.947Z",
    "endAt": "2026-03-06T18:42:00.947Z"
  },
  "configurations": {
    "voice": {
      "inbound": {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text"
      },
      "outbound": {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text"
      }
    },
    "sms": {
      "inbound": {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text"
      },
      "outbound": {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text"
      }
    },
    "mms": {
      "inbound": {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text"
      },
      "outbound": {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text"
      }
    },
    "fax": {
      "inbound": {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text"
      },
      "outbound": {
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text"
      }
    },
    "whatsapp": {
      "connectorId": "123e4567-e89b-12d3-a456-426614174000",
      "connectorTemplateId": "123e4567-e89b-12d3-a456-426614174000",
      "connectorTemplateRef": "text"
    }
  },
  "createdAt": "2026-03-06T18:42:00.947Z",
  "updatedAt": "2026-03-06T18:42:00.947Z",
  "activatedAt": "2026-03-06T18:42:00.947Z",
  "deactivatedAt": "2026-03-06T18:42:00.947Z",
  "deactivatesAt": "2026-03-06T18:42:00.947Z",
  "requirements": [
    {
      "requirement": {
        "name": "text",
        "type": "kycForm",
        "scope": "number-activation",
        "selector": {
          "scope": "text",
          "numberType": "local",
          "countryCode": "US"
        }
      },
      "status": "ok",
      "reference": "text",
      "notOkSince": "2026-03-06T18:42:00.947Z"
    }
  ],
  "endpoint": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "long-code-number",
    "instanceId": "1551f382-6870-4480-8f9b-f5ab34936288",
    "name": "[phone]",
    "capabilities": [
      {
        "name": "sms",
        "inbound": {
          "status": "active",
          "issues": [
            "subscription-is-not-active"
          ]
        },
        "outbound": {
          "status": "active",
          "destinationStatuses": {
            "active": 1,
            "inactive": 1,
            "available": 1,
            "unavailable": 1
          },
          "supportsDestinations": true,
          "issues": [
            "subscription-is-not-active"
          ]
        }
      }
    ],
    "dependencies": [
      {
        "type": "connector",
        "connectorId": "123e4567-e89b-12d3-a456-426614174000",
        "connectorTemplateRef": "text",
        "capabilities": [
          "voice"
        ]
      }
    ],
    "issues": [
      "subscription-is-not-active"
    ],
    "provisioningStatus": "provisioned",
    "whatsApp": {
      "whatsAppId": "text",
      "status": "verified",
      "stage": "text",
      "attempt": 1,
      "nextAttemptAt": "2026-03-06T18:42:00.947Z",
      "verificationExpiresAt": "2026-03-06T18:42:00.947Z",
      "requestedCodeAt": "2026-03-06T18:42:00.947Z",
      "createdAt": "2026-03-06T18:42:00.947Z",
      "updatedAt": "2026-03-06T18:42:00.947Z"
    },
    "createdAt": "2026-03-06T18:42:00.947Z",
    "updatedAt": "2026-03-06T18:42:00.947Z"
  },
  "whatsApp": {
    "whatsAppId": "text",
    "status": "verified",
    "stage": "text",
    "attempt": 1,
    "nextAttemptAt": "2026-03-06T18:42:00.947Z",
    "verificationExpiresAt": "2026-03-06T18:42:00.947Z",
    "requestedCodeAt": "2026-03-06T18:42:00.947Z",
    "createdAt": "2026-03-06T18:42:00.947Z",
    "updatedAt": "2026-03-06T18:42:00.947Z"
  }
}