Request Information
Update: Connection Events are now in the Replay stream -- plus a new REST endpoint!
Any connection events captured on or after July 1, 2025 will also be available in the Replay stream and this new Connections API. Older connection events are not available, but you can use the replay stream or the Connections API to reconcile the connection events you receive from the Streaming API going forward. These are two great options to ensure you haven't missed any connection events.
These events are captured when the user completes a connection or disconnection via the Inform Marketplace. See Working With A Stream for more information on these events.
Each connection event will contain a JSON encoded Validic standard object which will include a type attribute defining whether the event represents a user connection (create) or disconnection (delete) from a data source via the Inform Marketplace.
Connection events are reported by the Inform Marketplace for cloud-based (API) sources only. That means only cloud and cellular sources report connection events.
Data sources that use the Validic Mobile SDK do not report connection events.
It is worth noting that theid that is included with each connection or disconnection event is unique for every event. No two events will have the same id value.
Request Parameters
| Name | Required Field | Type | Description |
|---|---|---|---|
| start_date | optional | string | The start date to retrieve connection data for. Format: YYYY-MM-DD. Default is current UTC day. Max date range is 30 days. |
| end_date | optional | string | The end date to retrieve connection data for. Format: YYYY-MM-DD. Default is current UTC day. Max date range is 30 days. |
HTTP Response Status
| Response Code | Description |
|---|---|
| 200 (Ok) | Indicates the request was received and a result was returned. |
| 400 (Bad Request) | Indicates that there was an error with request |
Field Description
| action | string | create: the event represents a user connection via the Inform Marketplace.delete: the event represents a user disconnection from a data source via the Inform Marketplace. |
| id | string | Unique identifier for the event record. |
| profile | object | Optional -- not available from all sources. User profile details from the source profile. Only populated when action = create |
| credentials | object | Optional -- not available from all sources. Scopes or data permissions granted by the user. Only populated when action = create |
| user | object | A User object that contains identifiers related to the user. |
| user>uid | string | The customer's user ID. |
| user>user_id | string | Validic user ID. |
| user>organization_id | string | Validic organization ID. |
| source | A source object that contains source specific information. | |
| source>type | string | The source the connection event is for. |
| created_at | string | The record processed time represented in UTC. Format: YYYY-MM-DDThh:mm:ssZ. |
| event_time | string | The event time represented in UTC. Format: YYYY-MM-DDThh:mm:ssZ. |
| deleted_at | string | The record deleted time represented in UTC. Only populated when action = delete Format: YYYY-MM-DDThh:mm:ssZ. |
| deleted_reason | string | An indication of what triggered the delete. Only populated when action = delete |
Pagination Explained
This API uses the page and limit parameters for pagination. It’s crucial to understand that page does not represent page numbers or event counts directly but rather the page index.
Here's how it works:
-
Page and Limit Calculation:
- A request with no
page(defaultpage=0) andlimit=1000returns the first 1000 connection events. - A request with
page=1andlimit=1000fetches the next 1000 connection events (events 1001–2000). - Page essentially represents the page index where each page contains the number of results defined by the
limitparameter.
- A request with no
-
Iterating Through Events:
- To retrieve all connection events, increment the
pagewhile keeping thelimitfixed until you receive an empty response. - For example:
- Request:
?limit=1000&page=0→ Returns events 1–1000. - Request:
?limit=1000&page=1→ Returns events 1001–2000. - Continue incrementing the
pageuntil you receive an empty object.
- Request:
- To retrieve all connection events, increment the
-
Important Notes:
- If the total number of events is less than the calculated paging (
page * limit), the API will return an empty object. - The maximum value for
limitis 1000. If nolimitis specified, the default is 25.
- If the total number of events is less than the calculated paging (
Examples
Fetch the first 1000 events:
GET /connections?limit=1000&page=0
Fetch events 2001 to 3000:
GET /connections?limit=1000&page=2
Fetch all events (iterate until empty response):
// Start at page 0 and continue until an empty response
GET /connections?limit=1000&page=0
GET /connections?limit=1000&page=1
GET /connections?limit=1000&page=2
...