Events

Events API provides a way to listen for events of interest as they relate to your program. For example, you may want to listen for Account status changes or Transactions as they occur.

There are two approaches to consume events, traditional poll request and event streaming using Server-Sent Events. You might first want to consider the approach that best suits your architecture.

Poll Events

A standard request to GET /events will trigger the polling mechanism to fetch events based on the filters provided. This is standard request/response flow. The endpoint will hold the connection until either event(s) are returned or a timeout has occurred. The timeout is random but is at a maximum 1-minute long.

The response will contain the last_sequence_number in the event list which can be used in a subsequent request.

GET /events

Response:

{
  "data": [
    {
      "id": "c773c2bb-be73-4400-889c-df823ebc849e",
      "program_id": "cf2d36e4-68cc-4b10-9dd5-17ac5e07d60f",
      "sequence_number": 1,
      "created_dt": "2022-01-02T03:04:05.123456-05:00",
      "type": "PROFILE_ACCOUNT_STATUS",
      "data": {
        "id": "2c52e04d-9688-4b9c-be4a-87468b2cb2e8",
        "profile_ids": [
          "f54e01b2-1cde-4ea5-b6ba-0b8031d3b1ad"
        ],
        "name": "Basic Checking",
        "status": "PENDING",
        "account_number_last_four": "1234",
        "routing_number": "000000000",
        "created_dt": "2022-01-01T01:00:00.123456-05:00",
        "updated_dt": "2022-01-02T03:04:05.123456-05:00"
      }
    }
  ],
  "last_sequence_number": 1,
  "limit": 100
}

Stream Events

Using the event stream endpoint, you can listen for events as they unfold in real-time. The endpoint returns events matching the criteria provided and sends events using the Server-Sent Events (SSE) standard once a connection has been established. This requires setting the Accept header to text/event-stream.

Sample CURL Request

curl -X GET https://api.test.figurepay.com/events/stream \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer <access_token>'

Response

id: 1
data: [{"id":"c773c2bb-be73-4400-889c-df823ebc849e","type":"PROFILE_ACCOUNT_STATUS","program_id":"cf2d36e4-68cc-4b10-9dd5-17ac5e07d60f","sequence_number":"1","created_dt":"2022-01-02T03:04:05.123456-05:00","data":{"id": "2c52e04d-9688-4b9c-be4a-87468b2cb2e8","profile_ids": ["f54e01b2-1cde-4ea5-b6ba-0b8031d3b1ad"],"name": "Basic Checking","status": "PENDING","account_number_last_four": "1234","routing_number": "000000000","created_dt": "2022-01-01T01:00:00.123456-05:00","updated_dt": "2022-01-02T03:04:05.123456-05:00"}}]

Here the id is treated as the last_sequence_number. If the connection fails or is complete, you can use this to set your starting point.

Retrieve a single event

Fetch a single event by either its id or sequence_number for the authenticated program.

GET /event/:id

GET /event/sequence/:sequence_number

Event Types

Every event has a data field with contents related to the specific event type. This is a list of all current event types.

info

This list is subject to be updated as more types may be added.

Type	Description
account_statement_created	Account statement was inserted
card_changed	Card was inserted or updated
card_status	Card status was changed
invoice_changed	Invoice was inserted or updated
invoice_status	Invoice status was changed
profile_changed	Profile was inserted or updated
profile_status	Profile status was changed
profile_account_changed	Profile account was inserted or updated
profile_account_status	Profile account status was changed
program_account_changed	Program account was inserted or updated
program_account_status	Program account status was changed
transaction_changed	Transaction was inserted or updated
transaction_status	Transaction status was changed

The data model that corresponds with each model type is the full model definition of that object irrespective of if the event is for a _changed event or a _status event. The _status events are a subset of the _changed events given that they are only emitted when the status is first set or updated, whereas any change will emit a _changed event.