Tealium Collect HTTP API — V3 Early Access
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.
Contact your Tealium Account Manager to begin using the Tealium Collect HTTP API.
How it works
Tealium Collect is an HTTP endpoint that supports GET and POST methods.
https://collect.tealiumiq.com/event
Sessions are determined based on the Visit scope attribute property.
Regional and global endpoints
Tealium Collect is a cross-regional endpoint so that any profile can send event data to Tealium Collect in any region. The API recognizes the correct region of the profile and then sends data to ESP in the correct region.
Tealium Collect supports the following two hosts:
collect.tealiumiq.com
Sends events to the nearest Tealium Collect server (one with the least latency).collect-<region>.tealiumiq.com
Sends events to the Tealium Collect server in the region of the profile.
For secured Tealium Collect endpoints, the global endpoints are internally mapped to collect.tealiumiq.com
and regional endpoints are mapped to collect-<region>.tealiumiq.com
.
Endpoint mapping
The following table shows a mapping of unsecured Tealium Collect endpoints to secured Tealium Collect endpoints.
Unsecured Tealium Collect Endpoint | Secured Global Tealium Collect Endpoint | Secured Regional Tealium Collect Endpoint | HTTP Method | Description |
---|---|---|---|---|
/event |
/v3/collect/event |
/v3/collect/regional/event |
GET POST |
RESTful endpoint for non-browser based requests. |
/integration/event/<br> {account}/{profile}/<br> {datasourceID} |
/v3/collect/integration/<br> event/accounts/<br> {account}/profiles/<br> {profile}/datasources/<br> {datasourceID} |
/v3/collect/regional/<br> integration/event/accounts/<br> {account}/profiles/{profile}/<br> datasources/{datasourceID} |
POST | Endpoint used by HTTP Advanced HTTP API and Communications data sources internally. |
/bulk-event |
/v3/collect/bulk-event |
/v3/collect/regional/bulk-event |
POST | Send multiple events (up to 10) in a single request. |
Visitor ID attribute
Visitor identifiers
If you are using Tealium AudienceStream CDP you must pass a known visitor identifier attribute (secondary ID) with each tracking call (for example, email_address
or login_id
). If the events do not contain a visitor identifier each event will generate a new visit and visitor stitching will not be possible. Passing a known visitor identifier 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 Tealium EventStream API Hub and need to provide an ID to a vendor connector.
For more information about what makes a good visitor identifier, see Visitor ID Attribute.
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 Tealium 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 asemail_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 thetealium_visitor_id
parameter.
AUDIENCESTREAM | EVENTSTREAM |
---|---|
Required | Recommended |
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<br>
"tealium_visitor_id" : "bad8145f125e0560d07872e77e98bc9cd8b7b763a4577adbbf52bfd7b164223e"
}`
- Anonymous Visitors
When tracking events for an anonymous visitor from a website (without a known identifier), then the value of thetealium_visitor_id
will need to match the value in theutag_main_v_id
cookie. For more information about built-in variables from utag.js, see Data Layer.
AUDIENCESTREAM | EVENTSTREAM |
---|---|
Required | N/A |
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
AudienceStream gives the ID in the TAPID
cookie precedence over other IDs to determine the visitor profile to use and provides parameters that control how the endpoint handles ID priority.
For example, if a user logs in and their ID is added to the TAPID
cookie, traffic from all the anonymous users on the device are logged to that user. AudienceStream will continue to log activity to the first user if a second user logs in to that device with an anonymous cookie. For example, if visitors use a shared smart television or a public kiosk, the visitors’ profile data can become contaminated.
Use the following parameters to control how the Tealium Collect API 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.
For more information and a demonstration of how to use visitor switching, see Visitor Switching.
Permission requirements
- Server-side publisher permission
Authentication
The bearer token is used to authenticate all API calls and not the API key. The API key is only used in the authentication call. In addition to the bearer token, the authentication response includes a region-specific hostname that must be used in subsequent server-side API calls.
See the [Tealium API Tealium API V3 Getting Started guide to learn about generating a bearer token from the API key.
Required parameters
Tealium Collect supports the following standard parameters in each request:
tealium_account
- the name of your Tealium accounttealium_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 purposestealium_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.
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.
Examples for /event
Example cURL request
curl -i -X GET 'https://{host}/v3/collect/event?tealium_account={account}&tealium_profile={profile}&tealium_event=user_login&email_address=user@example.com'
--header 'Authorization: Bearer eyJ0**'
Example response
< HTTP/2 200
< date: Fri, 15 Jul 2022 00:08:50 GMT
< content-type: image/gif
< content-length: 43
< x-amzn-requestid: 03bb378a-2619-4440-9d5a-c1e7d0e8d2ae
< x-amzn-remapped-content-length: 43
< x-region: us-east-1
< x-acc: {account}:{profile}:2:event
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: f513ef4b-5870-4fa4-b908-38c5e12bf3e4
< x-amz-apigw-id: VSBy2Fu6oAMFezA=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-0182b50695a2297ec
< expires: Fri, 15 Jul 2022 00:08:50 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< x-tid: f513ef4b58704fa4b90838c5e12bf3e4
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:08:50 GMT
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.
Examples for /event
Example cURL request
curl --location --request POST 'https://{host}/v3/collect/event' --header 'Authorization: Bearer eyJ0eXA***' --header 'Content-Type: application/json' --data-raw '{
"tealium_account": "{account}",
"tealium_datasource": "w12c8s",
"tealium_profile": "{profile}",
"tealium_event": "page_view",
"page_type": "123",
"page_name": "testName"
}'
Example response
< HTTP/2 200
< date: Fri, 15 Jul 2022 00:08:03 GMT
< content-type: application/json
< content-length: 0
< x-amzn-requestid: ad5c154f-3053-4991-9a60-45b35745eba7
< x-region: us-east-1
< x-acc: {account}:main:2:event
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: 1d6b9c12-16c3-44a9-95c9-78afeabaf8e0
< x-amz-apigw-id: VSBroH24oAMFXpQ=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-0a95ad51791af67ac
< expires: Fri, 15 Jul 2022 00:08:03 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< x-tid: abc123_071422_1
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:08:03 GMT
Examples for /bulk-event
Example cURL request
curl --location --request POST 'https://{host}/v3/collect/bulk-event' \
--header 'Authorization: Bearer eyJ0eXAi***' \
--header 'Content-Type: application/json' \
--data-raw '{
"shared": {
"tealium_account": "{account}",
"tealium_profile": "{profile}",
"tealium_environment": "prod",
"tealium_datasource": "{datasource}",
"tealium_visitor_id": "abc123_071222_1"
},
"events": [
{
"page_name": "test1",
"tealium_event": "page_view"
},
{
"page_name": "test2",
"tealium_event": "page_view"
}
]
}'
Example response
< HTTP/2 200
< date: Fri, 15 Jul 2022 00:07:37 GMT
< content-type: application/json
< content-length: 0
< x-amzn-requestid: 11f79456-cdb8-4ccc-8cc7-e8a54db79414
< x-region: us-east-1
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: 7277c009-f9f5-47a2-9fe6-61f05c98e6fd
< x-amz-apigw-id: VSBnlEqkIAMFbFA=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-01e68ac980b602444
< expires: Fri, 15 Jul 2022 00:07:37 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:07:37 GMT
Examples for /integration/event
Example cURL request
curl --location --request POST 'https://{host}/v3/collect/integration/event/accounts/{account}/profiles/{profile}/datasources/{datasourceId}' --header 'Authorization: Bearer eyJ0***' --header 'Content-Type: application/json' --data-raw '{
"tealium_event": "page_view",
"tealium_datasource": "{datasourceId}",
"page_type": "123",
"outerObject": {
"innerobject":"1234"
},
"page_name": "kek"
}'
Example response
< HTTP/2 204
< date: Fri, 15 Jul 2022 00:05:23 GMT
< x-amzn-requestid: e3b5bc65-8712-40a3-a87c-9d6bb8df68cf
< x-region: us-east-1
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: fadbdf55-dccb-4241-a9ce-81722fc2a8d9
< x-amz-apigw-id: VSBSnF9OIAMFxXA=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-058449c0632b25787
< expires: Fri, 15 Jul 2022 00:05:23 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:05:23 GMT
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 for a GET request to /v3/collect/event
, shown in the X-Error
header, when the required tealium_account
or tealium_profile
parameter values are missing:
< HTTP/2 200
< date: Fri, 15 Jul 2022 00:03:05 GMT
< content-type: image/gif
< content-length: 43
< x-error: Missing required tealium_account or tealium_profile param value
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-region: us-west-2
< x-serverid: uconnect_i-0b80d0d9adfb124a2
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< vary: Origin
< pragma: no-cache
< expires: Fri, 15 Jul 2022 00:03:05 GMT
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-uuid: 1d0dd863-dc31-4eb2-b7a0-5b98e3b7fb5b
The following is an example is a 400 Bad Request
response for a POST request to /v3/collect/bulk-event
:
< HTTP/2 400
< date: Fri, 15 Jul 2022 00:01:16 GMT
< content-type: application/json
< content-length: 78
< x-amzn-requestid: 993d950d-cde4-4ee0-9f18-d3e41a3ed5ca
< x-amzn-remapped-content-length: 78
< x-region: us-east-1
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: 59afeed7-abe2-487c-bac1-a96903f4a449
< x-amz-apigw-id: VSAr9HOloAMFQkA=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-02ccd81bf59828cde
< expires: Fri, 15 Jul 2022 00:01:16 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:01:16 GMT
<
* Connection #0 to host us-east-1-platform.tealiumapis.com left intact
{ "returnCode" : 1400 , "message" : "Request body must contain 'events' key."}
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](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));
The Response Headers include the following:
Access-Control-Allow-Origin: [<http://your_domain.com>](<http://your_domain.com>)
Contact your Tealium Account Manager to begin using the Tealium Collect HTTP API.
This page was last updated: January 30, 2023