Tealium Collect HTTP API — V3 Early Access

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.

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

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 the tealium_visitor_id will need to match the value in the utag_main_v_id cookie. For more information about built-in variables from utag.js, see Data Layer.

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

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:

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

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

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:

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