About Moments API

Contact your account manager to enable Moments API for your account.

Moments API is a composable AudienceStream API that lets you retrieve high-performance data for real-time visitor personalization. Integrate Moments API into your Tealium client-side applications, wherever utag.js is installed, or in Tealium for Mobile.

How it works

Moments API uses configurations called engines that let you customize API responses to retrieve only the data you need for current visitors. For example, instead of retrieving an entire visitor profile, Moments API will retrieve only the audience, badge, and attribute data you select in the engine configuration.

After you configure the engine, Moments API creates a unique endpoint that you can then integrate into your workflow.

Use cases

Moments API can be used any time you need real-time visitor data for personalized customer experiences, including:

• Personalization (First-page and beyond)
• Next best action in combination with data enrichment logic
• Enterprise-grade API management and compliance

For example, when a customer returns to your website or app, a request is made to the unique Moments API endpoint for visitor data. Moments API is optimized to provide only the data you need, so the API sends a real-time, streamlined response back to your app. With that critical data, you can activate additional logic to trigger personalized experiences for your customers.

Engines

Moments API engines let you configure the visitor data to store in each unique endpoint and the domains allowed to access those endpoints.

When you configure an engine, you select only the audiences, badges, and attributes necessary for your use case. The Moments API engine shows you the JSON response as you build it, which lets you verify the accuracy and scope of your requests.

Data for visitors becomes available after you enable the engine and visitors log active sessions and generate events in the system. For example, when a customer visits your site, Moments API determines if the new visitor events impact the audiences, badges, and attributes defined in your engine configuration. Data is written to a unique data store for each engine only when visitor data needs to be updated.

Engines update their data stores in real-time, so the API endpoint data remains up-to-date as visitors interact with you brand.

By default, you can enable up to 10 engines per profile so that you can create a customized engine for each specific business case. If you need enable additional engines, contact your Tealium account manager.

Endpoints

Moments API creates a unique endpoint for each engine. Visitor data is returned as a JSON object.

Tealium has benchmarked the average Moments API endpoint performance at 60 ms for payload sizes of 1 kB and smaller,

To retrieve visitor data, configure a Tealium iQ Advanced JavaScript Code Extension to make a request to the Moments API endpoint.

Data is not available for visitors that have not had an active session since turning on the engine.

Visitor identifiers

Moments API endpoints support GET requests that use both the Tealium anonymous visitor ID and a visitor ID attribute to retrieve visitor data.

• Anonymous visitor ID: A unique and anonymous value assigned to a visitor on each visit to a site or each use of an app. The anonymous ID tracks a visitor over multiple visits from the same browser or app, but not across different browsers or devices.
• Visitor ID attribute: A special attribute type in AudienceStream that gets its value from a user identifier and is used in visitor stitching.

For more information, see Anonymous IDs, user identifiers, and visitor ID attributes.

Limits

The Moments API has the following default limits:

• Read rate limit per profile across all engines: 200 requests/second/profile

• Maximum enabled engines per profile: 10

• Maximum size of Moments API data that can be stored per visitor per engine: 1 kB

  If your visitor attribute data exceeds the data store limit, it will not be stored for that visitor.

• Data available in Moments API endpoint: 30-day retention if no new events are processed

If you need higher limits for your use case, contact your Tealium account manager.

Purge data

Moments API lets you delete outdated data from an endpoint using the purge data feature.

The following examples describe situations in which you may want to purge data from an endpoint:

• Renaming or deleting an audience, badge, or attribute that is included in your engine configuration.
• Changing the personally identifiable information (PII) status of an attribute. If you change the PII status of an attribute, restricted information may still be openly stored in the API endpoint.
• Removing an audience, badge, or attribute from an engine configuration.

If an audience, badge, or attribute used in an engine is deleted from AudienceStream or the engine configuration, that item will no longer be populated in the endpoint moving forward. Engine data that contains the removed attributes will be unchanged. In general, if removing a dependency causes breaking changes in your endpoint integration, you may want to purge the engine data.

Purging data only deletes Moments API engine data. Visitor records in AudienceStream are not affected.

For more information about purging engine data, see Manage Moments API engines > Purge data.

Domain allow list

We recommend creating a domain allow list only after you test the API endpoint.

An allow list prevents untrusted domains from making requests to your Moments API endpoints. You can add specific domains to the allow list when you configure the engine.

Moments API allows or restricts calls to the endpoint by comparing the domain in the Referer HTTP request header to the allow list defined in the Moments API engine:

• Domains match: The request is processed.
• Domains do not match: The request is not processed and returns a 403 error.

If you do not list any domains, all domains will be allowed.

Subdomains

When you add a domain to the allow list, all of its subdomains are automatically included. For example, if you allow example.com, any subdomain that matches *.example.com is included.

Permissions

Moments API functionality is managed through the following permission levels:

• Create, edit, delete engines and purge engine data
  • Editor or publisher legacy permissions
  • Write or delete access in platform permissions
• View engine list
  • Viewer legacy permissions or read access in platform permissions

Moments API compared with Data Layer Enrichment API

Both Moments API and Data Layer Enrichment API let you retrieve live visitor data, but the use cases, configurations, and implementations are different. Refer to the following comparison to learn more about the differences between these two visitor profile data retrieval methods.

	Moments API	Data Layer Enrichment API
Use case	Real-time access to current visitor data for first-page personalization and beyond.	Live visitor data available in real-time to near-real-time after an initial processed event.
Rates	200 requests/second	-
Active visitor session required	No	Yes
Available data	Audience, badge, or supported attribute data types. Names and IDs of audiences and badges available.	Attributes other than visitor IDs, funnels, and timelines, listed by attribute IDs. For badges and audiences, names are available. For badge names, combine with Profile Definition API.
Lookup ID	Tealium anonymous ID or visitor ID attribute value	Tealium anonymous ID
Authenticated endpoint	No	No
Access to PII	No	No
Custom response object	Yes	No
Implementation	API	API or Tealium Collect tag

Get started

A workflow using Moments API includes the following steps:

1. Consider what audiences, badges, and attributes you need to create personalized experiences.
2. Create a Moments API engine to populate your customized endpoint with the visitor data you need.
3. Integrate the endpoint into your Tealium client-side applications, wherever utag.js is installed, or in Tealium for Mobile.
4. Gather and activate your data.