Skip to main content

Tealium

Tealium is a customer data platform (CDP) that collects, unifies, and activates first-party customer data across web, mobile, and offline channels in real time. The Tealium API lets you send behavioral events to Tealium Collect, read and manage AudienceStream visitor profiles, fulfill GDPR/CCPA data subject requests, and manage iQ Tag Management configuration, Hosted Data Layer files, and Omnichannel file processing status.

Tealium icon

Power end-to-end data operations for your Tealium API with Nexla. Our bi-directional Tealium connector is purpose-built for Tealium, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Tealium or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Tealium workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

  • Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
  • Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
  • API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
  • Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites​

Tealium's HTTP APIs authenticate with a Username (your Tealium account email) and an API Key, which are exchanged for a short-lived JWT bearer token. Nexla handles this token exchange automatically once you provide the underlying credential fields. Tealium separates its APIs into two generations that use different token endpoints and are represented in Nexla as two separate credential types:

  • V3 API — used by the HTTP Event (Collect), Visitor Profile, Visitor Privacy, and iQ Profiles endpoints.
  • V2 API — used by the iQ Revisions, Hosted Data Layer, and Omnichannel File Status endpoints.

You will also need your Tealium Account and Profile names. In Tealium, an account is the top-level container for your organization, and a profile is a subdivision of that account that typically corresponds to a website, app, or group of properties with shared tagging requirements — both names appear in your Tealium installation (tag) code and in the Tealium UI.

To obtain your Tealium API key:

  1. Sign in to Tealium iQ Tag Management with an account that has user admin (or Manage Users) permission, or ask your Tealium administrator to authorize your account to generate its own API key. Authorization sends the target user an email notification once granted.

  2. From the admin menu, click Manage Users, select the user who needs the key, and click Edit/View User Settings.

  3. In the left-hand panel of the user settings dialog, click API Key, then click Generate Key.

  4. Tealium displays the generated key once in a pop-up. Copy it immediately and store it securely — the raw key value cannot be retrieved again after you close the dialog. If it is lost, you must generate a new one.

The API key is tied to the individual Tealium user account used to generate it and inherits that user's permissions. For details on authorization and key generation, see the Tealium API Keys documentation, and for the underlying token exchange used by Nexla, see the Tealium V3 Authentication and Tealium V2 Authentication documentation.

Authenticate​

Credentials required​

Token-based authentication for Tealium V3 APIs (HTTP Event, Visitor Profile, Visitor Privacy). Exchanges username + API key for a 30-minute JWT bearer token.

FieldRequiredSecretDescription
UsernameYesNoYour Tealium account email address used to log in.
API KeyYesYesYour Tealium API key from iQ Tag Management > Admin > API Keys.
AccountYesNoYour Tealium account name (e.g., mycompany).
ProfileYesNoYour Tealium profile name (e.g., main).

Create a credential in Nexla​

  1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

  2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

  3. Select the credential type that matches the endpoints you plan to use:

    • V3 API (Event Collection & Visitor APIs) — use this for the Send Event, Send Bulk Events, Send Integration Event, Visitor Profile, Visitor Privacy, and iQ Profile endpoints.
    • V2 API (iQ Revisions, Hosted Data Layer, Omnichannel) — use this for the iQ Revisions, Hosted Data Layer, and Omnichannel File Status endpoints.

    For either type, enter your Username (the email address you use to sign in to Tealium) and your API Key (generated in Prerequisites), then enter your Account and Profile names, which identify the specific Tealium implementation Nexla should connect to.

    The API key is a sensitive credential and is stored securely by Nexla. If a key is compromised, revoke authorization and generate a new one from your Tealium user settings. Bearer tokens obtained from your key are short-lived (30 minutes); Nexla automatically refreshes the token as needed.

    For more information about Tealium authentication and account/profile structure, see the Tealium V3 Authentication documentation and About profiles.

  4. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source​

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Tealium connector tile, then select the credential that will be used to connect to Tealium, and click Next; or, create a new Tealium credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Tealium endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

