Skip to main content

POST /identity/buckets

Monitor rotated salt buckets.

Used by: This endpoint is used mainly by advertisers and data providers. For details, see Advertiser/Data Provider Integration Guide.

Request Format

POST '{environment}/v2/identity/buckets'

IMPORTANT: You must encrypt all request using your secret. For details and Python script examples, see Encrypting Requests and Decrypting Responses.

Path Parameters

Path ParameterData TypeAttributeDescription
{environment}stringRequiredTesting environment:
Production environment:
For a full list, including regional operators, see Environments.

NOTE: The integration environment and the production environment require different API keys.

Unencrypted JSON Body Parameters

IMPORTANT: You must include the following parameter as a key-value pair in the JSON body of a request when encrypting it.

Body ParameterData TypeAttributeDescriptionFormat
since_timestampdate-time or integerRequiredSpecify the date and time to which to compare the last updated UTC timestamps of the buckets to be returned.ISO 8601 format:

Request Examples

The following is an unencrypted JSON request body example, which you should include in your identity bucket rotation requests:

"since_timestamp": "2022-06-01T13:00:00"

Here's an encrypted identity bucket rotation request format with placeholder values:

echo '[Unencrypted-JSON-Request-Body]' \
| curl -X POST '' -H 'Authorization: Bearer [CLIENT_API_KEY]' -d @- \

Here's an encrypted identity bucket rotation request example:

echo '{"since_timestamp": "2022-06-01T13:00:00"}' \
| DELPabG/hsJsZk4Xm9Xr10Wb8qoKarg4ochUdY9e+Ow= \
| curl -X POST '' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' -d @- \
| DELPabG/hsJsZk4Xm9Xr10Wb8qoKarg4ochUdY9e+Ow=

For details and Python script examples, see Encrypting Requests and Decrypting Responses.

Decrypted JSON Response Format


The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.

A successful decrypted response returns a list of salt bucket IDs and the timestamps of their last updates.

"bucket_id": "a30od4mNRd",
"last_updated": "2022-06-05T22:52:03.109"
"bucket_id": "aJ0jMvw9Z8",
"last_updated": "2022-06-06T22:52:01.828"
"bucket_id": "aeRQ9L7wRN",
"last_updated": "2022-06-01T22:52:02.574"

Response Body Properties

bucket_idstringThe salt bucket ID.
last_updateddate-timeThe UTC timestamp of the last time the bucket salt was rotated.

Response Status Codes

The following table lists the status property values and their HTTP status code equivalents.

StatusHTTP Status CodeDescription
success200The request was successful. The response will be encrypted.
client_error400The request had missing or invalid parameters.
unauthorized401The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation.

If the status value is anything other than success, the message field provides additional information about the issue.