• Platforms
  • Partners
  • Forums
  • 日本語
  • TLC Tealium Learning Center Tealium Learning
    Community
  • Discussions & Ideas Dicussions & Ideas
  • Product Guides Product Guides
  • Knowledge Base Knowledge Base
  • Developer Docs Developer Docs
  • Education Education
  • TLC Blog TLC Blog
  • Support Desk Support Desk
  • CDH Customer Data Hub Customer Data Hub
  • Mobile
  • Getting Started
    • Overview
    • Quick Start Guide
    • Mobile Concepts
    • Client-Side
    • Server-Side
    • Tracking Webviews
    • Data Layer
    • Consent Management
    • Event Batching
    • User Location and Geofencing
    • Media Tracking
    • Deep Links
    • Timed Events
    • Trace
    • Hosted Data Layer
    • Adobe Visitor Service Module
    • Feature Comparison
    • Troubleshooting
  • Remote Commands
    • Overview
    • How It Works
    • Integrations
      • Adjust
      • AppsFlyer
      • Branch
      • Braze
      • Contentsquare
      • Facebook
      • Firebase
      • Kochava
      • Usabilla
  • Android (Java)
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • Consent Management
    • Module List
      • Ad Identifier Module
      • Crash Reporter Module
      • Install Referrer Module
      • Lifecycle Tracking Module
      • Location Module
      • Optimizely X Tracking Module
    • Android TV
    • Android Wear
    • API Reference
      • ConsentManager
      • DataSources
      • Lifecycle
      • Tealium
      • Tealium.Config
      • TealiumLocation
    • Release Notes
  • Android (Kotlin)
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • Identity Resolution
    • Module List
      • Ad Identifier Module
      • AutoTracking Module
      • AdobeVisitorService Module
      • Collect Module
      • Collectors Module
      • Crash Reporter Module
      • In-App Purchase Module
      • Install Referrer Module
      • Lifecycle Tracking Module
      • Location Manager Module
      • Media Module
      • RemoteCommands Module
      • Tag Management Dispatcher Module
      • Visitor Service Module
    • Android TV
    • API Reference
      • ConsentCategory
      • ConsentManager
      • CurrentVisit
      • DataLayer
      • Lifecycle
      • LocationManager
      • Media
      • Tealium
      • TealiumConfig
      • VisitorProfile
      • VisitorService
    • Release Notes
  • Cordova 1.x
    • Overview
    • Install
    • Track
    • Data Management
    • Module List
      • Ad Identifier Module
      • Crash Reporter Module
      • Install Referrer Module
    • API Reference
    • Release Notes
  • Cordova 2.x
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • Flutter 1.x
    • Overview
    • Install
    • Track
    • Consent Management
    • Data Management
    • API Reference
    • Release Notes
  • Flutter 2.x
    • Overview
    • Install
    • Track
    • Consent Management
    • Data Management
    • API Reference
      • Tealium
      • TealiumConfig
      • VisitorProfile
    • Release Notes
  • iOS (Objective-C)
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • Consent Management
    • Tag Management
    • Module List
      • Lifecycle Tracking Module
    • tvOS
    • watchOS
    • API Reference
    • Release Notes
  • iOS (Swift) 1.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • App Extensions
    • Identity Resolution
    • Consent Management
    • Modules
    • Module List
      • AppData Module
      • Attribution Module
      • AutoTracking Module
      • Collect Module
      • Connectivity Module
      • CrashReporter Module
      • DataSource Module
      • DefaultStorage Module
      • Delegate Module
      • DeviceData Module
      • DispatchQueue Module
      • FileStorage Module
      • Lifecycle Module
      • Location Module
      • Logger Module
      • PersistentData Module
      • RemoteCommands Module
      • TagManagement Module
      • VisitorService Module
      • VolatileData Module
    • Feature Comparison
    • Working with Objective-C
    • API Reference
      • TealiumConfig
      • TealiumConsentCategories
      • TealiumConsentManagerDelegate
      • TealiumConsentManager
      • TealiumInstanceManager
      • TealiumPersistentData
      • TealiumVolatileData
      • Tealium
    • Release Notes
  • iOS (Swift) 2.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • App Extensions
    • Identity Resolution
    • Modules
    • Module List
      • AppData Module
      • AdobeVisitorService Module
      • Attribution Module
      • AutoTracking Module
      • Collect Module
      • Connectivity Module
      • CrashReporter Module
      • DeviceData Module
      • In-App Purchase Module
      • Lifecycle Module
      • Location Module
      • Media Module
      • RemoteCommands Module
      • TagManagement Module
      • VisitorService Module
    • Working with Objective-C
    • API Reference
      • LocationModule
      • MediaSession
      • Tealium
      • TealiumConfig
      • TealiumConsentCategories
      • TealiumConsentManager
      • TealiumDataLayer
      • TealiumInstanceManager
    • Release Notes
  • NativeScript
    • Overview
    • Install
    • Track
    • API Reference
      • Tealium
      • TealiumConfig
    • Release Notes
  • React Native 1.x
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • React Native 2.x
    • Overview
    • Install
    • Track
    • Location Module
    • API Reference
    • Release Notes
  • Unity 1.x
    • Overview
    • Install
    • Track
    • API Reference
  • Unity 2.x
    • Overview
    • Install
    • Track
    • API Reference
  • Xamarin 1.x
    • Overview
    • Install
    • Track
    • Data Management
    • Consent Management
    • API Reference
    • Release Notes
  • Xamarin 2.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • API Reference
    • Release Notes
  • Web
  • Getting Started
    • Overview
    • Quick Start Guide
    • Web Concepts
    • Data Layer
      • An Introduction to the Data Layer
      • How the Data Layer Works for Websites
      • Data Layer Best Practices
      • Definitions
        • Retail
        • Publisher
        • Hotel
        • Travel
        • Basic Video Tracking
  • Adobe Launch
    • Overview
    • Install
    • Data Layer
  • AMP
    • Overview
    • Install
    • Track
    • Data Layer
  • Angular
    • Overview
    • Install
    • Track
    • API Reference
  • Google Tag Manager
    • Overview
    • Install
    • Data Layer
  • JavaScript (Web)
    • Overview
    • Install
    • Track
    • Data Layer
    • Universal Data Object (utag_data)
    • Universal Tag (utag.js)
    • Data Layer Object (b)
    • Single-Page Applications
    • Settings
    • Debugging
    • API Reference
      • Cookie Functions
      • GDPR Functions
      • Tracking Functions
      • Utility Functions
    • Release Notes
  • Server
  • C#
    • Overview
    • Install
    • Track
    • Data Layer
    • API Reference
    • Release Notes
  • HTTP API
    • Overview
    • Endpoint
    • Data Layer
  • Java
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • Node
    • Overview
    • Install
    • Track
    • API Reference
  • Python
    • Overview
    • Install
    • Track
    • API Reference
  • Roku
    • Overview
    • Install
    • Track
    • API Reference
  • Ruby
    • Overview
    • Install
    • Track
    • API Reference
