Skip to content

post-identity-buckets.md

Latest commit

 

History

History
116 lines (85 loc) · 4.77 KB

post-identity-buckets.md

File metadata and controls

116 lines (85 loc) · 4.77 KB
title POST /identity/buckets
description Monitors rotated salt buckets.
hide_table_of_contents false
sidebar_position 7
displayed_sidebar docs

import Link from '@docusaurus/Link';

POST /identity/buckets

Monitors rotated salt buckets.

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

:::important If you're using the latest version (v3) of POST /v3/identity/map, you don't need to use POST /identity/buckets at all. You only need to use it if you're using the earlier version (v2) of POST /v2/identity/map.

If you're using the v2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see Migration from v2 Identity Map. :::

Request Format

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

For authentication details, see Authentication and Authorization.

:::important You must encrypt all requests using your secret. For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses. :::

Path Parameters

Path Parameter Data Type Attribute Description
{environment} string Required Testing (integration) environment: https://operator-integ.uidapi.com
Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see Environments.

:::note The integration environment and the production environment require different API keys. For information about getting credentials for each environment, see Getting Your Credentials. :::

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 Parameter Data Type Attribute Description Format
since_timestamp date-time or integer Required Specify the date and time to which to compare the last updated UTC timestamps of the buckets to be returned. ISO 8601 format:
YYYY-MM-DDThh:mm:ss

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 example:

echo '{"since_timestamp": "2023-04-19T13:00:00"}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/buckets [Your-Client-API-Key] [Your-Client-Secret]

For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses.

Decrypted JSON Response Format

:::note 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.

{
    "body":[
        {
            "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"
        }
    ],
    "status":"success"
}

Response Body Properties

The response body includes the properties shown in the following table.

Property Format Description
bucket_id string The salt bucket ID.
last_updated date-time The 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.

Status HTTP Status Code Description
success 200 The request was successful. The response will be encrypted.
client_error 400 The request had missing or invalid parameters.
unauthorized 401 The 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.