Tealium API v3 - Visitor Privacy API (formerly Visitor Lookup API)

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 Visitor Privacy 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. We recommend 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.

Rate Limits

The Visitor Privacy API has a default rate limit of 50 requests/second.

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:

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”.

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:

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:

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:

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: