Endpoint Specification
Learn to send data to the Tealium Customer Data Hub using the HTTP API for events.
This article provides the specification for the direct HTTP endpoint, which is used in any application that sends HTTP requests.
Tealium Collect URL
Tealium Collect is located at the following root URL:
https://collect.tealiumiq.com/event
Sessions are determined based on the Visit scope attribute property.
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. See About data sources for more information.
- 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 section 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. For more information about event attributes, see Using attributes.
Visitor ID attribute
If you are using Tealium AudienceStream you must pass a known visitor ID attribute (user identifier) with each tracking call, such as email_address
or login_id
.
If the events do not contain a visitor ID attribute then each event generates a new visit and visitor, making stitching not possible. This is important if using the Collect API on a web platform where you might be tracking anonymous users.
A visitor ID attribute is also needed if you are using Tealium EventStream and need to provide an ID to a vendor connector.
Learn more about the visitor ID attribute.
Anonymous ID
The tealium_visitor_id
attribute is an anonymous ID 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, use one of the following approaches:
Known Visitors
(Required for AudienceStream, recommended for EventStream)
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.
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.
{
"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
(Required for AudienceStream)
When tracking events for an anonymous visitor from a website (without a known ID), then the value of the tealium_visitor_id
needs to match the value in the utag_main_v_id
cookie.
Learn more about the built-in variables from utag.js
.
Visitor switching
When a first-party cookie is unavailable, the server side uses incoming data in the following order of precedence to determine the ID of a visitor:
- The
TAPID
cookie, also called thetealium_thirdparty_visitor_id
- The
tealium_visitor_id
- The
utag_main v_id
, also called thetealium_firstparty_visitor_id
Because AudienceStream gives the ID in TAPID
precedence over other IDs to determine the visitor profile to use, this can cause problems with tracking multiple users on the same device.
For example, if a user logs in and their ID is added to the TAPID
, traffic from all the anonymous users on the device are logged to that user. And if a second user logs in to that device, assuming that the anonymous cookie is not cleared, AudienceStream will continue log activity to the first user. If the visitors use a shared smart television or a public kiosk, this can cause contamination of data in the visitors’ profiles.
Use the following parameters to control how the endpoint handles the tealium_visitor_id
and tealium_thirdparty_visitor_id
values in the event:
Parameter | Type | Description |
---|---|---|
tealium_override_tapid |
string | Override tealium_visitor_id and tealium_thirdparty_visitor_id with this value. |
tealium_skip_3rd_party_vid_cookies |
boolean | Set to true to skip collecting the TAPID third-party cookie. |
tealium_delete_3rd_party_vid_cookies |
boolean | Set to true to delete the TAPID third-party cookie. |
- A
tealium_override_tapid
value prevents thetealium_delete_3rd_party_vid_cookies
parameter from deleting the cookie. - If removing the
account/profile
information from TAPID empties that cookie,set-cookie maxAge=0
is returned to delete that cookie from the client.
Methods
GET
The GET method is used to request data from a specified resource. It passes data using key-value pairs in the query string of the endpoint, and 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"
POST
The POST method is used to send data to a server to create/update a resource. It 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.
Example of user_login
event:
{
"tealium_account" : "ACCOUNT",
"tealium_profile" : "PROFILE",
"tealium_event" : "EVENT_NAME",
"email_address" : "EMAIL_ADDRESS"
}
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
Status codes
The following table summarizes Tealium’s HTTP response status codes:
Status Code | Description |
---|---|
200 Status OK |
The request succeeded |
400 Bad Request |
The server does not understand the request |
The 400 Bad Request
status code occurs when at least of the following is true:
- The JSON key contains a period, is invalid, or exceeds 1 MB in size
- The file-type parameter contains a value other than “json” or “javascript”
- The combination of
account
,profile
, anddatalayer_id
exceeds 250 characters in length, or contains restricted characters tealium_account
ortealium_profile
is missing, or contains typographical errors- The request body is empty
The following is an example of a 400 Bad Request
response, shown in the X-Error
header, when the required tealium_account
or tealium_profile
parameter values are missing:
> GET /event?tealium_account=jentest-as&tealium_profile=&tealium_visitor_id=sendgeteventhttps@testing.com&tealium_datasource=utc2cj&customer_city=Honolulu&customer_state=Hawaii&Flag=true&Number=45&String=ascent&String_Array=[hello,howareyou,whatsup,yoyoyo]&Number_Array=[2.222,3.000,19.12,28.3]&Flag_Array=[true,false,false,true]&Combo_Array=[1,salutations,2324,world,22jjfssl]&Array_of_Array=[[1,2,3],heyworld]&myvariable=unicorns HTTP/1.1
> Host: qa21-collect.tealiumiq.com
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 400 Bad Request
< Cache-Control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< Content-Type: application/json
< Date: Wed, 23 Oct 2019 17:10:51 GMT
< Expires: Wed, 23 Oct 2019 17:10:51 GMT
< P3P: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< Pragma: no-cache
< Vary: Origin
< X-Error: Missing required tealium_account or tealium_profile param value
< X-Region: us-east-1
< X-ServerID: uconnect_i-9a157d19
< X-ULVer: 1.0.331-SNAPSHOT
< X-UUID: d4fc78d1-8204-412c-a6cb-57869d2370a7
< Content-Length: 0
< Connection: keep-alive
Examples
HTML example
Tealium Collect is 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, as shown in the following example:
var cb=Math.random()*100000000000;
This variable is 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, allowing you to send a POST from your website to our domain, as shown in the following example:
var event = {
"tealium_account" : "ACCOUNT",
"tealium_profile" : "PROFILE",
"tealium_event" : "EVENT_NAME",
"email_address" : "EMAIL_ADDRESS"};
var xhr = new XMLHttpRequest();
xhr.open("POST", "https://collect.tealiumiq.com/event");
xhr.send(JSON.stringify(event));
The Response Headers include the following:
Access-Control-Allow-Origin: [http://your_domain.com](http://your_domain.com)
This page was last updated: January 9, 2023