Privacy Exclusions API

MaxMind maintains a list of Do Not Sell My Personal Information requests. This API provides a simple way to retrieve privacy exclusion requests in an automated fashion.

Request

Request URI

API calls should be made with HTTP GET request to: https://api.maxmind.com/privacy/exclusions

Authorization/Security

We use basic HTTP authentication. The HTTP Authorization header is required for authorization. The username is your MaxMind account ID. The password is your MaxMind license key. The authorization realm is privacy-exclusion.

The API is only available via HTTPS. The credentials are never transmitted unencrypted. If you attempt to access this service via HTTP, you will receive a 403 Forbidden HTTP response.

We require TLS 1.2 or greater for all requests to our servers to keep your data secure.

Request Parameters

The query string may include the following parameter:

KeyValue TypeDescription
updates_afterRFC 3339 timestampIf set, only updates made after this time will be returned. The value should be a valid RFC 3339 timestamp, e.g., 2020-04-12T23:20:50.52Z.

Example Request URL

https://api.maxmind.com/privacy/exclusions?updates_after=2020-04-12T23:20:50.52Z

Response

Response Headers

The Content-Type header will vary based on whether the request was successful or not, and is detailed further in each of the two Response Body sections below.

The response will always include a Content-Length header.

Response Body (for successful requests)

Description

The Content-Type header for a successful response will be application/vnd.maxmind.com-privacy-exclusions+json; charset=UTF-8; version=1.0

Data will be returned as a JSON document in UTF-8 encoding. The document will be a JSON object including the exclusions key. Additional keys may be added in the future.

The value for the exclusions key is an array of objects, each representing one exclusion request.

Each exclusion object in the exclusions array includes the following keys:

KeyValue TypeDescription
exclusion_typeenumThe governing law or rule that the exclusion was made under. Currently, the only valid type is ccpa_do_not_sell for the California Consumer Privacy Act’s “Do Not Sell My Personal Information” provision.
data_typeenumThe data type of the value being excluded. Currently, the only valid data type is network, which is an IP network in CIDR notation; all IP addresses in the specified network should be excluded. You should always check this before using the associated value. In the future, additional types may be added.
valuestringThe value being excluded.
last_updatedRFC 3339 timestampThe time of the last update to the exclusion as an RFC 3339 timestamp.

Please note that additional keys may be added in the future.

Response Body (for unsuccessful requests)

In the event an error occurs (the response indicates a 4xx or 5xx HTTP status), the response may include a JSON document in the body. An error in content negotiation will not include a body nor will many 5xx errors. Before attempting to decode the body as JSON, you should verify that the Content-Type of the error response is application/vnd.maxmind.com-error+json; charset=UTF-8; version=1.0.

If the JSON document is included in the response body, it will be an object with the keys code and error. The code field is a static error code for machine use. The value of any given code will never change, but codes can be added or removed. The error field is a human-readable description of the error and may change at any time.

In addition to the errors documented below, client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.

Code ErrorHTTP StatusError Mode
TIMESTAMP_INVALID400 Bad RequestThe updates_after field must be in RFC 3339 format.
AUTHORIZATION_INVALID401 UnauthorizedYour account ID or license key could not be authenticated.
ACCOUNT_ID_REQUIRED401 UnauthorizedAn account ID and license key are required to use this service.
LICENSE_KEY_REQUIRED401 UnauthorizedAn account ID and license key are required to use this service.
PERMISSION_REQUIRED403 ForbiddenYou do not have permission to use the service. Please contact support@maxmind.com for more information.
(none)503 Service Not AvailableThere is a problem with the web service server. You can check the status of our services, or try this request again later.

This page was last updated on September 17, 2021.