Overview

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. Use your Umbrella Management API key and secret to authorize an API request.

Types of Destination

A destination represents the following types of network location identifier:

• Fully qualified domain name (FQDN)
• URL
• IPv4 address

You can create Allow or Block destination lists and add the various types of destination to a destination list.

Destination Lists

• Create a destination list and add a list of destinations to allow or block
• Get, update, and delete a destination list
• Find the destination lists

Destinations

• Add destinations to a destination list
• Find the destinations in a destination list
• Delete the destinations in a destination list

POST Requests and Destination Limits

The Destination Lists API POST endpoints accept no more than 500 Destination objects in the body of the request.

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

If you request to create a Destination List with more than 500 Destination objects, Umbrella returns an HTTP 400 error response.

Total Pages in Destination Lists API Collections

You can use the value of the total field from the meta object in the API response to calculate the total number of pages in a collection of destination lists or destinations.

Note: For the Destination Lists API endpoints that return a collection, the default value for the page query parameter is 1. The default value for the limit query parameter is 100.

Destination Lists API endpoints that accept the limit and query parameters:

• GET https://api.umbrella.com/policies/v2/destinationlists
• GET https://api.umbrella.com/policies/v2/destinationlists/{destinationListId}/destinations

Query Destination Lists Collection for Total Records

Create a GET request to the Destination Lists API collection, and set the page parameter to a number that you estimate is larger than the number of pages in the collection.

Example Request:

curl -L --location-trusted --request GET --url 'https://api.umbrella.com/policies/v2/destinationlists?page=50&limit=1' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Example Response:

{
    "status": {
        "code": 200,
        "text": "OK"
    },
    "meta": {
        "page": 50,
        "limit": 1,
        "total": 2
    },
    "data": []
}

Calculate Total Pages in Collection

After getting the total number of records in the collection, calculate the number of pages in the collection. For a collection with more than the default number of records in a page (100), divide the total number of records by the default number of records in a page. If the total number of records in the collection is less than the default number of records in a page, the number of pages in the collection is 1.