Log In / Register

Event History API

The Events History API is used to programmatically access stored digital banking events. For more general information on Events, read our conceptual documentation on events.

This API must only be used by secure applications in machine-to-machine (M2M) interactions, such as scripts and server-side applications.

The event messages provided by the API are structured as a JSON object. The structure of this object is described in the General Structure article.

The event message JSON structure and data is nearly the same as events delivered by the Flat File Delivery. However, the Events History API allows a consumer to get event data more frequently and efficient than programmatically reading a flat file.

Using the Event History API

The Event History API requires authentication with client credentials before it can be accessed. Once authenticated, two methods can be used to retrieve events:

  • The application routinely polls the events that happened since the last watermark was created.

  • The application can retrieve events that occurred within a specific date-time range.

Both of these methods are described below, along with ways filters can be applied to get relevant information for the application.

Authentication

Client credential authentication is required to access the Event History APIs.

Client credential authentication is used to to validate M2M connections where there is not a human user. This type of authentication is documented in Authenticate using OAuth 2.0 Client Credentials Flow.

Polling Events with a Watermark

When a secured client periodically requests a list of any new events from the API, a watermark is sent with the request indicating which event messages were returned previously.

Each response from the API returns the event message data starting at the watermark and also returns a new watermark. The client should keep the watermark for the next time the job polls for new events.

Event messages are sorted in ascending order.

Note: An event message may be recorded after a watermark was created, even when the actual occurrence of the event was several minutes beforehand. That event message would be included the next time events are gathered using a watermark.

Read Event History using the Watermark

Use the listRecentEventHistory operation to fetch the event messages that have been recorded since the last watermark was created. Perform an authenticated GET request to:

GET /banking/recentEventHistory

The watermark query parameter should be assigned the same value as the watermark contained in the response from the last poll. When the response in received, the value of watermark should be stored for the next request.

Each response is limited to 10,000 event messages. If there are more than 10,000 event messages, the hasMore property in the response has a value of true. Use the watermark in the response to fetch the next events after the new watermark, until hasMore is false.

If this is the first time the operation has been called and/or there is no watermark, the response contains a few of the most recent event messages.

View the API documentation for a full example of the data formatting.

Gathering Event History by Date-Time

If the application needs to know which events happened during a specific timespan, events can alternatively be gathered by date and time.

Event history gathered this way can also be sorted by date-time by using the sortBy filter.

Note: There is always a slight delay between when an event occurs and when it is recorded in the event history and available via the API.

Read Event History by Date-Time

Use the listEventHistory operation to fetch a paginated list of events between a starting and an ending date-time.

GET /banking/eventHistory

The occuredAt property is used to select the date range and functions like the Range Filters described in Collection Filtering. occuredAt can be a YYYY-MM-DD date without a time component (such as 2023-06-01), a range with a start and end date without a time, or with a start and end date-time. Further examples are given in the full API documentation.

Normal Pagination rules are used to page through results. For more information on Pagination, see Collection Pagination.

The events return in descending order by default. Use ?sortBy=occurredAt for ascending order and use ?sortBy=-occurredAt for directly requesting descending order.

View the API documentation for a full example of the data formatting.

Filtering

Filters reduce the amount of data returned. Filters can be used whether the event history is gathered by Date-Time or gathered with a watermark. For general information on filters, see Collection Filtering.

The following filters are available for Event History. A pipe-delimited list can be used when a filter needs multiple entries:

  • type : The type of event message indicates what event was triggered. Event types are listed in General Structure. A list of event types can be gathered programmatically, as documented in Retrieving Event Types.

  • category : Each event message type belongs to an event category. Event categories are listed in General Structure.

  • sessionId : Session IDs are created every time a user is authenticated and identify a specific period of user activity.

  • agentId: An agentID identifies a specific user.

For more details, such as the maximum length, view our Event History API documentation.

listEventHistory can also use the sortBy query parameter, which is discussed in the Read Event History by Date-Time section.

Retrieving Event Types

listEventTypes returns a JSON list of all events. Perform an authenticated GET request to:

GET /banking/eventTypes

The response is formatted like the example below:

				
					{
  "items": [
    {
      "type": "singleTransferCreated",
      "category": "transfers",
      "description": "Payload for event messages triggered when a user has created a single account-to-account transfer.",
      "primaryIdDescription": "the transfer resource",
      "schemaId": "https://api.apiture.com/schemas/bankingEvents/singleTransferCreated"
    },
    {
      "type": "singleTransferScheduled",
      "category": "transfers",
      "description": "Payload for event messages triggered when a customer has scheduled a single account-to-account transfer.",
      "primaryIdDescription": "the transfer resource",
      "schemaId": "https://api.apiture.com/schemas/bankingEvents/singleTransferScheduled"
    },...
  ],
  "eventsEnabled": true
}

getEventTypesJsonSchema retrieves the JSON schemas for all events. The JSON schemas are returned in the response to the following GET request:

GET /banking/eventTypesJsonSchema

A full example of the response can be viewed in the API documentation.

On this page