Clarify refresh timestamp behavior

Author: vishalegbert-ttd

docs/endpoints/post-identity-map.md

@@ -178,6 +178,10 @@ For successfully mapped DII, the mapped object includes the properties shown in
 | `p`      | string     | One of the following:<ul><li>If the current raw UID2 was rotated in the last 90 days: the previous raw UID2.</li><li>Otherwise: `null`.</li></ul> |
 | `r`      | number     | The Unix timestamp (in milliseconds) that indicates when the raw UID2 might be refreshed. The raw UID2 is guaranteed to be valid until this timestamp. |
 
+:::note
+It is guaranteed that the raw UID2 will not rotate before the refresh timestamp. After the refresh timestamp, when remapping the DII, a new refresh timestamp will be returned but the raw UID2 may not rotate. This is by design to encourage more frequent checks of the opt-out status of the underlying DII. 
+:::
+
 For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table.
 
 | Property | Data Type | Description                                                                                                      |

docs/getting-started/gs-faqs.md

@@ -198,7 +198,7 @@ To determine whether to refresh a raw UID2:
 2. If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling the identity map endpoint again with the same <Link href="../ref-info/glossary-uid#gl-dii">DII</Link>.
 
 :::note
-We recommend checking for refresh opportunities daily. It is guaranteed that the raw UID2 won't refresh before the indicated timestamp. At some point on or after that time, the raw UID2 is refreshed.
+It is guaranteed that the raw UID2 will not rotate before the refresh timestamp. After the refresh timestamp, when remapping the DII, a new refresh timestamp will be returned but the raw UID2 may not rotate. This is by design to encourage more frequent checks of the opt-out status of the underlying DII. We recommend checking for refresh opportunities daily.
 :::
 
 #### How often should raw UID2s be refreshed for incremental updates?

docs/guides/integration-advertiser-dataprovider-endpoints.md

