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
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
Responseall of
get
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": "2025-08-01T15:23:30.395Z",
        "updatedAt": "2025-08-01T15:23:30.395Z",
        "canceledAt": "2025-08-01T15:23:30.395Z",
        "startAt": "2025-08-01T15:23:30.395Z",
        "endAt": "2025-08-01T15:23:30.395Z"
      }
    }
  ]
}

Get Workspace Endpoint Subscription

get

This route returns a specific subscription for a specific endpoint.

Authorizations
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
get
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": "2025-08-01T15:23:30.395Z",
    "updatedAt": "2025-08-01T15:23:30.395Z",
    "canceledAt": "2025-08-01T15:23:30.395Z",
    "startAt": "2025-08-01T15:23:30.395Z",
    "endAt": "2025-08-01T15:23:30.395Z"
  }
}

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
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
quantityinteger · min: 1Required
Responses
200
OK
application/json
post
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": "2025-08-01T15:23:30.395Z",
    "updatedAt": "2025-08-01T15:23:30.395Z",
    "canceledAt": "2025-08-01T15:23:30.395Z",
    "startAt": "2025-08-01T15:23:30.395Z",
    "endAt": "2025-08-01T15:23:30.395Z"
  }
}

Cancel Workspace Endpoint Subscription

post

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

Authorizations
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
post
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": "2025-08-01T15:23:30.395Z",
    "updatedAt": "2025-08-01T15:23:30.395Z",
    "canceledAt": "2025-08-01T15:23:30.395Z",
    "startAt": "2025-08-01T15:23:30.395Z",
    "endAt": "2025-08-01T15:23:30.395Z"
  }
}

Last updated

Was this helpful?