Umbrella Destination Lists API: create destination lists, destinations

Destination Lists

The Umbrella Destination Lists API enables you to programmatically manage access to network destinations. In Umbrella, you can block or allow a destination based on the policies applied to the identities within your organization.

Create a Destination List

POST /organizations/{organizationId}/destinationlists

Create a destination list and optionally add a list of destination information.

Request Body Fields

Name	Type	Description
access	string	The type of the destination list. Valid types are: `allow` or `block`. Required
isGlobal	boolean	Specify the destination list as a global destination list. There is only one default destination list of type `allow` or `block` for an organization. Set `true` or `false`. Required
name	string	The name of the destination list. Required
destinations	array	A list of Destination object. Accepts no more than 500 destination objects.
bundleTypeId	integer	The type of the Umbrella policy associated with the destination list. Set `1` to choose the Umbrella DNS policy or `2` to choose the Umbrella Web policy. If the field is not specified, the default value is `1`.

Destination Object

Name	Type	Description
destination	string	A destination is a domain, URL, or IPv4 address. For example: google.com or google.com/news or 10.10.10.10.
type	string	The type of the destination. Valid types are: `DOMAIN`, `URL`, or `IPV4`.
comment	string	A string which describes the destination. A comment must be less than 256 characters.

Request

curl -i -X POST "https://management.api.umbrella.com/v1/organizations/{organizationId}/destinationlists" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json' \
-d '{
    "access": "allow",
    "isGlobal": false,
    "name": "a test destination list",
    "destinations": [
        {
            "destination": "wikipedia.com",
            "type": "DOMAIN",
            "comment": "test domain, wikipedia.com"
        },
        {
            "destination": "google.com",
            "type": "DOMAIN",
            "comment": "test domain, google.com"
        },
        {
            "destination": "ebay.com",
            "type": "DOMAIN",
            "comment": "test domain, ebay.com"
        }
    ]
}'

Response

Sample response (200, OK):

{
    "id": 10328873,
    "organizationId": 1234567,
    "access": "allow",
    "isGlobal": false,
    "name": "a test destination list",
    "thirdpartyCategoryId": null,
    "createdAt": "2021-06-28T20:48:12+0000",
    "modifiedAt": "2021-06-28T20:48:12+0000",
    "isMspDefault": false,
    "markedForDeletion": false,
    "bundleTypeId": 1,
    "meta": {
        "destinationCount": 3
    }
}

Get Destination Lists

GET /organizations/{organizationId}/destinationlists

Find the destination lists for the organization.

Request

curl -i GET "https://management.api.umbrella.com/v1/organizations/{organizationId}/destinationlists" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

"status": {
    "code": 200,
    "text": OK
},
"meta": {
    "page": 1,
    "limit": 100,
    "total": 100
},
"data": [
    {
        "id": 10328875,
        "organizationId": 1234567,
        "access": "allow",
        "isGlobal": false,
        "name": "test web policy destination list",
        "thirdpartyCategoryId": null,
        "createdAt": "2022-01-10T15:34:21+0000",
        "modifiedAt": "2022-01-10T15:34:21+0000",
        "isMspDefault": false,
        "markedForDeletion": false,
        "bundleTypeId": 2,
        "meta": {
            "destinationCount": 3,
            "domainCount": 3,
            "urlCount": 1,
            "ipv4Count": 0,
            "applicationCount": 0
        }
    }
]

Add Destinations to Destination List

POST /organizations/{organizationId}/destinationlists/{destinationListId}/destinations

Add a list of destinations to a destination list.

Note: The Destination Lists resource includes the destination list ID.

Request Body Fields

Name	Type	Description
No specified field name	array	A list of Destination object. The body of the request accepts no more than 500 destination objects.

Destination Object

Name	Type	Description
destination	string	A destination is a domain, URL, or IPv4 address. For example: google.com or google.com/news or 10.10.10.10. Required
comment	string	A string which describes the destination. A comment must be less than 256 characters.

Request

curl -i -X POST "https://management.api.umbrella.com/v1/organizations/{organizationId}/destinationlists/{destinationId}/destinations" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json' \
-d '[
        {
            "destination": "nintendo.com",
            "comment": "nintendo test domain"
        },
        {
            "destination": "twitter.com",
            "comment": "twitter test domain"
        }
    ]'

Response

Sample response (200, OK):

{
    "id": 10328873,
    "organizationId": 1234567,
    "access": "allow",
    "isGlobal": false,
    "name": "a test destination list",
    "thirdpartyCategoryId": null,
    "createdAt": "2021-06-28T20:48:12+0000",
    "modifiedAt": "2021-06-28T21:15:52+0000",
    "isMspDefault": false,
    "markedForDeletion": false,
    "bundleTypeId": 1,
    "meta": {
        "destinationCount": 5
    }
}

Delete Destinations from Destination List

DELETE /organizations/{organizationId}/destinationlists/{destinationListId}/destinations/remove

Delete destinations from a destination list. Provide a list of destination ID in the request body.

Request Body Fields

Name	Type	Description
No specified field name	array	A list of destination ID.

Request

curl -i -X DELETE "https://management.api.umbrella.com/v1/organizations/{organizationId}/destinationlists/remove" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json' \
-d '[ 56, 135 ]'

Response

Sample response (200, OK):

{
    "id": 10328873,
    "organizationId": 1234567,
    "access": "allow",
    "isGlobal": false,
    "name": "a test destination list",
    "thirdpartyCategoryId": null,
    "createdAt": "2021-06-28T20:48:12+0000",
    "modifiedAt": "2021-06-28T20:48:12+0000",
    "isMspDefault": false,
    "markedForDeletion": false,
    "bundleTypeId": 1,
    "meta": {
        "destinationCount": 1
    }
}