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:

https://api.apiture.com/banking

Email: Apiture Web: Apiture

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 and token_endpoint to obtain an access token to pass in the Authorization 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

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 activity type.

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`