Events v0.1.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Describes events and event messages which convey activity in the Apiture digital banking platform.
An event is an action that has occurred at a point in time (such as: customer logged in, account beneficiary added, payment batch approved, etc.). An event is an abstraction. Each kind of event has an event type. Related events are also organized into categories. Each event type belongs to one category.
An event message is a concrete data packet representation of an event, its associated payload, and additional event metadata (such as a unique event ID, timestamp, etc.). There can be many event messages over time for each event type.
Download OpenAPI Definition (YAML)
Base URLs:
License: Apiture API License
Authentication
- API Key (
apiKey
)- header parameter: API-Key
- API Key based client identification. See details at Secure Access.
- OpenID Connect authentication (
accessToken
)- OpenId Connect (OIDC) authentication/authorization. The client uses the
authorization_endpoint
andtoken_endpoint
to obtain an access token to pass in theAuthorization
header. Those endpoints are available via the OIDC Configuration URL. The actual URL may vary with each financial institution. See details at Secure Access. - OIDC Configuration URL =
https://oidc.apiture.com/oidc/.well-known/oidc-configuration
- OpenId Connect (OIDC) authentication/authorization. The client uses the
Schemas
accountRoutingNumber
"stringstr"
Account Routing Number (v1.0.0)
A reusable type for an account routing number.
Type: string
minLength: 9
maxLength: 9
pattern: ^[0-9]{9}$
eventAccountReference
{
"id": "a212d3c119148960683d",
"maskedNumber": "*3210",
"routingNumber": "021000021"
}
Account Reference (v1.0.0)
A referfence to a banking accuont.
Properties
Name | Description |
---|---|
id | string: resourceId (required) The resource ID of the banking account. minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
maskedNumber | string: maskedAccountNumber (required) A masked account number: an asterisk * followed by one to four characters of the fullAccountNumber .minLength: 2 maxLength: 5 pattern: ^\*[- _a-zA-Z0-9.]{1,4}$ |
routingNumber | string: accountRoutingNumber (required) The account's routing and transit number. minLength: 9 maxLength: 9 pattern: ^[0-9]{9}$ |
eventAgentType
"customer"
Event User Type (v0.1.0)
Describes the type of agent (user or actor) that performed the action that triggered an event.
eventAgentType
strings may have one of the following enumerated values:
Value | Description |
---|---|
customer | Customer: A banking customer |
operator | Operator: A financial institution operator or administrator |
system | System: A system process or job, not an interactive person |
Type: string
enum values: customer
, operator
, system
eventMessageItem
{
"id": "0399abed30f38b8a365c",
"institutionId": "TIBURON",
"correlationId": "da2da17214b86185fb9e",
"type": "singleTransferScheduled",
"category": "moneyMovement",
"occurredAt": "2019-09-13T05:03:50.375Z",
"agentId": "4f3ec1daab02eed9de64",
"agentType": "customer",
"coreCustomerId": "138929",
"host": "13.226.38.34",
"primaryId": "a727ff2aedea60646819",
"data": {
"sourceAccount": "*3210",
"sourceRoutingNumber": "021000021",
"targetAccount": "*3219",
"targetRoutingNumber": "021000021"
}
}
Event Item (v0.1.0)
A data record representing a banking activity or action performed by a user. This conveys:
- who did something (
agentId
,agentType
,coreCustomerId
) - what they did (
type
,category
), - when they did it (
occurredAt
), - where they did it (
host
), - what they did it to (
primaryId
,secondaryId
) - additional
data
that is specific to the activitytype
.
The type
is a key into the set of event types . Each type has a corresponding JSON schema that defines the layout of the data
object. The schema name is derived from the type
name by adding EventSchema
. For example, the transferScheduled
event type's data
is defined by the schema named transferScheduledEventSchema
.
Properties
Name | Description |
---|---|
id | string: resourceId (required) The unique identifier for this event. This is an immutable opaque string. minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
institutionId | string: institutionId The unique identifier of the financial institution, if applicable. minLength: 2 maxLength: 9 pattern: ^[A-Z0-9_]{2,8}$ |
correlationId | string: resourceId An identifier that allows correlating multiple events. This may represent a business process transaction ID or service request ID. minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
sessionId | string: resourceId The customer session ID, if known. User login starts a session. minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
type | string (required) The type of this event. This is the key into the set of event types. This is a lowerCamelCase string. minLength: 4 maxLength: 48 pattern: [a-z][a-zA-Z0-9]{3,47} |
category | number (required) An identifier for the category of the record type. Multiple record types can belong to a category. This is a lowerCamelCase string. minLength: 4 maxLength: 40 pattern: [a-z][a-zA-Z0-9]{3,39} |
occurredAt | string(date-time): timestamp (required) The date-time when the action occurred or logged. The time is approximate. This is an RFC 3339 UTC date-time string. minLength: 20 maxLength: 30 |
agentId | string: resourceId The unique immutable ID of the agent that performed the action that triggered this event. If agentType is customer then the agent ID is the customer ID; if agentType is operator then the agent ID is the operator/administrator ID; if agentType is system then the agent ID is the process/job name.minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
agentType | string: eventAgentType (required) Indicates what type of agent or actor performed the operation that triggered this event. enum values: customer , operator , system |
coreCustomerId | string: resourceId The unique ID of the customer in the banking core. This is only present if agentType is customer .minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
requesterId | string: resourceId The unique immutable ID of the operator who is acting on behalf of the user identified by the agentId and agentType is customer . This is also known as user emulation.minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
host | string The host IP address of client which was used for this activity, if known. maxLength: 32 |
primaryId | string: resourceId The optional unique system ID of the the primary resource that this activity applies to. For example, if a transfer if scheduled or canceled, this is the ID of the transfer. minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
secondaryUri | string: resourceId The optional unique system ID of a secondary resource that this activity applies to, if any. minLength: 6 maxLength: 48 pattern: ^[-_:.~$a-zA-Z0-9]+$ |
data | object: abstractEventSchema Additional properties of the event, represented as a type -specific object. |
eventMessages
{
"version": "0.1.0",
"startsAt": "2022-12-02T11:00:00.000",
"endsAt": "2022-12-02T11:10:00.000Z",
"items": [
{
"id": "b844b2d641da",
"institutionId": "TIBURON",
"category": "authentication",
"type": "userLoggedIn",
"occurredAt": "2022-12-02T11:08:00.375Z",
"correlationId": "0730fd7ac6bfe5a87b0a",
"sessionId": "2ded0203a8a2b6e7befa",
"agentId": "4f3ec1daab02eed9de64",
"coreCustomerId": "12299292",
"agentType": "customer",
"host": "13.226.38.34",
"primaryId": "b844b2d6d9ca818df3c8",
"data": {
"mfaRequired": true,
"browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36",
"operatingSystem": "macos",
"platform": "web",
"application": "apitureDigitalBanking",
"score": 0
}
},
{
"id": "0399abed30f38b8a365c",
"institutionId": "TIBURON",
"category": "moneyMovement",
"type": "singleTransferScheduled",
"occurredAt": "2022-12-02T11:08:00.375Z",
"correlationId": "2266452a0bfd8150cf64",
"sessionId": "2ded0203a8a2b6e7befa",
"agentId": "4f3ec1daab02eed9de64",
"coreCustomerId": "12299292",
"agentType": "customer",
"host": "13.226.38.34",
"primaryId": "a727ff2aedea60646819",
"data": {
"sourceAccount": {
"id": "a212d3c119148960683d",
"maskedNumber": "*3210",
"routingNumber": "021000021"
},
"targetAccount": {
"id": "0c8ad50ab6cf0eb48c25",
"maskedNumber": "*3219",
"routingNumber": "021000021"
}
}
}
]
}
Event Messages (v0.1.0)
A list of events within a time frame.
Properties
Name | Description |
---|---|
version | string(semver) (required) The semantic version number of the event metadata structure. enum values: 0.1.0 |
startsAt | string(date-time): timestamp The beginning date-time for the events in this page of event messages. This is an RFC 3339 UTC date-time string. minLength: 20 maxLength: 30 |
endsAt | string(date-time): timestamp The ending date-time for the events in this page of event messages. This is an RFC 3339 UTC date-time string. minLength: 20 maxLength: 30 |
items | array: [eventMessageItem] (required) An array of event items. |
institutionId
"TIBURON"
Institution ID (v1.0.0)
The unique immutable identifier of a financial institution.
Type: string
minLength: 2
maxLength: 9
pattern: ^[A-Z0-9_]{2,8}$
maskedAccountNumber
"*1008"
Masked Account Number (v1.0.1)
A masked account number: an asterisk *
followed by one to four characters of the fullAccountNumber
.
Type: string
minLength: 2
maxLength: 5
pattern: ^*[- _a-zA-Z0-9.]{1,4}$
resourceId
"string"
Resource Identifier (v1.0.0)
The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.
Type: string
minLength: 6
maxLength: 48
pattern: ^[-_:.~$a-zA-Z0-9]+$
singleTransferScheduledEventSchema
{
"sourceAccount": {
"id": "a212d3c119148960683d",
"maskedNumber": "*3210",
"routingNumber": "021000021"
},
"targetAccount": {
"id": "0c8ad50ab6cf0eb48c25",
"maskedNumber": "*3219",
"routingNumber": "021000021"
}
}
Single Transfer Scheduled Event Schema (v0.1.0)
An event message for when a customer has scheduled a single account-to-account transfer. The transfer resource ID is captured in the event's primaryId
.
Properties
Name | Description |
---|---|
sourceAccount | object: eventAccountReference (required) The source account from which the funds are debited. |
targetAccount | object: eventAccountReference (required) The account where the funds are credited. |
timestamp
"2021-10-30T19:06:04.250Z"
Timestamp (v1.0.0)
A timestamp (an instant in time) formatted in YYYY-MM-DDThh:mm:ss.sssZ
RFC 3339 date-time
UTC format.
The schema timestamp
was added on version 0.4.0
of the API.
Type: string(date-time)
minLength: 20
maxLength: 30
userLoggedInEventSchema
{
"mfaRequired": true,
"browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36",
"operatingSystem": "macos",
"platform": "web",
"application": "apitureDigitalBanking",
"score": 0
}
User Logged In Event Schema (v0.1.0)
Event message sent when a user has logged in. The authenticated user's resource ID is captured in the event's userId
.
Properties
Name | Description |
---|---|
mfaRequired | boolean (required) Indicates if Multi-Factor Authentication (MFA) was required to complete the login. |
browser | string The browser or user agent used to complete the login. maxLength: 160 |
operatingSystem | string The name of operating system of the device used to complete the login, if known. maxLength: 32 |
platform | string The type of client application the user used when logging in. enum values: web , mobile , voice , sms , other , unknown |
application | string (required) The application into which the user logged in. The reserved names apitureDigitalBanking and apitureMobile represent Apiture's web and mobile applications. unknown if the application is not known.maxLength: 32 |
score | integer (required) A proprietary ADB value that indicates how unusual the login was. Lower values are least unusual; higher numbers are more unusual. minimum: 0 maximum: 100 |