Events API (Preview)
Download OpenAPI specification:Download
Welcome to the preview documentation for the Paxos Events APIs. The Events APIs are in the early preview stage and as a result will be updated regularly as new functionality becomes ready.
This document contains proposed additions to the main Paxos API 2.0 documentation. The additions here are subject to breaking changes until merged into the main documentation.
The Events API allows you to fetch events that occurred on the Paxos platform with the full event payload. This REST API can be used as part of your webhook integrations (including rebuilding your event history should your webhook consumer exceed its retries), or standalone by polling for events related to your identities.
Types of Events
Currently the below events are the only types available, more will be added over time. If your desired events are not listed yet, feel free to reach out here to let us know your use-case.
| Event Type | Description | Object |
|---|---|---|
identity.documents_required | Occurs when an identity is deemed high risk by Paxos and additional documents are required for enhanced due diligence | identity_documents_required |
identity.approved | Occurs when an identity lands in an approved status | identity_summary_status_change |
identity.denied | Occurs when an identity lands in a denied status | identity_summary_status_change |
identity.disabled | Occurs when an identity lands in a disabled status | identity_summary_status_change |
identity.kyc_refresh.started | Occurs when an identity is required to undergo its periodic KYC refresh | identity_kyc_refresh |
identity.kyc_refresh.completed | Occurs when an identity has finished its periodic KYC refresh | identity_kyc_refresh |
identity.kyc_refresh.expired | Occurs when an identity has not completed its KYC refresh within the designated window, and has now expired | identity_kyc_refresh |
Supported Objects
identity_documents_required
| Attribute | Type | Description |
|---|---|---|
id | UUID | The unique identifier for the identity_documents_required object |
identity_id | UUID | The unique identifier for the identity that documents are required for |
required_documents | list enum of document types | The list of required documents for the identity_id |
reason | list enum ([”SCREENING_HIT”, “KYC_EXPIRED”, “HIGH_RISK”, “IDV_FAILED”]) | Optional field that may or may not be populated with additional context |
identity_summary_status_change
| Attribute | Type | Description |
|---|---|---|
id | UUID | The unique identifier for the identity_status_change object |
identity_id | UUID | The unique identifier for the identity that the status change relates to |
old_summary_status | enum ([”PENDING”, ”ERROR”, ”APPROVED”, ”DENIED”, ”DISABLED”]) | The summary status of the identity_id prior to to the change |
new_summary_status | enum ([”PENDING”, ”ERROR”, ”APPROVED”, ”DENIED”, ”DISABLED”]) | The summary status of the identity_id after the change |
reason | list enum ([”SCREENING_HIT”, “KYC_EXPIRED”, “HIGH_RISK”, “IDV_FAILED”]) | Optional field that may or may not be populated with additional context |
identity_kyc_refresh
| Attribute | Type | Description |
|---|---|---|
id | UUID | The unique identifier for the identity_kyc_refresh object |
identity_id | UUID | The unique identifier for the identity that the KYC refresh relates to |
last_kyc_refresh_date | Datetime | Optional field that may or may not be populated with additional context |
next_kyc_refresh_date | Datetime | Optional field that may or may not be populated with additional context |
List Events
This endpoint enables you to fetch a list of events that have been created by the system.
You can use query parameters to filter the results by the created_at time using range_begin and you can
limit the number of events returned.
Using created_at and limit together will allow you to paginate through all events owned by you.
Events returned will always be order in created_at ascending order.
Authorizations:
query Parameters
| range_begin | string <date-time> The timestamp of the start of the range to filter events by, RFC3339 format, like |
| limit | integer <int32> Number of results to return. Defaults to 100 if no limit is provided. |
Responses
Response samples
- 200
- 400
- 403
{- "events": [
- {
- "id": "d99a03ee-6b88-4362-89da-087c2c8cd4a7",
- "event_type": "identity.approved",
- "object_type": "identity_summary_status_change",
- "object": {
- "id": "d840cf31-352f-4190-a476-7522bf3eafda",
- "identity_id": "4fd025ab-f29f-47e6-a02e-df90a61c7ec9",
- "previous_summary_status": "PENDING",
- "next_summary_status": "APPROVED"
}, - "created_at": "2023-08-25 14:25:41 UTC"
}, - {
- "id": "19c0ae8e-fdfc-4b27-88af-07762af8f2a8",
- "event_type": "identity.documents_required",
- "object_type": "identity_documents_required",
- "object": {
- "id": "d11aba88-39cd-4445-acbb-e4d127588def",
- "identity_id": "fc9dcae4-5411-464c-a20e-f0911ee1c5c1",
- "required_documents": [
- "TAX_IDENTIFICATION",
- "PROOF_OF_RESIDENCY",
- "PROOF_OF_FUNDS"
]
}, - "created_at": "2023-08-24 18:29:41 UTC"
}
]
}Get Event
Get an Event by its (event) id, the event must have been created by the system and you must be the owner of the the event, you can get an event id by either listing events or via a webhook integration.
Authorizations:
path Parameters
| id required | string The unique |
Responses
Response samples
- 200
- 400
- 403
- 404
{- "id": "d99a03ee-6b88-4362-89da-087c2c8cd4a7",
- "event_type": "identity.approved",
- "object_type": "identity_summary_status_change",
- "object": {
- "id": "d840cf31-352f-4190-a476-7522bf3eafda",
- "identity_id": "4fd025ab-f29f-47e6-a02e-df90a61c7ec9",
- "previous_summary_status": "PENDING",
- "next_summary_status": "APPROVED"
}, - "created_at": "2023-08-25 14:25:41 UTC"
}