DocumentazioneEngagement 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.
Payload della risposta
destinations
object
obbligatorio
organizationId
string
obbligatorio
workspaceId
string
obbligatorio
capabilityName
string
obbligatorio
createdAt
string
obbligatorio
updatedAt
string
obbligatorio
Esempio di codice
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Esempio di codice
GET /workspaces/{workspaceId}/destination-management/capability/sms
Response:
Esempio di codice
{
  "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.
Payload della richiesta
destinations
array of string
obbligatorio
Payload della risposta
destinations
object
obbligatorio
organizationId
string
obbligatorio
workspaceId
string
obbligatorio
capabilityName
string
obbligatorio
createdAt
string
obbligatorio
updatedAt
string
obbligatorio
Esempio di codice
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/allow' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Esempio di codice
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:
Esempio di codice
{
  "destinations": ["US", "CA"]
}
Response (full config):
Esempio di codice
{
  "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.
Payload della richiesta
destinations
array of string
obbligatorio
Payload della risposta
configuration
object
obbligatorio
Mostra attributi secondari
configuration.destinations
object
obbligatorio
configuration.organizationId
string
obbligatorio
configuration.workspaceId
string
obbligatorio
configuration.capabilityName
string
obbligatorio
configuration.createdAt
string
obbligatorio
configuration.updatedAt
string
obbligatorio
message
string
obbligatorio
Esempio di codice
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/block' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Esempio di codice
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:
Esempio di codice
{
  "destinations": ["BR", "IN"]
}
Response:
Esempio di codice
{
  "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.
Payload della richiesta
destinations
object
obbligatorio
Payload della risposta
destinations
object
obbligatorio
organizationId
string
obbligatorio
workspaceId
string
obbligatorio
capabilityName
string
obbligatorio
createdAt
string
obbligatorio
updatedAt
string
obbligatorio
Esempio di codice
curl -X PUT 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Esempio di codice
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:
Esempio di codice
{
  "destinations": {
    "US": "allowed",
    "BR": "blocked"
  }
}