Tealium Collect HTTP API

[#1]

This document describes how to send data to the Customer Data Hub using the HTTP API for events. This article provides the specification for the direct HTTP endpoint, which can be used in any application that can send HTTP requests.

In this article:

Table of Contents Placeholder 

Request Format

Tealium Collect is an HTTP endpoint that supports GET and POST methods.

Root URL

Tealium Collect is located at the following root URL: 

https://collect.tealiumiq.com/event

Standard Parameters

Tealium Collect supports the following standard parameters in each request:

• tealium_account - the name of your Tealium account
• tealium_profile - the name of your Tealium profile (default "main")
• tealium_datasource - (optional) the data source key from Customer Data Hub (learn more about Data Sources)
• tealium_event - (recommended) the name of the event for tracking purposes
• tealium_visitor_id - (required for AudienceStream) an anonymized and unique identifier for the visitor associated with the event (see Visitor Identifiers below)
• tealium_trace_id - (optional) for use with Trace

The format of the request will vary depending on the HTTP method used. In the examples below placeholder values are represented with curly braces in the following format: {VALUE}.

Custom Event Parameters

Additional event attributes are sent as custom parameters according to your tracking needs. These parameters should also be defined as event attributes in the Customer Data Hub.

Visitor Identifiers

If you are using AudienceStream you must pass a known visitor identifier attribute (secondary ID) with each tracking call (e.g. email_address or login_id). If the events do not contain a visitor identifier each event will generate a new visit and visitor and stitching will not be possible. This is especially important if using the Collect API on a web platform where you might be tracking anonymous users.

A visitor identifier is also needed if you are using EventStream and need to provide an ID to a vendor connector.

Learn more about what makes a good visitor identifier in the Visitor ID Attribute article.

Primary Visitor ID

The tealium_visitor_id attribute is an anonymous identifier used by AudienceStream to associate a visitor between events and visits. This value should be a GUID (Globally Unique Identifier).

Depending on your usage of the Collect API, you can use one of the following approaches:

• Known Visitors (Recommended)
  When tracking events for a known visitor (when a value exists for a Visitor ID attribute such as email_address), include a concatenation of the account, profile and the known visitor ID attribute ID and value, and a SHA256 hash of that concatenated value in the tealium_visitor_id parameter.
  

  AudienceStream	EventStream
  Required	Recommended

  
  

  To use a hash of an email address for the primary Visitor ID, we recommend creating a unique hashed ID that includes the account, profile, and email address. 

  
  Example:
  

  {
      "tealium_account"    : "my_account",
      "tealium_profile"    : "main",
      "tealium_event"      : "user_login",
      "email_address"      : "user@example.com",
      // SHA256 Hash of my_account_main_5102_user@example.com
      "tealium_visitor_id" : "bad8145f125e0560d07872e77e98bc9cd8b7b763a4577adbbf52bfd7b164223e"
  }

• Anonymous Visitors
  When tracking events for an anonymous visitor from a website (without a known identifier), then the value of the tealium_visitor_id will need to match the value in the utag_main_v_id cookie. (Learn more about the built-in variables from utag.js.)
  

  AudienceStream	EventStream
  Required	N/A

POST Method

The POST method supports JSON payloads where the request header must be set to Content-Type: application/json and the payload must be formatted as a valid JSON string. 

Let's use the following "user_login" event for our examples:

{
    "tealium_account"   : "{ACCOUNT}",
    "tealium_profile"   : "{PROFILE}",
    "tealium_event"     : "user_login",
    "email_address"     : "user@example.com"
}

Example using curl:

curl -X POST -H 'Content-type: application/json' \
  --data '{"tealium_account":"{ACCOUNT}","tealium_profile":"{PROFILE}","tealium_event":"user_login","email_address":"user@example.com"}' \
  https://collect.tealiumiq.com/event

GET Method

The GET method passes data using key/value pairs in the query string of the endpoint. This method returns a 1x1 transparent GIF to make it compatible with HTML-based implementations.

Example using curl:

curl -i -X GET "https://collect.tealiumiq.com/event?tealium_account={ACCOUNT}&tealium_profile={PROFILE}&tealium_event=user_login&email_address=user@example.com" 

Usage Examples

HTML

Tealium Collect can be referenced in an <img> tag within your HTML. Due to browser caching it's important to include a cache buster, an additional parameter that contains a randomly generated value.

Example cache  buster:

var cb=Math.random()*100000000000;

This variable would be added to the query string of the Tealium Collect pixel:

<img height="1" width="1" style="display:none" src="//collect.tealiumiq.com/event?tealium_account={ACCOUNT}&tealium_profile={PROFILE}&tealium_event=user_login&email_address=user@example.com&cb=' + cb + '"/>

JavaScript

Tealium Collect supports cross-domain requests, so you can send a POST from your website to our domain. The Response Headers will include the following:  Access-Control-Allow-Origin: http://your_domain.com

var event = {
   "tealium_account" : "{ACCOUNT}",
   "tealium_profile" : "{PROFILE}",
   "tealium_event"   : "user_login",
   "email_address"   : "user@example.com"
};

var xhr = new XMLHttpRequest();
xhr.open("POST", "https://collect.tealiumiq.com/event");
xhr.send(JSON.stringify(event));