Get Visitor Profile

Retrieve a live or historical visitor profile from Tealium AudienceStream by a Visitor ID attribute.

  • Attribute ID (required) — Numeric ID of the Visitor ID attribute to look up (e.g., 5013). See the Get Visitor ID Attributes endpoint below to list available attribute IDs.
  • Attribute Value (required) — The value to look up for the specified Visitor ID attribute (e.g., user@example.com). URL-encode special characters.
  • Pretty Names (optional, default True) — If true, response attributes display as human-readable names. If false, attributes display as numeric IDs.
  • Search Priority (optional, default Live then Historical) — Data source priority for the lookup. Controls whether live, historical, or both data sources are queried.
  • Response Filters (optional) — JSON array of attribute IDs to include in the response (max 150). Leave empty to return all visitor data.

For details, see the Tealium Visitor Profile API documentation. Use the V3 API credential type with this endpoint.

Get Historical Visitor Profile

Retrieve a historical visitor profile from Tealium AudienceStream, optimized for faster response by querying only historical data.

  • Attribute ID (required) — Numeric ID of the Visitor ID attribute to look up (e.g., 5013).
  • Attribute Value (required) — The value to look up for the specified Visitor ID attribute (e.g., user@example.com). URL-encode special characters.
  • Pretty Names (optional, default True) — If true, response attributes display as human-readable names. If false, attributes display as numeric IDs.
  • Response Filters (optional) — JSON array of attribute IDs to include in the response (max 150). Leave empty to return all visitor data.

For details, see the Tealium Visitor Profile API documentation. Use the V3 API credential type with this endpoint.

Get Privacy Visitor Data

Retrieve all known data about a specific visitor for DSAR (Data Subject Access Request) compliance purposes.

  • Attribute ID (required) — Numeric ID of the Visitor ID attribute to look up (e.g., 86 for Email Address).
  • Attribute Value (required) — The value to look up (e.g., user@example.com). URL-encode special characters.
  • Pretty Names (optional, default True) — If true, attributes display as human-readable names. If false, attributes display as numeric IDs.

For details, see the Tealium Visitor Privacy API documentation. Use the V3 API credential type with this endpoint.

Get Visitor ID Attributes

Retrieve a list of all Visitor ID attributes (numeric ID to name mapping) available in the Tealium account and profile.

  • This endpoint takes no additional parameters — it returns every Visitor ID attribute configured for the account and profile in the credential.

Use this endpoint to look up the numeric Attribute ID values required by the Get Visitor Profile, Get Historical Visitor Profile, and Get Privacy Visitor Data endpoints. For details, see the Tealium Visitor Privacy API documentation. Use the V3 API credential type with this endpoint.

Get Delete Transaction Status

Check the processing status of a previously submitted visitor delete request using its transactionId. Returns PENDING, SUCCESS, or FAILED.

  • Transaction ID (required) — The transactionId returned from a Delete Visitor (GDPR) request.

For details, see the Tealium Visitor Privacy API documentation. Use the V3 API credential type with this endpoint.

Get iQ Revisions

Retrieve a list of all iQ Tag Management revision IDs for the account and profile, in reverse chronological order.

  • This endpoint takes no additional parameters — it returns every revision ID recorded for the account and profile in the credential.

For details, see the Tealium iQ Revisions API documentation. Use the V2 API credential type with this endpoint.

Get Revision Details

Retrieve full metadata for a specific iQ revision including creator, publish targets, comments, and SHA256 checksums.

  • Revision ID (required) — The revision ID timestamp (YYYYMMDDHHMM format) to retrieve details for (e.g., 201612131954).

For details, see the Tealium iQ Revisions API documentation. Use the V2 API credential type with this endpoint.

Get Hosted Data Layer File Metadata

