Alloy Events API
Events are how we receive ongoing data, including entities (persons, businesses), logins, bank accounts, and transactions.
OpenAPI Specification
openapi: 3.0.0
info:
title: Alloy Identity Bank Accounts Events API
version: 1.0.0
description: The Alloy Identity API provides endpoints for creating and managing person and business entities, running evaluations through configurable risk workflows, managing journey applications, submitting events for ongoing monitoring, handling document verification, and managing investigations and case alerts. Authentication is via Basic HTTP credentials or OAuth 2.0 Client Credentials.
contact:
name: Alloy Support
url: https://help.alloy.com/hc/en-us
license:
name: Proprietary
servers:
- url: https://sandbox.alloy.co/v1
description: Sandbox environment
- url: https://alloy.co/v1
description: Production environment
security:
- basic: []
- oauth2: []
tags:
- name: Events
description: Events are how we receive ongoing data, including entities (persons, businesses), logins, bank accounts, and transactions.
paths:
/events/{event_request_token}:
get:
tags:
- Events
summary: Get an event by token
description: Retrieves a previously submitted event by its event request token, including the original request body.
parameters:
- in: path
name: event_request_token
schema:
type: string
example: EV-xi7Etep0gW7gZiuWsqXG
required: true
description: The event request token returned when the event was created.
responses:
'200':
x-summary: OK
description: Event found
content:
application/json:
schema:
type: object
properties:
event_request_token:
type: string
example: EV-xi7Etep0gW7gZiuWsqXG
event_type:
type: string
description: The type of event that was submitted.
example: person_created
events_api_type_id:
type: integer
description: Internal numeric identifier for the event type.
event_status_id:
type: integer
nullable: true
description: Internal identifier for the event status, if one was assigned.
event_lifecycle_id:
type: string
nullable: true
maxLength: 128
description: Lifecycle identifier for grouping related events.
external_event_id:
type: string
nullable: true
description: External event identifier provided in the original request.
event_request_status_type_id:
type: integer
nullable: true
description: Status type of the event request (e.g. processed, error).
event_request_source:
type: string
nullable: true
description: Source of the event request (e.g. API, batch ingestion).
ingestion_batch_token:
type: string
nullable: true
description: Token of the ingestion batch, if the event was submitted via batch.
upserted_events_type_id:
type: integer
nullable: true
description: For upserted events, indicates whether the upsert resolved to a create or update.
timestamp:
type: string
format: date-time
description: Timestamp of when the event request was recorded.
body:
type: object
description: The original request body that was submitted with the event.
example:
event_request_token: EV-xi7Etep0gW7gZiuWsqXG
event_type: person_created
events_api_type_id: 1
event_status_id: null
event_lifecycle_id: null
external_event_id: audit-event-123
event_request_status_type_id: 1
event_request_source: null
ingestion_batch_token: null
upserted_events_type_id: null
timestamp: '2024-12-06T17:04:25.579Z'
body:
event_type: person_created
data:
external_entity_id: 087ac67e-17ab-4529-8d1a-a8b2214d305f
name_first: John
name_last: Smith
timestamp: '2024-12-06T17:04:25.579Z'
'404':
x-summary: NOT FOUND
description: Event not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: EV-xi7Etep0gW7gZiuWsqXG not found
/events/schema:
get:
tags:
- Events
summary: Get the schema for request event type
description: Retrieves the schema for requested event type
parameters:
- in: query
name: type
schema:
type: string
enum:
- person_created
- person_updated
- business_created
- business_updated
- bank_account_created
- bank_account_updated
- external_account_created
- external_account_updated
- transaction
- login
- credentials_updated
- embedded_authentication
- entity_group_created
- entity_group_updated
example: login
required: true
description: The type of event for the schema.
responses:
'200':
x-summary: OK
description: Returns the schema for specified events. If a workflow is attached to event, will also include supplemental data for the workflow
content:
application/json:
schema:
type: object
example:
status_code: 200
type: Object
event_type:
type: string
enum:
- login
external_event_id:
type: string
nullable: true
data:
timestamp:
type: string
supplemental_data:
type: object
properties: {}
'400':
x-summary: ERROR
description: Validation Error
content:
application/json:
schema:
type: object
/events/:
post:
tags:
- Events
summary: Create an event
requestBody:
description: 'The post bodies are fully documented in the [Request Specifications](/public/docs/api-request).
'
content:
application/json:
schema:
type: object
required:
- event_type
properties:
event_type:
type: string
enum:
- person_created
- person_updated
- business_created
- business_updated
- bank_account_created
- bank_account_updated
- external_account_created
- external_account_updated
- transaction
- login
- credentials_updated
- embedded_authentication
- modify_notification
- entity_group_created
- entity_group_updated
- card_created
- card_updated
external_event_id:
type: string
example: audit-event-123
event_status:
type: string
example: successful
description: Event statuses are customer-defined values.
data:
type: object
allOf:
- properties:
timestamp:
type: string
format: date-time
required:
- timestamp
oneOf:
- title: Person Created data
required:
- external_entity_id
allOf:
- properties:
external_entity_id:
type: string
gender:
type: string
birth_date:
type: string
document_ssn:
type: string
name_first:
type: string
name_last:
type: string
document_id_card:
type: string
document_license:
type: string
document_passport:
type: string
addresses:
type: array
description: 'List of addresses for the given entity.
'
items:
type: object
description: 'Full address for an entity. When `country_code` is `"US"`, `state` is also required.
'
required:
- line_1
- city
- postal_code
- country_code
- type
properties:
type:
type: string
description: Allowed values are (`"primary"`, `"secondary"`, `"previous"`, `"mailing"`, `"shipping"`, `"service"`, `"other"`, `"business_primary"`, `"business_secondary"`, `"business_previous"`)
example: primary
line_1:
type: string
example: 41 E. 11th
line_2:
type: string
example: 2nd floor
city:
type: string
example: New York
state:
type: string
description: Required when `country_code` is `"US"`.
example: NY
postal_code:
type: string
example: 10003
country_code:
type: string
example: US
emails:
type: array
description: 'List of emails for the given entity.
'
items:
type: object
description: Email for an entity
properties:
email_address:
type: string
example: events@alloy.com
phones:
type: array
description: 'List of phone numbers for the given entity.
'
items:
type: object
description: Phone for an entity
properties:
phone_number:
type: string
example: 5555555555
type:
type: string
enum:
- home
- cell
- fax
- work
default: home
required:
- phone_number
status:
type: string
enum:
- active
- inactive
status_detail:
type: string
nullable: true
minLength: 1
status_fraud:
type: string
enum:
- fraud
- not fraud
- $ref: '#/paths/~1entities~1persons~1%7Bentity_token%7D/patch/requestBody/content/application~1json/schema/allOf/1'
- properties:
entity_groups:
type: array
items:
type: object
anyOf:
- title: Specify Entity Group Token
required:
- entity_group_token
- title: Specify External Entity Group ID
required:
- external_entity_group_id
properties:
entity_group_token:
type: string
external_entity_group_id:
type: string
roles:
type: array
items:
type: string
enum:
- primary
- shareholder
- secondary
- beneficiary
- beneficial_owner
- control_prong
- director
- authorized_signer
- principal_owner
- coborrower
- joint
- guarantor
ownership_percentage:
type: number
title:
type: string
- title: Person Updated data
allOf:
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/0/allOf/0'
- properties:
entity_token:
type: string
example: P-R21gUOQ8rwCvmx8tIscf
- $ref: '#/paths/~1entities~1persons~1%7Bentity_token%7D/patch/requestBody/content/application~1json/schema/allOf/1'
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/0/allOf/2'
anyOf:
- title: Updated by External ID
$ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/1/properties/entities/items/anyOf/0'
- title: Updated by Entity Token
$ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/1/properties/entities/items/anyOf/1'
- title: Business Created data
required:
- external_entity_id
- business_name
allOf:
- properties:
external_entity_id:
type: string
business_name:
type: string
business_alternate_name:
type: string
business_registry_id:
type: string
business_federal_ein:
type: string
addresses:
type: array
description: 'List of addresses for the given entity.
'
items:
$ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/0/allOf/0/properties/addresses/items'
emails:
type: array
description: 'List of emails for the given entity.
'
items:
$ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/0/allOf/0/properties/emails/items'
phones:
type: array
description: 'List of phone numbers for the given entity.
'
items:
$ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/0/allOf/0/properties/phones/items'
status:
type: string
enum:
- active
- inactive
status_detail:
type: string
nullable: true
minLength: 1
status_fraud:
type: string
enum:
- fraud
- not fraud
- $ref: '#/paths/~1entities~1persons~1%7Bentity_token%7D/patch/requestBody/content/application~1json/schema/allOf/1'
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/0/allOf/2'
- title: Business Updated data
allOf:
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/2/allOf/0'
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/1/allOf/1'
- $ref: '#/paths/~1entities~1persons~1%7Bentity_token%7D/patch/requestBody/content/application~1json/schema/allOf/1'
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/0/allOf/2'
anyOf:
- title: Updated by External ID
$ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/1/properties/entities/items/anyOf/0'
- title: Updated by Entity Token
$ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/1/properties/entities/items/anyOf/1'
- title: Bank Account Created data
required:
- external_account_id
- account_number
- entities
- timestamp
allOf:
- $ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/1'
- title: Bank Account Updated data
required:
- timestamp
allOf:
- $ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/1'
- $ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/0'
anyOf:
- title: Updated by External ID
required:
- external_account_id
- title: Updated by Account Token
required:
- account_token
- title: Credentials Updated data
anyOf:
- title: Specify External Entity ID
required:
- external_entity_id
- title: Specify Entity Token
required:
- entity_token
required:
- target
- timestamp
properties:
entity_token:
type: string
external_entity_id:
type: string
external_credentials_updated_event_identifier:
type: string
description: Unique external identifier for grouping multiple credentials updated events.
target:
description: The user credential attribute that is being updated
type: string
enum:
- 2fa
- username
- password
- passkey
channel:
type: string
enum:
- contact_center
- online_banking
- in_branch
authenticated_user:
type: boolean
status:
type: string
enum:
- pending
- successful
- failed
device:
allOf:
- allOf:
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/10/properties/device/allOf/0'
properties:
registered_device:
type: boolean
2fa:
allOf:
- required:
- methods
properties:
methods:
type: array
items:
type: object
properties:
method:
type: string
enum:
- email
- voice
- sms
value:
type: string
minLength: 1
maxLength: 65535
required:
- method
- value
required:
type: boolean
default: false
operation:
type: string
enum:
- create
- delete
- update
- title: Embedded Authentication data
required:
- embedded_application
- external_entity_id
- timestamp
properties:
embedded_application:
description: The application that is embedded in the host application, e.g. Zelle
type: string
enum:
- zelle
- billpay
external_entity_id:
description: External ID of the entity interacting with the embedded application
type: string
external_embedded_authentication_id:
description: Unique external identifier for grouping multiple embedded authentication events
type: string
device:
allOf:
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/6/properties/device/allOf/0'
- title: External Account Created data
required:
- timestamp
- external_account_id
- entities
allOf:
- $ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/1'
- properties:
link_timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of when the external account was linked to the entity. If omitted, Alloy uses the top-level `timestamp` value from the `external_account_created` event.
example: '2024-06-01T12:00:00.000Z'
nullable: true
- title: External Account Updated data
required:
- timestamp
allOf:
- $ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/1'
- $ref: '#/paths/~1bank-accounts~1%7Baccount_identifier_or_token%7D/get/responses/200/content/application~1json/schema/allOf/0'
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/8/allOf/1'
- properties:
unlink_timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of when the external account was unlinked from the entity. When provided, Alloy records this as the time the account association ended.
example: '2024-09-15T08:30:00.000Z'
nullable: true
anyOf:
- title: Updated by External ID
$ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/5/anyOf/0'
- title: Updated by Account Token
$ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/5/anyOf/1'
- title: Login data
anyOf:
- title: Specify External Entity ID
required:
- external_entity_id
- title: Specify Entity Token
required:
- entity_token
required:
- login_method
- timestamp
properties:
entity_token:
type: string
external_entity_id:
type: string
external_login_id:
type: string
description: Unique identifier for grouping multiple login events into a single login.
username:
type: string
login_method:
type: string
enum:
- biometric
- password
- sso
- passwordless
sso:
type: string
enum:
- okta
- google
- apple
status:
type: string
enum:
- attempted
- failed
- mfa
- rejected
- successful
device:
allOf:
- properties:
external_device_id:
type: string
ip_address_v4:
type: string
ip_address_v6:
type: string
- title: Modify Notification data
anyOf:
- title: Specify External Entity ID
required:
- external_entity_id
- title: Specify Entity Token
required:
- entity_token
required:
- timestamp
properties:
entity_token:
type: string
external_entity_id:
type: string
external_modify_notification_event_identifier:
type: string
description: Unique external identifier for grouping multiple modify_notification events.
notification:
type: object
properties:
type:
type: string
enum:
- account
- general
- security
- transaction
subtype:
type: string
minLength: 1
required:
- type
- subtype
notification_target:
type: array
items:
type: object
properties:
method:
type: string
enum:
- email
- voice
- sms
- message_center
- push_notification
value:
type: string
minLength: 1
required:
- method
- value
enabled:
type: boolean
operator:
type: string
enum:
- less_than
- greater_than
- equals
external_account_id:
type: string
amount:
type: integer
device:
allOf:
- $ref: '#/paths/~1events~1/post/requestBody/content/application~1json/schema/properties/data/oneOf/6/properties/device/allOf/0'
- title: Transaction data
allOf:
- properties:
external_transaction_id:
description: Unique external identifier for the transaction.
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/alloy/refs/heads/main/openapi/alloy-events-api-openapi.yml