Destination management API

Set the outbound SMS destination policy for a workspace.

Control which countries can receive SMS at the workspace level by allowing or blocking destinations. Destinations are ISO 3166-1 alpha-2 country codes.

Endpoints

Get a destination management configuration for a given workspace/capability.

get

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

capabilityNamestringRequired

Responses

200

Could get the destination management config successfully

application/json

organizationIdstring · uuidRequired

workspaceIdstring · uuidRequired

capabilityNamestringRequired

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

400

The request was malformed.

application/json

get/workspaces/{workspaceId}/destination-management/capability/{capabilityName}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/destination-management/capability/{capabilityName} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "destinations": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "capabilityName": "text",
  "createdAt": "2026-08-10T21:46:05.585Z",
  "updatedAt": "2026-08-10T21:46:05.585Z"
}

GET /workspaces/{workspaceId}/destination-management/capability/sms

Response:

{
  "organizationId": "5a3d8cf1-3aaf-4b56-a2e0-260b28c0a0d0",
  "workspaceId": "e9d00796-afb3-458e-ad85-64a1bdefe3aa",
  "capabilityName": "sms",
  "destinations": {
    "US": "allowed",
    "BR": "blocked"
  },
  "createdAt": "2025-01-02T15:04:05Z",
  "updatedAt": "2025-01-09T10:11:12Z"
}

Allow destinations

Adds a list of allowed countries to a destination management configuration for a given workspace/capability.

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

capabilityNamestringRequired

Body

application/json

destinationsstring · iso3166-1[]Required

Responses

200

Updated

application/json

organizationIdstring · uuidRequired

workspaceIdstring · uuidRequired

capabilityNamestringRequired

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

400

The request was malformed.

application/json

422

The request contains invalid parameters or body fields.

application/json

post/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/allow

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/destination-management/capability/{capabilityName}/allow HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "destinations": [
    "text"
  ]
}

{
  "destinations": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "capabilityName": "text",
  "createdAt": "2026-08-10T21:46:05.585Z",
  "updatedAt": "2026-08-10T21:46:05.585Z"
}

POST /workspaces/{workspaceId}/destination-management/capability/sms/allow

Notes:

• destinations is an array of country codes

• This will add specific destinations

• Destinations are ISO 3166-1 alpha-2 country codes.

Request body:

{
  "destinations": ["US", "CA"]
}

Response (full config):

{
  "organizationId": "5a3d8cf1-3aaf-4b56-a2e0-260b28c0a0d0",
  "workspaceId": "e9d00796-afb3-458e-ad85-64a1bdefe3aa",
  "capabilityName": "sms",
  "destinations": {
    "US": "allowed",
    "CA": "allowed",
    "BR": "blocked"
  },
  "createdAt": "2025-01-02T15:04:05Z",
  "updatedAt": "2025-01-09T10:11:12Z"
}

Block destinations

Adds a list of blocked countries to a destination management configuration for a given workspace/capability.

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

capabilityNamestringRequired

Body

application/json

destinationsstring · iso3166-1[]Required

Responses

200

Updated

application/json

messagestringRequired

400

The request was malformed.

application/json

422

The request contains invalid parameters or body fields.

application/json

post/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/block

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/destination-management/capability/{capabilityName}/block HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "destinations": [
    "text"
  ]
}

{
  "configuration": {
    "destinations": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "capabilityName": "text",
    "createdAt": "2026-08-10T21:46:05.585Z",
    "updatedAt": "2026-08-10T21:46:05.585Z"
  },
  "message": "text"
}

POST /workspaces/{workspaceId}/destination-management/capability/sms/block

Notes:

• destinations is an array of country codes

• This will remove specific destinations

• Destinations are ISO 3166-1 alpha-2 country codes.

Request body:

{
  "destinations": ["BR", "IN"]
}

Response:

{
  "message": "Destinations have been blocked. If the block is not temporary, please cancel any associated subscriptions to prevent unexpected charges.",
  "configuration": {
    "organizationId": "5a3d8cf1-3aaf-4b56-a2e0-260b28c0a0d0",
    "workspaceId": "e9d00796-afb3-458e-ad85-64a1bdefe3aa",
    "capabilityName": "sms",
    "destinations": {
      "US": "allowed",
      "BR": "blocked",
      "IN": "blocked"
    },
    "createdAt": "2025-01-02T15:04:05Z",
    "updatedAt": "2025-01-09T10:11:12Z"
  }
}

Upsert config

Upsert a destination management configuration for a given workspace/capability.

put

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

capabilityNamestringRequired

Body

application/json

Responses

200

Created or updated

application/json

organizationIdstring · uuidRequired

workspaceIdstring · uuidRequired

capabilityNamestringRequired

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

400

The request was malformed.

application/json

422

The request contains invalid parameters or body fields.

application/json

put/workspaces/{workspaceId}/destination-management/capability/{capabilityName}

HTTPcURLJavaScriptPython

PUT /workspaces/{workspaceId}/destination-management/capability/{capabilityName} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "destinations": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "destinations": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "capabilityName": "text",
  "createdAt": "2026-08-10T21:46:05.585Z",
  "updatedAt": "2026-08-10T21:46:05.585Z"
}

PUT /workspaces/{workspaceId}/destination-management/capability/sms

Notes:

• destinations is a map of country code → status (allowed or blocked).

• This will fully overwrite your existing config

• Any destination not present in the map is treated as blocked.

• Destinations are ISO 3166-1 alpha-2 country codes.

Request body:

{
  "destinations": {
    "US": "allowed",
    "BR": "blocked"
  }
}