Overview

Resolves a token generated using GetToken API, back to its PII value.

Use this API when you already have a tokenized value and need to retrieve the underlying PII, for example, when sending an email or SMS to a user.

HTTP method

POST

Base URL

Use the base URL that matches your account region.

https://vault-endpoint/ct-vault/api/tokenization/getRawValue

Authentication and Headers

To authenticate and process your request, include these headers in every call:

Header	Required	Value
Content-Type	Yes	application/json
Authorization	Yes	Bearer YOUR_ACCESS_TOKEN

📘
Note
To use this API, first authenticate and retrieve an access token. To get your access token, refer to Get Access Token.

Request Body

The following table describes the request fields:

Field	Type	Required	Description
token	String	Yes	Token to resolve. The token must follow the format generated by the tokenization API, for example `TKN_` followed by 8 to 64 alphanumeric characters. Example pattern: `TKN_6F9A1B2C`.
metadata	Object	No	Optional contextual attributes, such as `purpose` or `request_id`. Vault does not use these fields to influence resolution, but may log them for observability or audit. Field names are case sensitive.

Example Request for a Single Token

The following is the sample request for getting PII for a single token:

curl -X POST https://vault-endpoint/ct-vault/api/tokenization/getRawValue \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "555-67-8901"
  }'

import requests

url = "https://in1.api.clevertap.com/api/v1/tokenvault/resolve-token"
headers = {
    "Authorization": "Bearer YOUR_VAULT_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "token": "TKN_6F9A1B2C",
    "metadata": {
        "purpose": "email_dispatch",
        "request_id": "req_789"
    }
}

response = requests.post(url, json=payload, headers=headers)

if response.ok:
    data = response.json()
    print("PII value:", data.get("value"))
    print("Data type:", data.get("dataType"))
    print("Expires in (seconds):", data.get("expires_in"))
else:
    try:
        error = response.json()
    except ValueError:
        error = {"message": response.text}

    print("Request failed")
    print("Status code:", response.status_code)
    print("Error:", error)

const fetch = require("node-fetch");

const url = "https://in1.api.clevertap.com/api/v1/tokenvault/resolve-token";

const headers = {
  "Authorization": "Bearer YOUR_VAULT_API_KEY",
  "Content-Type": "application/json"
};

const body = JSON.stringify({
  token: "TKN_6F9A1B2C",
  metadata: {
    purpose: "email_dispatch",
    request_id: "req_789"
  }
});

fetch(url, {
  method: "POST",
  headers,
  body
})
  .then(async response => {
    const text = await response.text();
    const data = text ? JSON.parse(text) : null;

    if (response.ok) {
      console.log("PII value:", data.value);
      console.log("Data type:", data.dataType);
      console.log("Expires in (seconds):", data.expires_in);
    } else {
      console.error("Request failed with status", response.status);
      console.error("Error body:", data);
    }
  })
  .catch(err => {
    console.error("Network or parsing error:", err);
  });

<?php

$url = "https://in1.api.clevertap.com/api/v1/tokenvault/resolve-token";

