Endpoint Specification

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

Rate limits

The Tealium Collect API supports a maximum rate limit of 100 requests/second.

If your business needs require higher call limits, contact your Tealium account manager.

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. The default is 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](#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 About attributes.

Visitor identifiers

AudineceStream tracks visitors using a combination of:

• Primary visitor ID: Used to track the visitor anonymously.
• Secondary visitor ID: Sent additionally once the visitor is known.

Primary visitor ID

The primary visitor ID is an anonymous identifier used by AudienceStream to associate a visitor between events and visits. This value should be a GUID (Globally Unique Identifier) and should be consistent for the visitor.

The key name of the primary visitor ID is tealium_visitor_id.

Depending on your business case, you can use anonymous visitors or known visitors.

Anonymous visitors

If you are using TealiumiQ Tag Management and sending API calls server-to-server to enrich anonymous visitor profiles, then the value of the tealium_visitor_id must match the value in the utag_main_v_id cookie. For more information about the built-in variables from utag.js, see JavaScript (Web) > Data Layer.

If you are using Adobe Launch or Google Tag Manager, then the value needs to match the v part of the TEAL cookie.

Known visitors server-to-server

When sending data for known visitors (when a value exists for a Visitor ID attribute such as email_address), include a concatenation of the account, profile, visitor ID attribute ID and value and the value in the tealium_visitor_id parameter.

You can find the visitor ID attribute ID next to the attribute name in the attribute list or within the expanded details. For more information, see About Attributes.

For example, for the following values:

• Account name: my-account
• Profile: main
• Visitor ID attribute ID: 7688
• Customer number value you want to pass: 45653454

you would concatenate these values in the following way:

tealium_visitor_id":"__my-account_main__7688_45653454__"

Ensure that your tealium_visitor_id is formatted correctly before proceeding. Incorrectly formed parameters will cause errors in AudienceStream and may not track properly.

Example JSON:

{
    "tealium_account"    : "my-account",
    "tealium_profile"    : "main",
    "tealium_event"      : "user_login",
    "email_address"      : "user@example.com",
    "tealium_visitor_id" : "__my-account_main__7688_45653454__"
}

Whether you use anonymous visitors or known visitors, if your API calls do not contain a consistent tealium_visitor_id, each event will generate a new visit and visitor stitching will not be possible.

Secondary ID

When using AudienceStream, you can pass a known visitor identifier attribute, a secondary ID, with a tracking call. For example, email_address or login_id.

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

To learn more about creating visitor identifiers, see Visitor ID Attribute.

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 the tealium_thirdparty_visitor_id
• The tealium_visitor_id
• The utag_main v_id, also called the tealium_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:

• A tealium_override_tapid value prevents the tealium_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:

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, and datalayer_id exceeds 250 characters in length, or contains restricted characters
• tealium_account or tealium_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)