Visitor Profile API — V3 Early Access
The Visitor Profile API is used to query visitor profile records from the Customer Data Hub. Retrieve known data about a specific visitor to improve personalization for first time visitors to your website.
How it works
Visitor lookups are based on a Visitor ID attribute from your account.
Rate Limits
The Visitor Profile API has a default rate limit of 150 requests/second. If you need a higher rate limit, contact your Tealium account manager with your projected usage.
Permission Requirements
Server-side reader, editor, or publisher.
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
},
"funnels": {
"fake_funnel": {
"completed": true,
"fake_title": {
"timestamp": 1655303842639,
"snapshot": {
"fake_string": "fake_string",
"Average visits per week": 1.0
}
}
},
"pii_funnel": {
"completed": true,
"step2": {
"timestamp": 1655303842639,
"snapshot": {
"pii_string": "Example string",
"First visit": 1655303836000,
"Last event URL": "http://172.16.3.15:8000/datacloudtest.html"
}
},
"step1": {
"timestamp": 1655303842639,
"snapshot": {
"pii_string": "Example string"
}
}
}
},
"sequences": {
"fake_timeline": [
{
"timestamp": 1655303842639,
"snapshot": {}
},
{
"timestamp": 1655303842642,
"snapshot": {}
},
{
"timestamp": 1655303842652,
"snapshot": {}
},
{
"timestamp": 1655303842654,
"snapshot": {}
},
{
"timestamp": 1655303842665,
"snapshot": {}
}
]
},
"audiences": [
"fake_visitors"
],
"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/customer/visitor/accounts/{account}/profiles/{profile}?attributeId={attributeId}&attributeValue={attributeValue}&prettyName={prettyName}&responseFilters=["{attributeId}", "{attributeId}"]
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 appear 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 appear in the response:
searchPriority- The data source for your request, passed as a JSON string array. The default is
["live", "historical"].["live"]– Fetches live data from your website about current visitors.["historical"]— Fetches historical data from your website about completed visits after a 30 minute waiting period.["live", "historical"]— The API will attempt to fetch live visitor data. If no live visitor data is available, the API will fetch historical visitor data.["historical", "live"]— The API will attempt to fetch historical visitor data. If no historical data is available, the API will fetch live visitor data.
- The data source for your request, passed as a JSON string array. The default is
responseFilters- A JSON array of IDs for filtering visitor data. If left unset, the API will return all the visitor data. When set, the
attributeIdvalues included inresponseFilterswill be returned in the response. - The maximum number of
attributeIdvalues that the API will return at one time is 150. If you provide more than 150attributeIdvalues, the API will return only the first 150 IDs. - Example:
responseFilters=["5051", "5016"]
- A JSON array of IDs for filtering visitor data. If left unset, the API will return all the visitor data. When set, the
You must use the region-specific host returned in the authentication API with this call. For more information, see Getting Started > Region-Specific Host .
Example cURL request
curl --location -g --request \
GET 'https://us-east-1-platform.tealiumapis.com/v3/customer/visitor/accounts/my_account/profiles/profileinuseast?attributeId=5013&attributeValue=liveOnly&searchPriority=["live", "historical"]&responseFilters=["5051", "5016"]' \
--header 'Authorization: Bearer fakeToken'
Example response
See the example visitor object for the format of the response.
Error messages
Potential error messages for this include the following:
| ERROR MESSAGE | DESCRIPTION |
|---|---|
| 400 | {"message": "You are missing an attribute Id or Attribute Value"} |
| 401 | {"message": "Unauthorized"} |
| 404 | Visitor was not found, empty response.{"message": "Invalid query parameter value for 'searchPriority' detected."} |
GET Historical Visitor
The GET Historical Visitor method is optimized for faster response times by searching only historical visitors.
Use the following GET command to retrieve a historical visitor record:
GET /v3/customer/visitor/historical/accounts/{account}/profiles/{profile}?attributeId={attributeId}&attributeValue={attributeValue}&prettyName={prettyName}&responseFilters=["{attributeId}", "{attributeId}"]
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”.
responseFilters- A JSON array of IDs for filtering visitor data. If left unset, the API will return all the visitor data. When set, the
attributeIdvalues included inresponseFilterswill be returned in the response. The maximum number ofattributeIdvalues that the API will return at one time is 150. If you provide more than 150attributeIdvalues, the API will return only the first 150 IDs.
- A JSON array of IDs for filtering visitor data. If left unset, the API will return all the visitor data. When set, the
You must use the region-specific host returned in the authentication API with this call. For more information, see Getting Started > Region-Specific Host .
Example cURL request
curl --location -g --request \
GET 'https://us-east-1-platform.tealiumapis.com/v3/customer/visitor/historical/accounts/my_account/profiles/profileinuseast?attributeId=5013&attributeValue=liveOnly&responseFilters=["5051", "5016"]' \
--header 'Authorization: Bearer fakeToken'
Example response
See the example visitor object for the format of the response.
Error messages
Potential error messages for this endpoint:
| ERROR MESSAGE | DESCRIPTION |
|---|---|
| 400 | {"message": "You are missing an attribute Id or Attribute Value"} |
| 401 | {"message": "Unauthorized"} |
| 404 | Visitor was not found, empty response. |
This page was last updated: June 2, 2023