Retrieve metadata (file path, last modified, size) for a specific Hosted Data Layer object or JSON file.

  • Data Layer ID (required) — The unique identifier for the Hosted Data Layer object or file to retrieve metadata for.
  • File Type (optional, default JavaScript) — Use json for JSON files; leave empty for JavaScript objects.

For details, see the Tealium Hosted Data Layer API documentation. Use the V2 API credential type with this endpoint.

List Hosted Data Layer Files

Retrieve a list of up to 1,000 Hosted Data Layer objects and JSON files. Supports a continuation token for large result sets.

  • This endpoint takes no additional parameters. It is paginated — Nexla automatically follows the response's continuation token to fetch subsequent pages of results.

For details, see the Tealium Hosted Data Layer API documentation. Use the V2 API credential type with this endpoint.

Get Failed HDL Uploads

Query for failed Hosted Data Layer uploads within a specified date range. Returns up to 5,000 records.

  • Start Date (optional, default 7 days before now) — Start of the date range for failed upload queries. Format: YYYY-MM-DDThh:mm:ssZ (e.g., 2017-03-31T13:45:33-0700).
  • End Date (optional, default now) — End of the date range for failed upload queries. Format: YYYY-MM-DDThh:mm:ssZ (e.g., 2017-04-07T13:45:33-0700).

For details, see the Tealium Hosted Data Layer API documentation. Use the V2 API credential type with this endpoint.

Get Omnichannel File Count

Retrieve a count of uploaded omnichannel files matching a specified file prefix and date range.

  • File Prefix (required) — The file prefix matching the Omnichannel file definition (e.g., sales_transactions). Max 150 characters.
  • Start Date (required, default 7 days before now) — Start date of the file range to query. Format: 2017-01-01T12:34Z.
  • End Date (required, default now) — End date of the file range to query. Format: 2017-01-08T12:34Z.

For details, see the Tealium Omnichannel File Status API documentation. Use the V2 API credential type with this endpoint.

Get Omnichannel File Status

Retrieve the processing status of a single omnichannel CSV file (DOWNLOADING, DOWNLOADED, PROCESSING, PROCESSED).

  • Filename (required) — The full filename of the omnichannel CSV file to retrieve status for (e.g., sales_transactions_2024jan01.csv). Max 150 characters.

For details, see the Tealium Omnichannel File Status API documentation. Use the V2 API credential type with this endpoint.

Search Omnichannel File Statuses

Retrieve processing statuses for multiple omnichannel files matching a file prefix within a specified date range.

  • File Prefix (required) — The file prefix matching the Omnichannel file definition (e.g., sales_transactions). Max 150 characters.
  • Start Date (required, default 7 days before now) — Start of the date range for the file status search. Format: 2016-07-31T13:45-0700.
  • End Date (required, default now) — End of the date range for the file status search. Format: 2016-07-31T13:45-0700.

For details, see the Tealium Omnichannel File Status API documentation. Use the V2 API credential type with this endpoint.

Get iQ Profile Configuration

Retrieve a full iQ Tag Management profile configuration: load rules, tags, extensions, variables, events, and version IDs.

  • Includes (optional, default loadRules,tags,extensions,variables,events,versionIds) — Comma-separated config sections to include in the response.
  • Publish Version (optional) — A specific revision version to retrieve (YYYYMMDDHHMM). Leave empty for the latest saved version.

For details, see the Tealium iQ GET Profile API documentation. Use the V3 API credential type with this endpoint.

Get HDL Upload Status

Poll the status of a Hosted Data Layer upload, update, or delete action. Statuses are retained for 30 days.

  • Data Layer ID (required) — The unique identifier of the HDL file to check upload/update/delete status for.

For details, see the Tealium Hosted Data Layer API documentation. Use the V2 API credential type with this endpoint.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration​

Tealium data sources can also be manually configured to ingest data from any valid Tealium API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Tealium data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination​

Click the + icon on the Nexset that will be sent to the Tealium destination, and select the Send to Destination option from the menu. Select the Tealium connector from the list of available destination connectors, then select the credential that will be used to connect to Tealium, and click Next; or, create a new Tealium credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Tealium endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Send Event

