Manage Endpoint Subscriptions

Manage your Number/ Sender ID subscription status, all sender types are considered "endpoints".

List Workspace Endpoint Subscriptions

get

This route returns all associated subscriptions of a given endpoint.

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

endpointIdstringRequired

Your endpoint ID. In some cases (e.g. Long Code Numbers) this value is equal to the number ID.

Responses

200

OK

application/json

404

Endpoint not found

application/json

get

/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "name": "text",
      "status": "active",
      "price": {
        "currencyCode": "EUR",
        "amount": 3500000,
        "exponent": -6
      },
      "subscription": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "correlationId": "123e4567-e89b-12d3-a456-426614174000",
        "status": "none",
        "subscribedAt": "2026-03-06T17:14:18.572Z",
        "updatedAt": "2026-03-06T17:14:18.572Z",
        "canceledAt": "2026-03-06T17:14:18.572Z",
        "startAt": "2026-03-06T17:14:18.572Z",
        "endAt": "2026-03-06T17:14:18.572Z"
      }
    }
  ]
}

Get Workspace Endpoint Subscription

get

This route returns a specific subscription for a specific endpoint.

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

endpointIdstringRequired

Your endpoint ID. In some cases (e.g. Long Code Numbers) this value is equal to the number ID.

subscriptionNamestringRequired

Your number subscription name. For long code numbers, the subscription name is 'main'. For short code and alpha numbers, the subscription name is the same as the country code of the destination which you want to subscribe to.

Example: main

Responses

200

OK

application/json

namestringRequired

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.

statusstring · enumRequired

The status of the endpoint subscription. It can be active or inactive.

Possible values:

404

Not Found

application/json

get

/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "status": "active",
  "price": {
    "currencyCode": "EUR",
    "amount": 3500000,
    "exponent": -6
  },
  "subscription": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "correlationId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "none",
    "subscribedAt": "2026-03-06T17:14:18.572Z",
    "updatedAt": "2026-03-06T17:14:18.572Z",
    "canceledAt": "2026-03-06T17:14:18.572Z",
    "startAt": "2026-03-06T17:14:18.572Z",
    "endAt": "2026-03-06T17:14:18.572Z"
  }
}

Activate Workspace Endpoint Subscription

post

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.

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

endpointIdstringRequired

Your endpoint ID. In some cases (e.g. Long Code Numbers) this value is equal to the number ID.

subscriptionNamestringRequired

Your number subscription name. For long code numbers, the subscription name is 'main'. For short code and alpha numbers, the subscription name is the same as the country code of the destination which you want to subscribe to.

Example: main

Body

application/json

quantityinteger · min: 1Required

Responses

200

OK

application/json

namestringRequired

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.

statusstring · enumRequired

The status of the endpoint subscription. It can be active or inactive.

Possible values:

404

Not Found

application/json

post

/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/activate

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/activate HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "quantity": 1
}

{
  "name": "text",
  "status": "active",
  "price": {
    "currencyCode": "EUR",
    "amount": 3500000,
    "exponent": -6
  },
  "subscription": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "correlationId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "none",
    "subscribedAt": "2026-03-06T17:14:18.572Z",
    "updatedAt": "2026-03-06T17:14:18.572Z",
    "canceledAt": "2026-03-06T17:14:18.572Z",
    "startAt": "2026-03-06T17:14:18.572Z",
    "endAt": "2026-03-06T17:14:18.572Z"
  }
}

Cancel Workspace Endpoint Subscription

post

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

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

endpointIdstringRequired

Your endpoint ID. In some cases (e.g. Long Code Numbers) this value is equal to the number ID.

subscriptionNamestringRequired

Your number subscription name. For long code numbers, the subscription name is 'main'. For short code and alpha numbers, the subscription name is the same as the country code of the destination which you want to subscribe to.

Example: main

Responses

200

OK

application/json

namestringRequired

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.

statusstring · enumRequired

The status of the endpoint subscription. It can be active or inactive.

Possible values:

404

Not Found

application/json

post

/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/cancel

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/cancel HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "status": "active",
  "price": {
    "currencyCode": "EUR",
    "amount": 3500000,
    "exponent": -6
  },
  "subscription": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "correlationId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "none",
    "subscribedAt": "2026-03-06T17:14:18.572Z",
    "updatedAt": "2026-03-06T17:14:18.572Z",
    "canceledAt": "2026-03-06T17:14:18.572Z",
    "startAt": "2026-03-06T17:14:18.572Z",
    "endAt": "2026-03-06T17:14:18.572Z"
  }
}