Tealium Visitor Privacy API endpoints

The Visitor Privacy API allows you to retrieve known data about a specific visitor, delete a visitor record, and check the status of a delete request.

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}

GET visitor parameters

This command uses the following parameters:

parameter type description
attributeId string The numeric ID representing a Visitor ID attribute from your account.
attributeValue string The value to look up. Values containing special characters must be URL encoded.
prettyName boolean 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.

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 for the format of the response.

Error messages

Potential error messages for this task are:

Error code Error message
404 “returnCode” : 1240, “message” : “Account was not found”
404 “returnCode” : 1250, “message” : “Profile was not found”

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 /v2/visitor/accounts/{account}/profiles/{profile}
  attributeID={value}
  attributeValue={value}

DELETE visitor parameters

This command uses the following parameters:

parameter type description
attributeId string The numeric ID representing a Visitor ID attribute from your account.
attributeValue string The value to look up. Values containing special characters must be URL encoded.

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 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 code Error message
404 “returnCode” : 1240, “message” : “Account was not found”
404 “returnCode” : 1250, “message” : “Profile was not found”

GET transaction

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}

Example cURL request

Read about API authentication to learn how to generate 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

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

GET visitor ID attributes

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

Example cURL request

curl -H 'Authorization: Bearer {token}' \ 
https://api.tealiumiq.com/v2/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"
}

Was this page helpful?

This page was last updated: January 7, 2023