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.

Corps de la réponse

destinations

object

obligatoire

organizationId

string

obligatoire

workspaceId

string

obligatoire

capabilityName

string

obligatoire

createdAt

string

obligatoire

updatedAt

string

obligatoire

Exemple de code

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Exemple de code

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

Response:

Exemple de code

{
  "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.

Corps de la requête

destinations

array of string

obligatoire

Corps de la réponse

destinations

object

obligatoire

organizationId

string

obligatoire

workspaceId

string

obligatoire

capabilityName

string

obligatoire

createdAt

string

obligatoire

updatedAt

string

obligatoire

Exemple de code

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/allow' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Exemple de code

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:

Exemple de code

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

Response (full config):

Exemple de code

{
  "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.

Corps de la requête

destinations

array of string

obligatoire

Corps de la réponse

configuration

object

obligatoire

Afficher les attributs enfants

configuration.destinations

object

obligatoire

configuration.organizationId

string

obligatoire

configuration.workspaceId

string

obligatoire

configuration.capabilityName

string

obligatoire

configuration.createdAt

string

obligatoire

configuration.updatedAt

string

obligatoire

message

string

obligatoire

Exemple de code

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/block' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Exemple de code

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:

Exemple de code

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

Response:

Exemple de code

{
  "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.

Corps de la requête

destinations

object

obligatoire

Corps de la réponse

destinations

object

obligatoire

organizationId

string

obligatoire

workspaceId

string

obligatoire

capabilityName

string

obligatoire

createdAt

string

obligatoire

updatedAt

string

obligatoire

Exemple de code

curl -X PUT 'https://api.bird.com/workspaces/{workspaceId}/destination-management/capability/{capabilityName}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Exemple de code

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:

Exemple de code

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