Endpoint Specification

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 UDH (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 UDH.

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.  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 the known visitor ID attribute and a hash of that value in the tealium_visitor_id parameter.
  

  AudienceStream	EventStream
  Required	Recommended

  Example:
  

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

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

HTML Example

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 Example

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](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));