Visitor Lookup API

Visitor Lookup API

by on ‎03-26-2018 04:51 PM - edited 3 weeks ago (1,682 Views)

The Visitor Lookup API is used to query visitor profile records from the Universal Data Hub (UDH). These requests are offered 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.

In this article:

Table of Contents Placeholder 

How It Works

While this API is only used for AudienceStream and DataAccess accounts, the permissions needed to access this API are controlled in Tealium iQ.

Required permission to use this API:

  • Save/Save as

Visitor lookups are based on a Visitor ID attribute from your account. The numeric ID of this attribute and the value to search for are the required parameters, named attributeId and attributeValue , respectively. For example, you might have a Visitor ID attribute named "Email Address" with an attribute ID of "86". This attribute ID would be used as a parameter to the API calls, as shown in the following example:

attributeId=86&attributeValue=user@example.com

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 24 hours to complete.

Visitor Fields

Visitors are returned as JSON objects that contain the following fields:

Object Name Type Description
transaction_id string A unique ID returned in every response for logging purposes and the status API.
live Boolean True if the visitor has a live session right now.
 visitor object

The visitor object with sub-objects for each of the attribute data types:

  • Visitor IDs:
    secondary_ids : { }
  • Numbers/Array of Numbers:
     "metrics" : { }
    "metric_lists" : { }
  • Strings/Array of Strings/Set of Strings:
    "properties" : { }
    "property_lists" : { }
    "property_sets" : { }
  • Booleans/Array of Booleans:
    "flags" : { }
    "flag_lists" : { }
  • Dates:
     "dates" : { }
  • Badges:
     "badges" : { }
  • Tallies:
     "metric_sets" : { }

Example

{
    "transactionId": "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
            }
        }
    }
}

Get Visitor

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: 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 appear as user-friendly names, eg. "Lifetime Order Value"
    • false: attributes appear as numeric ID's, eg. "28471"

Example Curl Request

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'

Example Response

See the example visitor object below for the format of the response.

Error Messages

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"
}

Delete Visitor

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 24 hours to complete. If a visitor replaces or has been replaced by another visitor, all visitors that have been stitched are deleted.

When deleting a visitor record using the selected attributes action in the AudienceStore connector, only the tealium_id is affected. This action does not purge the assigned visitor id (secondary id).

The response to a delete request will include 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, FAILED. A delete request will likely remain in PENDING status for 3-4 days. 

Use the following DELETE command to delete a visitor record:

DELETE /v2/visitor/accounts/{account}/profiles/{profile}
attributeID={value}
attributeValue={value}

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.

This command uses the following parameters:

  • attributeId: the numeric ID representing a Visitor ID attribute from your account
  • attributeValue: the value to look up

Example Curl Request

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"

Example Response

The success 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:
 {
  "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" 
}

Get Transaction

A transaction refers to any GET visitor or DELETE visitor request. Since the DELETE visitor requests are queued for later processing, the transaction_id is your unique record for that request and is used to check 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}

Example Curl Request

curl -H 'Authorization: Bearer {token}' \ 
https://api.tealiumiq.com/v2/visitor/accounts/my_account/profiles/main/transactions/0123456789

Example Response

The response will contain 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, FAILED.

{
  "0123456789" : "SUCCESS"
}

Get Visitor ID Attributes

To retrieve a list of the Visitor ID attributes available in your account, use the GET visitor IDs command:

GET /v2/visitor/accounts/{account}/profiles/{profile}/ids

Example Curl Request

curl -H 'Authorization: Bearer {token}' \ 
https://api.tealiumiq.com/v2/visitor/accounts/my_account/profiles/main/revisions/ids

Example Response

The response for this command is an object of key/value pairs representing the he numeric ID and name of the Visitor ID attribute.

{
  "43" : "Email Address",
"57" : "Tax ID Number" }