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.

Rate limits

The Tealium Collect HTTP API — V3 supports a maximum rate limit of 100 events/second.

For example, if you send:

• 1 event per call, you can send 100 calls/second.
• 10 events per call, you can send 10 calls/second.
• 100 events per call, you can send 1 call/second.

If you exceed the rate limit, Tealium will send an HTTP 429 response indicating too many requests.

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

Endpoint mapping

The following table shows a mapping of unsecured Tealium Collect endpoints to secured Tealium Collect endpoints.

Visitor identifiers

AudienceStream tracks visitors using a combination of:

• Anonymous ID: An ID usually used to track the visitor anonymously (for example, from a device or browser). In the case of a known visitor, you can use a value based on a user identifier.
• User Identifier: Sent after the visitor is known. Based on a value that identifies the user instead of a particular device.

Anonymous ID

The Anonymous ID is an anonymous identifier used by AudienceStream to associate a visitor between events and visits. Ensure this value is a GUID and consistent for the visitor.

The key name of the anonymous ID is tealium_visitor_id.

Depending on your business case, you can use anonymous values or values based on known user identifiers.

Anonymous values

If you are using Tealium iQ 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 following:

• Account

• Profile

• Visitor ID attribute ID and value

  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.

• Value in the tealium_visitor_id parameter

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

User Identifiers

When using AudienceStream, you can pass a known user identifier with a tracking call. For example, email_address or login_id.

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

In AudienceStream, these user identifiers are used to enrich visitor ID attributes.

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