Umbrella Destination Lists API, Umbrella Destinations API

Destination Lists

The Umbrella Destination Lists API enables you to create and 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.

About 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

About Destinations

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

You can find the Umbrella Destination Lists API endpoints under the policies scope in the Umbrella API.

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 Type Destination List Type
domain Allow, Block
url Block
ipv4 Allow

Rate Limits for Policies API Endpoints

Umbrella enables rate limits on the Destination Lists API endpoints. For more information, see Rate Limits > Policies.

Request Headers

Unless specified, the Umbrella API endpoints use JSON for all requests and responses.

Note: For POST, PUT, and PATCH operations, set the HTTP Content-Type header to application/json in your API request.

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 https://api.umbrella.com/policies/v2/destinationlists
  • POST https://api.umbrella.com/policies/v2/destinationlists/{destinationListId}/destinations

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

Error Conditions When Adding URLs on High-Volume Domains to Destination Lists

If you make a Destination Lists API request that adds a URL on a high-volume domain to a destination list, the operation may succeed (HTTP/200 OK). However, the server returns an error message (HTTP/400 Bad Request) that indicates that the destination is on a high-volume domain.

Note: Umbrella does not add URLs on high-volume domains to destination lists. Instead, we recommend that you add the domain only.

For more information about the error conditions that may occur when you add destinations to destination lists, see Umbrella SIG User Guide: Troubleshooting DNS Destination Lists.

Delete Destinations and Destination Limits

The Destination Lists API DELETE operation, that removes a list of destinations from a destination list, accepts no more than 500 destination IDs in the body of the API request.

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

Note: If you make an API request to remove more than 500 destinations from a destination list, 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.

Destination Lists API Endpoints