Alloy Events API

openapi: 3.2.0
info:
  title: Alloy Com Events API
  version: '1.0'
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: alloy-com-identity-api-openapi.yml, alloy-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://sandbox.alloy.co/v1
  description: Sandbox environment
- url: https://alloy.co/v1
  description: Production environment
- url: https://api.alloy.co/v1
  description: Production environment
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
                    - 'null'
                    description: Internal identifier for the event status, if one was assigned.
                  event_lifecycle_id:
                    type:
                    - string
                    - 'null'
                    maxLength: 128
                    description: Lifecycle identifier for grouping related events.
                  external_event_id:
                    type:
                    - string
                    - 'null'
                    description: External event identifier provided in the original request.
                  event_request_status_type_id:
                    type:
                    - integer
                    - 'null'
                    description: Status type of the event request (e.g. processed, error).
                  event_request_source:
                    type:
                    - string
                    - 'null'
                    description: Source of the event request (e.g. API, batch ingestion).
                  ingestion_batch_token:
                    type:
                    - string
                    - 'null'
                    description: Token of the ingestion batch, if the event was submitted via batch.
                  upserted_events_type_id:
                    type:
                    - integer
                    - 'null'
                    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
      security:
      - basic: []
      - oauth2: []
    parameters:
    - name: event_request_token
      in: path
      required: true
      schema:
        type: string
    servers:
    - url: https://sandbox.alloy.co/v1
      description: Sandbox environment
    - url: https://alloy.co/v1
      description: Production environment
  /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
                    - 'null'
                  data:
                    timestamp:
                      type: string
                    supplemental_data:
                      type: object
                      properties: {}
        '400':
          x-summary: ERROR
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
      security:
      - basic: []
      - oauth2: []
    servers:
    - url: https://sandbox.alloy.co/v1
      description: Sandbox environment
    - url: https://alloy.co/v1
      description: Production environment
  /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
                          - 'null'
                          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
                          - 'null'
                          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
                          - 'null'
                          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'
                  - 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
                          - 'null'
                          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'
                    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:
                  

# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/alloy-com/refs/heads/main/openapi/alloy-com-events-api-openapi.yml