Send a single event to Tealium Collect via the V3 HTTP API (POST method).

  • Each record from your Nexset is sent as the JSON body of a separate POST request to the Tealium Collect event endpoint. No additional endpoint parameters are required — the record's fields become the event payload.

For details on the event payload structure, see the Tealium HTTP API documentation. Use the V3 API credential type with this endpoint.

Send Bulk Events

Send multiple events to Tealium Collect in a single batched request using the V3 HTTP API bulk-event endpoint.

  • Nexla batches up to 50 records per request and sends them as the events array of the bulk-event payload, alongside a shared object containing the account and profile from your credential. No additional endpoint parameters are required.

For details on the bulk-event payload structure, see the Tealium HTTP API documentation. Use the V3 API credential type with this endpoint.

Send Integration Event

Send an event scoped to a specific datasource via the V3 HTTP API integration event endpoint.

  • Datasource ID (required) — The Tealium datasource ID scoping this event to a specific data source (e.g., abc123).

For details, see the Tealium HTTP API documentation. Use the V3 API credential type with this endpoint.

Delete Visitor (GDPR)

Queue deletion of all data associated with a visitor record for GDPR/CCPA compliance. Returns a transactionId to track delete status.

  • Attribute ID (required) — Numeric ID of the Visitor ID attribute identifying the visitor to delete (e.g., 86 for Email Address).
  • Attribute Value (required) — The value identifying the visitor to delete (e.g., user@example.com).

Use the Get Delete Transaction Status source endpoint to poll the resulting transactionId. For details, see the Tealium Visitor Privacy API documentation. Use the V3 API credential type with this endpoint.

Upload Hosted Data Layer File

Upload a new Hosted Data Layer object or JSON file to Tealium. Changes may take up to one hour to propagate.

  • Data Layer ID (required) — The unique identifier for the new Hosted Data Layer object or file to upload.
  • File Type (optional, default JavaScript) — Use json for JSON files; leave empty for JavaScript objects.

For details, see the Tealium Hosted Data Layer API documentation. Use the V2 API credential type with this endpoint.

Update Hosted Data Layer File

Update an existing Hosted Data Layer object or JSON file in Tealium. Changes may take up to one hour to propagate.

  • Data Layer ID (required) — The unique identifier for the existing Hosted Data Layer object or file to update.
  • File Type (optional, default JavaScript) — Use json for JSON files; leave empty for JavaScript objects.

For details, see the Tealium Hosted Data Layer API documentation. Use the V2 API credential type with this endpoint.

Update iQ Profile Configuration

Create, update, or delete iQ Tag Management components (load rules, tags, extensions) programmatically via PATCH.

  • Each record from your Nexset is sent as the JSON body of a PATCH request. No additional endpoint parameters are required — the record's fields describe the iQ Profile components to create, update, or delete.

For details on the PATCH payload structure, see the Tealium iQ Profiles API documentation. Use the V3 API credential type with this endpoint.

Send Event (GET / Pixel)

Send a tracking event via GET query parameters. Returns a 1x1 GIF. Use for server-to-server pixel and HTML img-tag implementations.

  • Event Name (required) — The tealium_event value for this tracking pixel call (e.g., page_view, add_to_cart).
  • Visitor ID (optional) — The tealium_visitor_id for AudienceStream. Required for visitor profile enrichment.

For details, see the Tealium HTTP API documentation. Use the V3 API credential type with this endpoint.

Manual configuration​

Tealium destinations can also be manually configured to send data to any valid Tealium API endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

Tealium APIs expect JSON request bodies for most POST/PATCH operations, with the exception of Delete Visitor (GDPR), which uses application/x-www-form-urlencoded, and Send Event (GET / Pixel), which sends parameters as a query string.

Save & activate​

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Tealium endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to the Tealium endpoint until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.