Search events

This API provides advanced search functionality for behavioural events, allowing you to filter, sort, and paginate through events.

❗️

Attention

The API retrieves event details from January 2024 onwards and does not fetch details of events that occurred before this date.

Features

  1. Filters:

    • Filter events based on various criteria:
    • Date range
    • Event name.
    • Events of a customer or groups. You can combine this with other search criteria. For example, events of a customer in a particular date range.
    • Events performed by a particular member in a user group event
    • Event ID. The event ID is an internally generated ID during the creation of the event.
    • Behavioural event attributes.
    • Duplicate events.
  2. Sorting: Sort events based on event date-time in ascending or descending order.

  3. Pagination: Limit the number of page results and setting offset (number of pages to skip from the beginning)

  4. This API provides more flexibility and search options than the GET Customer event API.

Use cases

  • You can use different combinations to search for events. For example, suppose you want to find an event named "Offerscan" performed by a particular user. In that case, you can filter the event search using the eventName parameter and by providing the identifier type and value of the customer.

  • Similarly, to retrieve details of a particular event between certain dates, you can definefromDate, tillDate, eventName and filter the events.
    https://eu.api.capillarytech.com/v2/events/search?fromDate=2024-03-19T15:31:28&tillDate=2024-04-19T16:31:28

  • Searching for an event using behavioural event attribute - For example, as a hotel chain brand, if you want to search for reservation events of a particular hotel, you can search by defining the attribute name and value. If the behavioural event attribute name is hotel_name and the hotel name is PalaceABC, you can search using the attribute name hotel_name and the value PalaceABC.
    https://eu.api.capillarytech.com/v2/events/search?fromDate=2024-03-19T15:31:28&tillDate=2024-04-19T16:31:28&hotel_name=PalaceABC

  • Searching for duplicate events of a user

    https://eu.api.capillarytech.com/v2/events/search?userIdentifierType=userId&userIdentifierValue=555734097&isDuplicate=true

  • Searching for an event with details of outcomes triggered by the occurrence of a specific event

    https://eu.api.capillarytech.com/v2/events/search?userIdentifierType=mobile&userIdentifierValue=918105886351&includeSideEffects=true

  • Searching for an event performed by a member in a group event
    https://eu.api.capillarytech.com/v2/events/search?userIdentifierType=userId&userIdentifierValue=176875087&userGroupIdentifierType=groupExternalId&userGroupIdentifierValue=bukl123


👍

Note

For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .

Prerequisites

  • Authentication; Basic or OAuth authentication details
  • Access group resource - Read access to Customer access group resource

Resource information

URIv2/events/search
HTTP methodGET
Pagination supported?Yes
Rate limitRefer to the Rate limits documentation
Batch supportNA

Request query parameters

Parameter

Type

Description

eventId

string

Primary ID of the event. This ID is internally generated during the creation of the event. Refer to Create Event to know about event creation.

eventName

string

Name of the event.

userIdentifierType

Enum

Type of user identifier: Supported values: mobile, email, and userId.

userIdentifierValue

string

Value of the user identifier.

userIdentifierSource

string

Source to search user profile. The default value is INSTORE.

userIdentifierAccountId

string

Account ID of the user profile source. Not required for INSTORE profiles.

userGroupIdentifierType

Enum

Type of user group identifier. Supported values: groupId, groupExternalId, mobile, email, and userId.

userGroupIdentifierValue

string

Value of the user group identifier.

userGroupIdentifierSource

string

Source to search user profile. The default value is INSTORE. Required if searching by mobile or email.

userGroupIdentifierAccountId

string

Account ID of the user profile source. Not required for INSTORE profiles. Required for mobile or email search.

fromDate

string

Start date in ISO format (e.g., 2024-03-19T15:31:28).

tillDate

string

End date in ISO Format (e.g., 2024-03-19T16:31:28).

limit

integer

Number of records to fetch. The default value is 10.

offset

integer

Number of records to skip from the beginning. The default value is 0.

sortOrder

string

Sorts by event date-time in ascending or descending order. The default value is desc.

includeSideEffects

boolean

Indicates whether to include loyalty side effects. The Default value is false. This parameter provides details of the outcomes triggered by the occurrence of a specific event.

isDuplicate

boolean

Indicates whether to include duplicate events. The isDuplicate field indicates whether an event is considered a duplicate or an original event. If true, it indicates that the event is a duplicate, meaning it's a repetition or a copy of a previously recorded event. Acceptable values - true or false.

allowExactMatch

boolean

Controls how the event attributes filters are matched in the search. Use this parameter to choose between exact matching and partial matching for your search. By default, the value is set to false.

Set allowExactMatch=true to return only events where the attribute value matches the full string exactly as entered. This is helpful when filtering values that include special characters like underscores (_) or hyphens (-). Example: /v2/events/search?address=colaba-mumbai&allowExactMatch=true Returns only events where the address exactly matches "colaba-mumbai".

Set allowExactMatch=false (or omit the parameter) to perform a partial match. The API splits the input into parts and matches each part independently. This allows for more flexible, forgiving searches. Example: /v2/events/search?address=colaba\ Returns events where similar parts appear in the address, such as: "colaba east", colaba market", or "colaba-mumbai".

Note: This parameter applies only to event attribute filters.

attribute

Based on the attribute

Parameter used to search behavioural events by attribute name and its corresponding value.

Scenario 1:
The event includes a standard attribute named eventDateTime with the value 1746694617000, you can retrieve it by searching on that field: Example: v2/events/search?eventDateTime=1746694617000

Scenario 2:
If an event includes a custom attribute named hotel_name with the value Hilton-Kensington, you can use the same approach to search by that attribute: Example: v2/events/search?hotel_name=Hilton-Kensington

Response parameters

ParameterDescription
orgIdThe organization ID associated with the event.
userIdThe user identifier of the customer.
dateThe date and time when the event was processed in epoch time format.
eventNameThe name of the event.
eventIdThe unique identifier for the event. This is internally generated during creation of the event.
sourceCustomer registration source profile (e.g., INSTORE).
tillCodeThe code associated with the till where the event occurred.
displayNameThe display name of the event.
additionalAttributesAdditional attributes related to the event, such as review content, account ID, and event metadata.
- The isDuplicate field indicates whether an event is considered a duplicate or an original event. If true, it indicates that the event is a duplicate, meaning it's a repetition or a copy of a previously recorded event.
- The eventDateTime is a standard attribute in the behavioural event system. This field captures the date and time when the event is processed. If you define a value for this parameter while sending the event, it displays that specific date and time in epoch format. Otherwise, it displays the event processing time, sharing the same value as the date parameter above.
clickEventSideEffectsAdditional actions or consequences triggered by events, such as awarding points or other actions.
requestIdThe unique identifier for the request associated with the event.
psiAttributesIncludes attributes that are marked as potentially sensitive data. Refer to the PSI data documentation for more information on classifying PSI data
sideEffectsAn array containing details of any side effects triggered by the event.

API Specific Error Code

Error CodeDescriptionWhen It Occurs
1850Invalid search request parameters userIdentifierValueWhen an invalid or malformed value is passed in the userIdentifierValue parameter of the search request (e.g., "77448764sd" instead of a valid value).
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!