HTTP API

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.

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

{
    "tealium_account"    : "ACCOUNT",
    "tealium_profile"    : "PROFILE",
    "tealium_event"      : "EVENT_NAME",
    "email_address"      : "EMAIL_ADDRESS",
    "tealium_visitor_id" : "VISITOR_ID"
}

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.

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 1MB 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)
Next
Data Layer
"Data Layer"

 

Was this article helpful?

This page was last updated: January 6, 2022      

Thank you for your feedback!

Table of Contents

  • Tealium Collect URL
  • Visitor ID Attribute
    • Anonymous ID
  • Methods
    • GET
    • POST
  • Status Codes
  • Examples
    • HTML Example
    • JavaScript Example
  • Platforms
  • Partners
  • Forums
  • Mobile
  • Getting Started
  • Remote Commands
  • Android (Java)
  • Android (Kotlin)
  • Cordova 1.x
  • Cordova 2.x
  • Flutter 1.x
  • Flutter 2.x
  • iOS (Objective-C)
  • iOS (Swift) 1.x
  • iOS (Swift) 2.x
  • NativeScript
  • React Native 1.x
  • React Native 2.x
  • Unity 1.x
  • Unity 2.x
  • Xamarin 1.x
  • Xamarin 2.x
  • Web
  • Getting Started
  • Adobe Launch
  • AMP
  • Angular
  • Google Tag Manager
  • JavaScript (Web)
  • Server
  • C#
  • HTTP API
  • Java
  • Node
  • Python
  • Roku
  • Ruby