From c3d75cbef6fb7eaf4ed51dbf6257b8d80ee8b1ea Mon Sep 17 00:00:00 2001 From: vishal egbert Date: Thu, 4 Dec 2025 11:38:05 +1100 Subject: [PATCH 1/4] Update /token/validate docs --- docs/endpoints/post-token-validate.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/endpoints/post-token-validate.md b/docs/endpoints/post-token-validate.md index 635719cf8..c101eecad 100644 --- a/docs/endpoints/post-token-validate.md +++ b/docs/endpoints/post-token-validate.md @@ -45,11 +45,11 @@ The integration environment and the production environment require different
  • The only valid value is: `validate@example.com`. | -| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation (`validate@example.com`).
    The only valid value is: `ntI244ZRTXwAwpki6/M5cyBYW7h/Wq576lnN3l9+W/c=`. | -| `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens.
    The only valid value is: `+12345678901`. | -| `phone_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hash of a [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number.
    The only valid value is: `EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=`. | +| `token` | string | Required | The advertising token returned by the [POST /token/generate](post-token-generate.md) response.

    You may only validate advertising tokens that have been generated with your own credentials. | +| `email` | string | Conditionally Required | The email address for token validation. | +| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation. | +| `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens. | +| `phone_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hash of a [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number. | ### Request Examples @@ -111,7 +111,7 @@ A successful decrypted response returns a boolean value that indicates the valid | Property | Data Type | Description | | :--- | :--- | :--- | -| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.
    A value of `false` indicates any of the following:
    - The request included an invalid advertising token.
    - The email address, phone number, or the respective hash specified in the request is not one of the four valid values specified in the [Unencrypted JSON Body Parameters](#unencrypted-json-body-parameters) table. | +| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.

    A value of `false` indicates that the email address, phone number, or the respective hash specified in the request is not the same as the oned used to generated the advertising token. | ### Response Status Codes @@ -120,7 +120,7 @@ The following table lists the `status` property values and their HTTP status cod | 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.| +| `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. @@ -129,8 +129,7 @@ If the `status` value is anything other than `success`, the `message` field prov You can use this endpoint to test whether the DII that you are sending through [POST /token/generate](../endpoints/post-token-generate.md) is valid. Follow these steps. -1. Depending on whether the DII is a hashed or unhashed email address or phone number, send a [POST /token/generate](../endpoints/post-token-generate.md) request using one of the four valid options listed in the [Unencrypted JSON Body Parameters](#unencrypted-json-body-parameters) table—`email`, `email_hash`, `phone`, or `phone_hash`—with the corresponding value as listed in the table. - +1. Send a [POST /token/generate](../endpoints/post-token-generate.md) request using an `email`, `email_hash`, `phone` or `phone_hash` to generate an advertising token to validate. 2. Store the returned `advertising_token` value for use in the next step. 3. Send a `POST /token/validate` request using the `email`, `email_hash`, `phone`, or `phone_hash` value that you sent in Step 1, with the `advertising_token` that you saved in Step 2 as the `token` property value. 4. Check the response to the `POST /token/validate` request. The results indicate the success of your process, as follows: From 9c55516fcadc3cf4b7694787c29208be78242114 Mon Sep 17 00:00:00 2001 From: vishal egbert Date: Fri, 5 Dec 2025 21:51:39 +1100 Subject: [PATCH 2/4] Address feedback --- docs/endpoints/post-token-validate.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/endpoints/post-token-validate.md b/docs/endpoints/post-token-validate.md index c101eecad..15bde3c88 100644 --- a/docs/endpoints/post-token-validate.md +++ b/docs/endpoints/post-token-validate.md @@ -45,7 +45,7 @@ The integration environment and the production environment require different

  • You may only validate advertising tokens that have been generated with your own credentials. | +| `token` | string | Required | The advertising token returned by the [POST /token/generate](post-token-generate.md) response.
    You can only validate advertising tokens that have been generated with your own credentials. | | `email` | string | Conditionally Required | The email address for token validation. | | `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation. | | `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens. | @@ -111,7 +111,7 @@ A successful decrypted response returns a boolean value that indicates the valid | Property | Data Type | Description | | :--- | :--- | :--- | -| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.

    A value of `false` indicates that the email address, phone number, or the respective hash specified in the request is not the same as the oned used to generated the advertising token. | +| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.

    A value of `false` indicates that the email address, phone number, or the respective hash specified in the request is not the same as the one used to generated the advertising token. | ### Response Status Codes From e91dbd197cc11e030fae151e0d48c2a84eb2d485 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Fri, 5 Dec 2025 10:33:53 -0500 Subject: [PATCH 3/4] minor updates --- docs/endpoints/post-token-validate.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/endpoints/post-token-validate.md b/docs/endpoints/post-token-validate.md index 15bde3c88..57cb47108 100644 --- a/docs/endpoints/post-token-validate.md +++ b/docs/endpoints/post-token-validate.md @@ -40,16 +40,18 @@ The integration environment and the production environment require different
  • You can only validate advertising tokens that have been generated with your own credentials. | -| `email` | string | Conditionally Required | The email address for token validation. | -| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation. | -| `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens. | -| `phone_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hash of a [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number. | +| `token` | string | Required | The advertising token returned by the [POST /token/generate](post-token-generate.md) response.
    You can only validate an advertising token that has been generated with your own credentials. +| `email` | string | Conditionally Required | The email address for token validation. You can use any valid email value, normalized or not. | +| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of any valid [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address. | +| `phone` | string | Conditionally Required | The phone number for which to generate tokens. You can use any valid phone number value, but it must be [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization). | +| `phone_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hash of any valid [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number. | ### Request Examples @@ -109,9 +111,11 @@ A successful decrypted response returns a boolean value that indicates the valid ## Body Response Properties +The following table provides information about the response body. + | Property | Data Type | Description | | :--- | :--- | :--- | -| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.

    A value of `false` indicates that the email address, phone number, or the respective hash specified in the request is not the same as the one used to generated the advertising token. | +| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.
    A value of `false` indicates that the email address, phone number, or the respective hash specified in the request is not the same as the one used to generated the advertising token. | ### Response Status Codes From 0d1150e8ca1388663904cbc9ec9b973a180c927c Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Fri, 5 Dec 2025 11:07:03 -0500 Subject: [PATCH 4/4] minor updates --- docs/endpoints/post-token-validate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/endpoints/post-token-validate.md b/docs/endpoints/post-token-validate.md index 57cb47108..91903a7fb 100644 --- a/docs/endpoints/post-token-validate.md +++ b/docs/endpoints/post-token-validate.md @@ -50,7 +50,7 @@ Here are some key points about using this endpoint: | `token` | string | Required | The advertising token returned by the [POST /token/generate](post-token-generate.md) response.
    You can only validate an advertising token that has been generated with your own credentials. | `email` | string | Conditionally Required | The email address for token validation. You can use any valid email value, normalized or not. | | `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of any valid [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address. | -| `phone` | string | Conditionally Required | The phone number for which to generate tokens. You can use any valid phone number value, but it must be [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization). | +| `phone` | string | Conditionally Required | The phone number for token validation. You can use any valid phone number value, but it must be [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization). | | `phone_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hash of any valid [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number. | ### Request Examples