> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/numbers-api/api-reference/destination-management-api.md).

# 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.

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"DestinationManagement":{"type":"object","required":["organizationId","workspaceId","destinations","capabilityName","createdAt","updatedAt"],"properties":{"destinations":{"type":"object","additionalProperties":{"type":"string"}},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"capabilityName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.bad_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The request was malformed."}}},"paths":{"/workspaces/{workspaceId}/destination-management/capability/{capabilityName}":{"get":{"operationId":"getDestinationManagementConfig","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationManagement"}}},"description":"Could get the destination management config successfully"},"400":{"$ref":"#/components/responses/error.response.bad_request"}},"summary":"Get a destination management configuration for a given workspace/capability.","tags":["destination_management"]}}}}
```

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

Response:

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

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"DestinationManagementOperationRequest":{"type":"object","required":["destinations"],"properties":{"destinations":{"type":"array","items":{"type":"string","format":"iso3166-1"}}}},"DestinationManagement":{"type":"object","required":["organizationId","workspaceId","destinations","capabilityName","createdAt","updatedAt"],"properties":{"destinations":{"type":"object","additionalProperties":{"type":"string"}},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"capabilityName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"error.response.bad_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The request was malformed."},"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"paths":{"/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/allow":{"post":{"operationId":"applyAllowOverDestinationManagementConfig","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationManagementOperationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationManagement"}}},"description":"Updated"},"400":{"$ref":"#/components/responses/error.response.bad_request"},"422":{"$ref":"#/components/responses/error.response.invalid_request"}},"summary":"Adds a list of allowed countries to a destination management configuration for a given workspace/capability.","tags":["destination_management"]}}}}
```

```
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:**

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

**Response (full config):**

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

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"DestinationManagementOperationRequest":{"type":"object","required":["destinations"],"properties":{"destinations":{"type":"array","items":{"type":"string","format":"iso3166-1"}}}},"DestinationManagementBlockResponse":{"type":"object","required":["configuration","message"],"properties":{"configuration":{"$ref":"#/components/schemas/DestinationManagement"},"message":{"type":"string"}}},"DestinationManagement":{"type":"object","required":["organizationId","workspaceId","destinations","capabilityName","createdAt","updatedAt"],"properties":{"destinations":{"type":"object","additionalProperties":{"type":"string"}},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"capabilityName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"error.response.bad_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The request was malformed."},"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"paths":{"/workspaces/{workspaceId}/destination-management/capability/{capabilityName}/block":{"post":{"operationId":"applyBlockOverDestinationManagementConfig","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationManagementOperationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationManagementBlockResponse"}}},"description":"Updated"},"400":{"$ref":"#/components/responses/error.response.bad_request"},"422":{"$ref":"#/components/responses/error.response.invalid_request"}},"summary":"Adds a list of blocked countries to a destination management configuration for a given workspace/capability.","tags":["destination_management"]}}}}
```

```
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:**

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

**Response:**

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

```json
{"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"DestinationManagementUpsertRequest":{"type":"object","required":["destinations"],"properties":{"destinations":{"type":"object","additionalProperties":{"type":"string"}}}},"DestinationManagement":{"type":"object","required":["organizationId","workspaceId","destinations","capabilityName","createdAt","updatedAt"],"properties":{"destinations":{"type":"object","additionalProperties":{"type":"string"}},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"capabilityName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"error.response.bad_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The request was malformed."},"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"paths":{"/workspaces/{workspaceId}/destination-management/capability/{capabilityName}":{"put":{"operationId":"upsertDestinationManagementConfig","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationManagementUpsertRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationManagement"}}},"description":"Created or updated"},"400":{"$ref":"#/components/responses/error.response.bad_request"},"422":{"$ref":"#/components/responses/error.response.invalid_request"}},"summary":"Upsert a destination management configuration for a given workspace/capability.","tags":["destination_management"]}}}}
```

```
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:**

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