Tealium API v3 - Visitor Privacy API (formerly Visitor Lookup API)
The Visitor Privacy API (formerly Visitor Lookup API) is used to query visitor profile records from the Customer Data Hub in support of General Data Protection Regulation (GDPR) compliance to satisfy the requirement of responding to data subject access requests.
This API allows you to retrieve known data about a specific visitor, delete a visitor record, and check the status of a delete request.
This article provides information about using the Tealium v3 API. The previous Tealium v2 API is still available, but will eventually be deprecated.
How it works
Visitor lookups are based on a Visitor ID attribute from your account.
Limits and intended use
The Visitor Privacy API is intended to satisfy regulatory requirements such as GDPR and CCPA and is not designed for high volume usage. Tealium recommends that you have a maximum of one (1) connection open to this API at any given time. Contact your account manager if you estimate that your usage will exceed 1000 API calls per day.
Authentication
The bearer token is used to authenticate all API calls and not the API key. The API key is only used in the authentication call. In addition to the bearer token, the authentication response includes a region-specific hostname that must be used in subsequent server-side API calls.
See the Tealium API V3 Getting Started guide to learn about generating a bearer token from the API key.
Visitor fields
Visitors are returned as JSON objects that contain the following fields:
Object Name | Type | Description |
---|---|---|
live |
Boolean | Set to true if the visitor is currently in a live session. |
visitor |
object | The visitor object with sub-objects for each of the attribute data types:
|
Example Response
{
"live": false,
"visitor": {
"metrics": {
"Weeks since first visit": 0.14,
"Total referred visits": 11,
"Lifetime visit count": 12,
"Average visit duration in minutes": 0.36,
"Lifetime event count": 35,
"Total time spent on site in minutes": 4.27,
"Total direct visits": 1
},
"dates": {
"Last visit": 1521217490000,
"last_visit_start_ts": 1521217490000,
"First visit": 1521134626000
},
"properties": {
"Lifetime browser versions used (favorite)": "Chrome",
"Lifetime browser types used (favorite)": "Chrome",
"profile": "main",
"Lifetime devices used (favorite)": "Mac desktop",
"Lifetime platforms used (favorite)": "browser",
"Last event URL": "http://www.tealium.com/",
"account": "tealium",
"Lifetime operating systems used (favorite)": "Mac OS X"
},
"flags": {
"Returning visitor": true
},
"badges": ["Unbadged"],
"metric_sets": {
"Lifetime operating systems used": {
"Mac OS X": 12
},
"Lifetime devices used": {
"Mac desktop": 12
},
"Lifetime browser versions used": {
"Chrome": 12
},
"Lifetime browser types used": {
"Chrome": 12
},
"Lifetime platforms used": {
"browser": 12
}
}
}
}
GET Visitor
Use the following GET command to retrieve a visitor record:
GET /v3/privacy/visitor/accounts/{account}/profiles/{profile}?attributeId={attributeId}&attributeValue={attributeValue}&prettyName={prettyName}
This command uses the following parameters:
attributeId
- The numeric ID representing a Visitor ID attribute from your account.
attributeValue
- The value to look up.
- Values containing special characters must be URL encoded.
prettyName
- A Boolean value indicating how attribute keys display in the response:
- True – Attributes display as user-friendly names, such as “Lifetime Order Value”.
- False – Attributes display as numeric ID’s, such as “28471”.
- A Boolean value indicating how attribute keys display in the response:
You must use the region-specific host returned in the authentication API with this call. For more information, see Getting Started > Region-Specific Host .
Permission requirements
- Server-side reader, editor, or publisher
Example cURL request
curl -H 'Authorization: Bearer {token}' \
-G \
'https://us-east-1-platform.tealiumapis.com/v3/privacy/visitor/accounts/my_account/profiles/main' \
--data-urlencode 'attributeId=86' \
--data-urlencode 'attributeValue=user@example.com' \
--data 'prettyName=true'
Example response
See the example visitor object for the format of the response.
Error messages
Potential error messages for this task are:
Error Message | Description |
---|---|
400 | {"message": "You are missing an attribute Id or Attribute Value"} |
401 | { "message": "Unauthorized"} |
404 | Visitor not found in system { "transactionId": {transactionId} } |
500 | { "message": "Internal Server Error"} |
DELETE visitor
Consider the following prior to deleting one or more visitor records:
- Requests to delete visitor records result in the deletion of all data associated to the visitor ID value, including stitched visitor records.
- Delete requests are queued for processing and may take up to 1-4 days to complete.
- If a visitor replaces or has been replaced by another visitor, all visitors that have been stitched are deleted.
- The parameters to the DELETE command must be passed as URL-encoded form fields using the content-type "
application/x-www-form-urlencoded
", and not as query string parameters.
Use the following DELETE command to delete a visitor record:
DELETE /v3/visitor/privacy/accounts/{account}/profiles/{profile}
attributeID={value}
attributeValue={value}
This command uses the following parameters:
attributeId
The numeric ID representing a Visitor ID attribute from your account.attributeValue
The value to look up.
You must use the region-specific host returned in the authentication API with this call. For more information, see Getting Started > Region-Specific Host.
Permission requirements
- Server-side publisher
Example cURL request
curl -H 'Authorization: Bearer {token}' \
-X DELETE \
'https://us-east1-platform.tealiumapis.com/v3/privacy/visitor/accounts/my_account/profiles/main' \
--data-urlencode "attributeId=86"
--data-urlencode "attributeValue=user@example.com"
Example response
The response to a delete request includes a transaction_id
and a status. The transaction_id
is used in the GET transactions call to check the status of a previous request. The following status strings are possible: PENDING, SUCCESS, or FAILED.
A successful response displays the 202 Accepted message with a transactionId
value. If a request with the exact same account
, profile
, attributeId
, and attributeValue
already exists with a transaction status of PENDING, the existing transaction ID is returned, as follows:
{
"transactionId" : "{transactionId1}"
}
Error messages
Potential error messages for this task are:
Error Message | Description |
---|---|
400 | {"message": "You are missing an attribute Id or Attribute Value"} |
401 | { "message": "Unauthorized"} |
404 | Visitor not found in system { "transactionId": {transactionId} } |
GET transaction
A transaction refers to any DELETE visitor request. DELETE visitor requests are queued for later processing, which makes the transaction_id
the unique record for that request and ID to be used when checking the processing status.
Use the following GET command to check the status of a transaction:
GET /v3/privacy/visitor/accounts/{account}/profiles/{profile}/transactions/{transaction_id}
Permission requirements
- Server-side reader, editor, or publisher
Example cURL request
See the Tealium API V3 Getting Started guide to learn about generating a bearer token from the API key. The bearer token is used in the API calls, rather than the API key.
curl -H 'Authorization: Bearer {token}' \
https://platform.tealiumapis.com/v3/privacy/visitor/accounts/my_account/profiles/main/transactions/0123456789
Example response
The response contains an object with one key/value pair where the key is a transaction_id
and the value is one of the following status strings: PENDING, SUCCESS, or FAILED.
{
"0123456789" : "SUCCESS"
}
Error messages
Potential error messages for this task are:
Error Message | Description |
---|---|
401 | { "message": "Unauthorized"} |
404 | Visitor not found in system { "transactionId": {transactionId} } |
GET Visitor ID Attributes
Use the following GET command to retrieve a list of the Visitor ID attributes available in your account:
GET /v3/privacy/visitor/accounts/{account}/profiles/{profile}/ids
Permission requirements
- Server-side reader, editor, or publisher
Example cURL request
curl -H 'Authorization: Bearer {token}' \
https://platform.tealiumapis.com/v3/privacy/visitor/accounts/my_account/profiles/main/ids
Example response
The response for this command is an object of key/value pairs representing the numeric ID and name of the Visitor ID attribute.
{
"43" : "Email Address",
"57" : "Tax ID Number"
}
Error messages
Potential error messages for this task are:
Error Message | Description |
---|---|
401 | { "message": "Unauthorized"} |
404 | { "message" : "No Visitor ids were found for the account and profile"} |
500 | { "message" : "Internal Server Error"} |
This page was last updated: May 31, 2023