$payload = json_encode([
    "token" => "TKN_6F9A1B2C",
    "metadata" => [
        "purpose" => "email_dispatch",
        "request_id" => "req_789"
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_VAULT_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$responseBody = curl_exec($ch);

if ($responseBody === false) {
    $error = curl_error($ch);
    curl_close($ch);
    echo "cURL error: $error\n";
    exit(1);
}

$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Status: $statusCode\n";

$data = json_decode($responseBody, true);

if ($statusCode >= 200 && $statusCode < 300) {
    echo "PII value: " . ($data["value"] ?? "") . "\n";
    echo "Data type: " . ($data["dataType"] ?? "") . "\n";
    echo "Expires in (seconds): " . ($data["expires_in"] ?? "") . "\n";
} else {
    echo "Error response:\n";
    print_r($data);
}

Example Request for Multiple Tokens

The following is the sample request for getting PII for multiple tokens:

curl -X POST http://vault-endpoint/ct-vault/api/tokenization/tokens/values/batch \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": [
      "555-67-8901",
      "987-65-4321",
      "123-45-6789",
      8918663499,
      "999-11-2222"
    ]
  }'

Response Parameters

On success, the API returns HTTP 200 OK and a JSON body with the resolved PII value.

Field	Type	Description
value	String	Original PII value that corresponds to the token, such as an email address or phone number.
dataType	String	Type of the original value, for example `email` or `phone`.
expires_in	Int	Token validity duration in seconds from the time of the response. When this value reaches zero, the token expires and resolution fails with `token_expired`.

Example Response for a Single Token

The following is the sample response for getting PII for a single token:

{
  "value": "[email protected]",
  "dataType": "string",
  "expires_in": 3600
}

Example Response for Multiple Tokens

The following is the sample response for getting PII for multiple tokens:

{
  "results": [
    {
      "token": "555-67-8901",
      "value": "555-12-3456",
      "exists": true,
      "dataType": "string"
    },
    {
      "token": "987-65-4321",
      "value": "234-56-7890",
      "exists": true,
      "dataType": "string"
    },
    {
      "token": "123-45-6789",
      "value": "345-67-8901",
      "exists": true,
      "dataType": "string"
    },
    {
      "token": 8918663499,
      "value": 9870344567,
      "exists": true,
      "dataType": number
    },
    {
      "token": "999-11-2222",
      "value": null,
      "exists": false,
      "dataType": null
    }
  ],
  "summary": {
    "processedCount": 5,
    "foundCount": 4,
    "notFoundCount": 1
  }
}

Error Responses

On error, the API returns a non 2xx HTTP status code and a JSON body that describes the error.

Error Response

This section describes the fields in an error response:

Field	Type	Description
error	String	Machine readable error code.
message	String	Human readable description of the error and how to fix it.
request_id	String	Optional correlation ID for support and debugging.

Example Error Response

{
  "error": "invalid_token",
  "message": "Token format is invalid. Expected pattern TKN_6F9A1B2C.",
  "request_id": "req_789"
}

Error Codes

The following are the error codes and its description:

HTTP	error	Description
400	invalid_token	The request contains a missing, malformed, or improperly formatted token. This occurs when `token` is empty, corrupted, or not in the expected structure.
401	unauthorized	The request cannot be authenticated because the access token in the `Authorization` header is missing, invalid, or expired.
404	token_not_found	The provided token does not have a corresponding stored value in the vault. No mapping exists for the token.
410	token_expired	The token previously existed but passed its validity period and is no longer retrievable. You must re tokenise the original value to generate a new token.
429	rate_limited	The client has sent too many requests in a given period. Reduce request rate or implement backoff before retrying.
500	server_error	The vault service encountered an internal error. Retry the request with exponential backoff. If the issue persists, contact support and include the `request_id` value.

Security Considerations

Follow these guidelines when you use the Vault Resolve API:

Use HTTPS for all requests. Do not send tokens or PII over an unencrypted channel.
Store YOUR_VAULT_API_KEY securely, for example in a secrets manager, not in source control.
Restrict access to the vault API key to services that actually need to resolve tokens.
Avoid logging tokens or raw PII in application logs. If you must log, mask or hash sensitive values.
Use short lived credentials when possible and rotate keys regularly.

Rate Limits

Vault APIs may enforce rate limits per account or per API key.

If you receive HTTP 429 rate_limited, reduce the request rate and implement exponential backoff.
Distribute requests over time rather than sending large bursts.
For current rate limit values that apply to your account, contact your CleverTap representative.

Best Practices

Follow these best practices to ensure reliable, secure, and efficient integration when working with the token resolution workflow.

Validate token format on the client before sending the request, when practical.
Handle token_expired and token_not_found explicitly. Decide whether your application should prompt a re tokenization flow or treat the user as unknown.
Cache non sensitive derived information, not the PII itself, to reduce the number of resolve calls.
Implement robust error handling and logging for non 2xx responses, including request_id where available.
Set reasonable client timeouts so calls do not hang indefinitely. A typical starting point is 5 to 10 seconds, then tune based on your environment.

GetValue API

Overview

HTTP method

Base URL

Authentication and Headers

📘
Note

Request Body

Example Request for a Single Token

Example Request for Multiple Tokens

Response Parameters

Example Response for a Single Token

Example Response for Multiple Tokens

Error Responses

Error Response

Example Error Response

Error Codes

Security Considerations

Rate Limits

Best Practices

Overview

HTTP method

Base URL

Authentication and Headers

📘Note

Request Body

Example Request for a Single Token

Example Request for Multiple Tokens

Response Parameters

Example Response for a Single Token

Example Response for Multiple Tokens

Error Responses

Error Response

Example Error Response

Error Codes

Security Considerations

Rate Limits

Best Practices

📘
Note