- TLC Home Home
- Discussions Discussions
- Documentation Documentation
- Knowledge Base Knowledge Base
- Education Education
- Blog Blog
- Support Desk Support Desk
The Visitor Privacy API (formerly Visitor Lookup API) is used to query visitor profile records from the Customer Data Hub. This API allows you to retrieve known data about a specific visitor, delete a visitor record, and check the status of a delete request.
These requests can also be used in support of General Data Protection Regulation (GDPR) compliance to satisfy the requirement of responding to data subject access requests.
In this article:
Server-side Editor permission within CDH permissions is required for this API. Visitor lookups are based on a Visitor ID attribute from your account.
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.
attributeId
– The numeric ID of this attribute.attributeValue
– The value to search for.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.
See the Getting Started guide to learn about generating a bearer token from the API key.
For a Visitor ID attribute named Email Address with an attribute ID of 86, the attributeID
would be used as a parameter to the API calls, as shown in the following example:
attributeId=86
attributeValue=user@example.com
Visitors are returned as JSON objects that contain the following fields:
Object Name | Type | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
transaction_id |
string |
|
||||||||||||||
live |
Boolean |
|
||||||||||||||
visitor |
object |
The visitor object with sub-objects for each of the attribute data types:
|
{ "transaction_id": "a1b23bcb4b5b56", "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 } } } }
Use the following GET command to retrieve a visitor record:
GET /v2/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
prettyName
curl -H 'Authorization: Bearer {token}' \
-G \
'https://api.tealiumiq.com/v2/visitor/accounts/my_account/profiles/main' \
--data-urlencode 'attributeId=86' \
--data-urlencode 'attributeValue=user@example.com' \
--data 'prettyName=true'
See the example visitor object for the format of the response.
Potential error messages for this task are:
Error Message | Description |
---|---|
404 Not Found |
{ |
{ |
Consider the following prior to deleting one or more visitor records:
application/x-www-form-urlencoded
", and not as query string parameters.Use the following DELETE command to delete a visitor record:
DELETE /v2/visitor/accounts/{account}/profiles/{profile}
attributeID={value}
attributeValue={value}
This command uses the following parameters:
attributeId
attributeValue
curl -H 'Authorization: Bearer {token}' \
-X DELETE \ 'https://api.tealiumiq.com/v2/visitor/accounts/my_account/profiles/main' \
--data-urlencode "attributeId=86"
--data-urlencode "attributeValue=user@example.com"
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}"
}
Potential error messages for this task are:
Error Message | Description |
---|---|
404 Not Found |
{ "returnCode" : 1240, "message" : "Account was not found" } { "returnCode" : 1250, "message" : "Profile was not found" } |
A transaction refers to any GET visitor or 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 /v2/visitor/accounts/{account}/profiles/{profile}/transactions/{transaction_id}
See the 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://api.tealiumiq.com/v2/visitor/accounts/my_account/profiles/main/transactions/0123456789
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" }
Use the following GET command to retrieve a list of the Visitor ID attributes available in your account:
GET /v2/visitor/accounts/{account}/profiles/{profile}/ids
curl -H 'Authorization: Bearer {token}' \ https://api.tealiumiq.com/v2/visitor/accounts/my_account/profiles/main/ids
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" }
Copyright All Rights Reserved © 2008-2023