@@ -93,9 +93,11 @@ You could also send conversion information via API or pixels for measurement (at
 
 ### 5: Monitor for Raw UID2 Refresh
 
-A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes roughly once per year as part of the UID2 refresh process.
+A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user rotates roughly once per year as part of the UID2 refresh process.
 
-The v3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data. It is guaranteed that it won't refresh before that time.
+The v3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might rotate. Use this timestamp to determine when to regenerate raw UID2s for your stored data. 
+
+It is guaranteed that the raw UID2 will not rotate before the refresh timestamp. After the refresh timestamp, when remapping the DII, a new refresh timestamp will be returned but the raw UID2 may not rotate. This is by design to encourage more frequent checks of the opt-out status of the underlying DII. 
 
 We recommend checking for refresh opportunities daily. The following table shows the steps for monitoring raw UID2 refresh.
 

docs/guides/integration-advertiser-dataprovider-overview.md

@@ -121,9 +121,11 @@ You could also send conversion information via API or pixels for measurement (at
 
 ### 5: Monitor for Raw UID2 Refresh
 
-A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes roughly once per year as part of the UID2 refresh process.
+A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user rotates roughly once per year as part of the UID2 refresh process.
 
-The v3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data. It is guaranteed that it won't refresh before that time.
+The v3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might rotate. Use this timestamp to determine when to regenerate raw UID2s for your stored data. 
+
+It is guaranteed that the raw UID2 will not rotate before the refresh timestamp. After the refresh timestamp, when remapping the DII, a new refresh timestamp will be returned but the raw UID2 may not rotate. This is by design to encourage more frequent checks of the opt-out status of the underlying DII. 
 
 We recommend checking for refresh opportunities daily. To determine whether to refresh a raw UID2:
 

docs/guides/integration-databricks.md

@@ -142,6 +142,10 @@ The following table provides information about the structure of the output data,
 | `REFRESH_FROM` | timestamp | The value is one of the following:<ul><li>**DII was successfully mapped**: The timestamp indicating when this UID2 should be refreshed.</li><li>**Otherwise**: `NULL`.</li></ul> |
 | `UNMAPPED` | string | The value is one of the following:<ul><li>**DII was successfully mapped**: `NULL`.</li><li>**Otherwise**: The reason why the identifier was not mapped: `OPTOUT`, `INVALID IDENTIFIER`, or `INVALID INPUT TYPE`.<br/>For details, see [Values for the UNMAPPED Column](#values-for-the-unmapped-column).</li></ul> |
 
+:::note
+It is guaranteed that the raw UID2 will not rotate before the refresh timestamp. After the refresh timestamp, when remapping the DII, a new refresh timestamp will be returned but the raw UID2 may not rotate. This is by design to encourage more frequent checks of the opt-out status of the underlying DII. 
+:::
+
 #### Values for the UNMAPPED Column
 
 The following table shows possible values for the `UNMAPPED` column in the output table schema.

docs/guides/integration-snowflake.md

@@ -387,6 +387,10 @@ The following table identifies each item in the response, including `NULL` value
 
 The `FN_T_IDENTITY_MAP_V3` function returns refresh timestamps (`REFRESH_FROM`) that indicate when each UID2 should be refreshed.
 
+:::note
+It is guaranteed that the raw UID2 will not rotate before the refresh timestamp. After the refresh timestamp, when remapping the DII, a new refresh timestamp will be returned but the raw UID2 may not rotate. This is by design to encourage more frequent checks of the opt-out status of the underlying DII. 
+:::
+
 To determine which UID2s need regeneration, compare the current time to the `REFRESH_FROM` timestamps returned by the function.
 
 | Column Name       | Data Type     | Description                                                                                                                                                                                                               |

docs/sdks/sdk-ref-java.md

@@ -332,6 +332,10 @@ For the earlier version, see [Previous SDK Version (using POST /identity/map v2)
        .withHashedPhone("preHashedPhone");
    ```
 
+:::note
+The SDK automatically handles email normalization and hashing, ensuring that raw email addresses and phone numbers do not leave your server.
+:::
+
 3. Call a function that takes the `input` and generates an IdentityMapV3Response object:
    ```java
    IdentityMapV3Response identityMapResponse = identityMapV3Client.generateIdentityMap(input);
@@ -356,7 +360,9 @@ For the earlier version, see [Previous SDK Version (using POST /identity/map v2)
    }
    ```
 
->**Note:** The SDK automatically handles email normalization and hashing, ensuring that raw email addresses and phone numbers do not leave your server.
+:::note
+It is guaranteed that the raw UID2 will not rotate before the refresh timestamp. After the refresh timestamp, when remapping the DII, a new refresh timestamp will be returned but the raw UID2 may not rotate. This is by design to encourage more frequent checks of the opt-out status of the underlying DII. 
+:::
 
 ### Usage Example
 

docs/sdks/sdk-ref-python.md

@@ -255,6 +255,10 @@ To map DII to raw UID2s, follow these steps:
           .with_hashed_phone("pre_hashed_phone")
       ```
 
+:::note
+The SDK automatically handles email normalization and hashing, ensuring that raw email addresses and phone numbers do not leave your server.
+:::
+
 3. Call a function that takes the `input` and generates an `IdentityMapV3Response` object:
    ```py
    identity_map_response = identity_map_v3_client.generate_identity_map(input)
@@ -279,7 +283,7 @@ To map DII to raw UID2s, follow these steps:
    ```
 
 :::note
-The SDK automatically handles email normalization and hashing, ensuring that raw email addresses and phone numbers do not leave your server.
+It is guaranteed that the raw UID2 will not rotate before the refresh timestamp. After the refresh timestamp, when remapping the DII, a new refresh timestamp will be returned but the raw UID2 may not rotate. This is by design to encourage more frequent checks of the opt-out status of the underlying DII. 
 :::
 
 #### Usage Example