From 00c553734a703d1e4a046d51abf04a9e3374d403 Mon Sep 17 00:00:00 2001 From: sean wibisono Date: Tue, 31 Mar 2026 16:06:11 +1100 Subject: [PATCH 1/6] remove 'sequential' restriction from /identity/map endpoint docs --- docs/endpoints/post-identity-map-v2.md | 2 +- docs/endpoints/post-identity-map.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index 781f25e91..ed5674c17 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -28,7 +28,7 @@ If you're using an earlier version, we recommend that you upgrade as soon as pos Here's what you need to know: - The maximum request size is 1MB. -- To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch. +- To map a large number of email addresses, phone numbers, or their respective hashes, send them in batches with a maximum of 5,000 items per batch. - Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. - Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 696e9f239..a158a5d71 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -28,7 +28,7 @@ If needed, documentation is also available for the previous version: see [POST / Here's what you need to know: - The maximum request size is 1MB. -- To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch. +- To map a large number of email addresses, phone numbers, or their respective hashes, send them in batches with a maximum of 5,000 items per batch. - Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. - Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). From 09127c899739053a0d4676ca2af6356210485886 Mon Sep 17 00:00:00 2001 From: sean wibisono Date: Tue, 31 Mar 2026 16:11:04 +1100 Subject: [PATCH 2/6] remove sequential restriction from Getting Started FAQ section --- docs/getting-started/gs-faqs.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index addc47e1d..65e211411 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -219,10 +219,6 @@ The system should follow the [email normalization rules](gs-normalization-encodi Yes. Not storing mappings might increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. -:::important -Unless you are using a Private Operator, you must map email addresses, phone numbers, or hashes consecutively, using a single HTTP connection, with a maximum batch size of 5,000 items per batch. In other words, do your mapping without creating multiple parallel connections. -::: - #### How should I handle user opt-outs? When a user opts out of UID2-based targeted advertising through the [Transparency and Control Portal](https://www.transparentadvertising.com/), the opt-out signal is sent to DSPs and publishers, who handle opt-outs at bid time. We recommend that advertisers and data providers regularly check whether a user has opted out, via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. From 64e8cfac3c820f3ee7cba78cccc3c2c4cbb05213 Mon Sep 17 00:00:00 2001 From: sean wibisono Date: Tue, 31 Mar 2026 17:28:25 +1100 Subject: [PATCH 3/6] add Rate Limiting section and update Response Status Codes section --- docs/endpoints/post-identity-map-v2.md | 12 +++++++++--- docs/endpoints/post-identity-map.md | 12 +++++++++--- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index ed5674c17..6c0d9406c 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -23,15 +23,20 @@ This documentation is for version 2 of this endpoint, which is not the latest ve If you're using an earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map). For deprecation information, see [Deprecation Schedule: Endpoint Versions](../ref-info/deprecation-schedule.md#endpoint-versions). ::: -## Batch Size and Request Parallelization Requirements +## Batch Size Requirements Here's what you need to know: - The maximum request size is 1MB. - To map a large number of email addresses, phone numbers, or their respective hashes, send them in batches with a maximum of 5,000 items per batch. -- Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. - Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). +## Rate Limiting + +To ensure fair usage and platform stability, the `POST /identity/map` endpoint enforces rate limits to safeguard against bursts of incoming traffic. If you send many requests in quick succession, you might receive `429` error responses. + +To handle rate limit errors gracefully, we recommend implementing [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) with random jitter when retrying requests. To maximize throughput within the limit, use the maximum batch size of 5,000 items per request rather than sending many small requests. + ## Request Format `POST '{environment}/v2/identity/map'` @@ -203,5 +208,6 @@ The following table lists the `status` property values and their HTTP status cod | `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. | +| N/A | 429 | Too many requests to this endpoint. Wait and retry using exponential backoff. | -If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. +If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. Note: 429 responses do not include a JSON response body. diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index a158a5d71..b0df0464e 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -23,15 +23,20 @@ This documentation is for the latest version of this endpoint, version 3. If needed, documentation is also available for the previous version: see [POST /identity/map (v2)](post-identity-map-v2.md). -## Batch Size and Request Parallelization Requirements +## Batch Size Requirements Here's what you need to know: - The maximum request size is 1MB. - To map a large number of email addresses, phone numbers, or their respective hashes, send them in batches with a maximum of 5,000 items per batch. -- Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. - Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). +## Rate Limiting + +To ensure fair usage and platform stability, the `POST /identity/map` endpoint enforces rate limits to safeguard against bursts of incoming traffic. If you send many requests in quick succession, you might receive `429` error responses. + +To handle rate limit errors gracefully, we recommend implementing [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) with random jitter when retrying requests. To maximize throughput within the limit, use the maximum batch size of 5,000 items per request rather than sending many small requests. + ## Request Format `POST '{environment}/v3/identity/map'` @@ -197,8 +202,9 @@ The following table lists the `status` property values and their HTTP status cod | `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. | +| N/A | 429 | Too many requests to this endpoint. Wait and retry using exponential backoff. | -If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. +If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. Note: 429 responses do not include a JSON response body. ## Migration from v2 Identity Map From b447f43ab6e30c8a400a7b8ff99072c4cafc19a1 Mon Sep 17 00:00:00 2001 From: sean wibisono Date: Tue, 31 Mar 2026 17:43:00 +1100 Subject: [PATCH 4/6] add entry to Documentation Updates --- docs/ref-info/updates-doc.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/ref-info/updates-doc.md b/docs/ref-info/updates-doc.md index 4691e371b..f16ce53bf 100644 --- a/docs/ref-info/updates-doc.md +++ b/docs/ref-info/updates-doc.md @@ -24,6 +24,23 @@ Use the Tags toolbar to view a subset of documentation updates. The following documents were released in the first quarter of 2026. + + +### Rate Limiting and Parallel Request Updates for /identity/map + +April 1, 2026 + +The [POST /identity/map](../endpoints/post-identity-map.md) endpoint documentation has been updated with the following changes: + +- Added a new [Rate Limiting](../endpoints/post-identity-map.md#rate-limiting) section documenting that the endpoint enforces rate limits to safeguard against bursts of incoming traffic. +- Removed the previous recommendation to send batches sequentially over a single HTTP connection. + +These changes apply to both [v2](../endpoints/post-identity-map-v2.md) and [v3](../endpoints/post-identity-map.md) endpoints. + + + + + ### Removal of optout_check Parameter From 1164a44df72b61419009b25fd2a89ea08a7cc120 Mon Sep 17 00:00:00 2001 From: swibi-ttd Date: Tue, 7 Apr 2026 09:38:53 +1000 Subject: [PATCH 5/6] Separate note on 429 responses Co-authored-by: Gen Whitt <107279666+genwhittTTD@users.noreply.github.com> --- docs/endpoints/post-identity-map.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index b0df0464e..ca57b90f7 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -204,7 +204,11 @@ The following table lists the `status` property values and their HTTP status cod | `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. | | N/A | 429 | Too many requests to this endpoint. Wait and retry using exponential backoff. | -If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. Note: 429 responses do not include a JSON response body. +If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. + +:::note +429 responses do not include a JSON response body. +::: ## Migration from v2 Identity Map From 571bc25119fad727a2344bd98db6f5fb2ddfa867 Mon Sep 17 00:00:00 2001 From: swibi-ttd Date: Tue, 7 Apr 2026 09:39:22 +1000 Subject: [PATCH 6/6] Add HTTP verb Co-authored-by: Gen Whitt <107279666+genwhittTTD@users.noreply.github.com> --- docs/ref-info/updates-doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ref-info/updates-doc.md b/docs/ref-info/updates-doc.md index f16ce53bf..2fdea7742 100644 --- a/docs/ref-info/updates-doc.md +++ b/docs/ref-info/updates-doc.md @@ -26,7 +26,7 @@ The following documents were released in the first quarter of 2026. -### Rate Limiting and Parallel Request Updates for /identity/map +### Rate Limiting and Parallel Request Updates for POST /identity/map April 1, 2026