DokumentationEngagement Platform API
Sign inGet started
Guides
API

Destination management API

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
/workspaces/{workspaceId}/destination-management/capability/{capabilityName}
Get a destination management configuration for a given workspace/capability.
Antwort-Payload
destinations
object
erforderlich
organizationId
string
erforderlich
workspaceId
string
erforderlich
capabilityName
string
erforderlich
createdAt
string
erforderlich
updatedAt
string
erforderlich
Codebeispiel
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Codebeispiel
GET /workspaces/{workspaceId}/destination-management/capability/sms
Response:
Codebeispiel
{
  "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

POST
/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/allow
Adds a list of allowed countries to a destination management configuration for a given workspace/capability.
Anfrage-Payload
destinations
array of string
erforderlich
Antwort-Payload
destinations
object
erforderlich
organizationId
string
erforderlich
workspaceId
string
erforderlich
capabilityName
string
erforderlich
createdAt
string
erforderlich
updatedAt
string
erforderlich
Codebeispiel
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/allow' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Codebeispiel
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:
Codebeispiel
{
  "destinations": ["US", "CA"]
}
Response (full config):
Codebeispiel
{
  "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

POST
/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/block
Adds a list of blocked countries to a destination management configuration for a given workspace/capability.
Anfrage-Payload
destinations
array of string
erforderlich
Antwort-Payload
configuration
object
erforderlich
Untergeordnete Attribute anzeigen
configuration.destinations
object
erforderlich
configuration.organizationId
string
erforderlich
configuration.workspaceId
string
erforderlich
configuration.capabilityName
string
erforderlich
configuration.createdAt
string
erforderlich
configuration.updatedAt
string
erforderlich
message
string
erforderlich
Codebeispiel
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/block' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Codebeispiel
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:
Codebeispiel
{
  "destinations": ["BR", "IN"]
}
Response:
Codebeispiel
{
  "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

PUT
/workspaces/{workspaceId}/destination-management/capability/{capabilityName}
Upsert a destination management configuration for a given workspace/capability.
Anfrage-Payload
destinations
object
erforderlich
Antwort-Payload
destinations
object
erforderlich
organizationId
string
erforderlich
workspaceId
string
erforderlich
capabilityName
string
erforderlich
createdAt
string
erforderlich
updatedAt
string
erforderlich
Codebeispiel
curl -X PUT 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Codebeispiel
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:
Codebeispiel
{
  "destinations": {
    "US": "allowed",
    "BR": "blocked"
  }
}