Moments API endpoint | Moments API

How it works

The Moments API engine creates a unique endpoint for your region, account, and profile. Each engine assigns a unique engine ID to each endpoint.

Data for visitors becomes available after you enable the engine and visitors log active sessions and generate events in the system. If you request data for a visitor and they have not logged an active session yet, the API will not return any data.

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

GET method

Use the GET method to retrieve audience, badge, and attribute data that you specified in your Moments API engine.

Tealium anonymous visitor ID

GET  https://personalization-api.{REGION}.prod.tealiumapis.com/personalization/accounts/{ACCOUNT}/profiles/{PROFILE}/engines/{ENGINE_ID}/visitors/{IDENTIFIER}?suppressNotFound={SUPPRESS_NOT_FOUND}

This command uses the following parameters:

Parameter	Type	Description
`identifier`	String Path parameter	The Tealium anonymous visitor ID.
`suppressNotFound`	Boolean Query parameter	Determines the response type returned when a visitor is not found. The default is `false`. `true` - Returns an HTTP 200 code with an empty response body. `false` - Returns an HTTP 404 code.

Visitor ID attribute

GET  https://personalization-api.{REGION}.prod.tealiumapis.com/personalization/accounts/{ACCOUNT}/profiles/{PROFILE}/engines/{ENGINE_ID}?attributeId={attributeId}&attributeValue={attributeValue}&suppressNotFound={SUPPRESS_NOT_FOUND}

This command uses the following parameters:

Parameter	Type	Description
`attributeId`	String Query parameter	The numeric ID representing a Visitor ID attribute from your account.
`attributeValue`	String Query parameter	The value to look up. Values containing special characters must be URL encoded.
`suppressNotFound`	Boolean Query parameter	Determines the response type returned when a visitor is not found. The default is `false`. `true` - Returns an HTTP 200 code with an empty response body. `false` - Returns an HTTP 404 code.

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

Objects

Moments API returns visitor data as JSON objects that contain the audience, badge, and attribute fields you specify in the engine configuration.

You can configure visitor attributes to be returned with the ID or name, as seen in the following response body example:

{
    "audiences": [
        "VIP", 
        "Women's Apparel",
        "Lifetime visit count"
    ],
    "badges": [
        "13",
        "26",
        "52"
    ],
    "metrics": {
        "5048": 0
    },
    "properties": {
        "5050": "<attr_value>"
    },
    "flags": {
        "5052": false
    },
    "dates": {
        "5054": 123456789
    } 
}

The following table summarizes the data types supported by Moments API:

Attribute Type	Supported
Badge	✓
Boolean	✓
Date	✓
Number	✓
String	✓
Array of booleans	✗
Array of numbers	✗
Array of strings	✗
Funnel	✗
Set of strings	✗
Tally	✗
Timeline	✗

Attributes marked as PII are not supported.

Headers

The following HTTP headers are required in a Moments API request:

Referer - The value compared to the domain allow list. If the referrer and the allow list do not match, the request is refused.
- Example: https://www.example.com/
Origin - The value used to address CORS errors when calling the API from JavaScript.
- Example: https://www.example.com/

Error messages

Potential error messages for this endpoint:

Status Code	Description
200	Status OK. The request succeeded.
400	Bad request.
403	The Moments API engine is not enabled.
404	Not Found. The Tealium visitor ID does not have moments stored in the database.