> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook Event Payloads & Data Structures
> Detailed payload structures, field definitions, and examples for every Corsa webhook event type.
## Payload Structure
Every webhook event follows one of two structures depending on whether it is a `created` or `updated` event.
### Created Event
When an entity is created, the full entity object is included in the payload:
| Field | Type | Description |
| ------------------ | -------- | --------------------------------------------------- |
| `type` | `string` | The event type (e.g., `individual_client.created`). |
| `timestamp` | `string` | ISO 8601 timestamp of when the event occurred. |
| `data.id` | `string` | Unique identifier of the entity. |
| `data.referenceId` | `string` | External reference ID (if set). |
| `data.entity` | `object` | The full entity object at the time of creation. |
### Updated Event
When an entity is updated, the payload includes only the changed fields along with the previous values:
| Field | Type | Description |
| --------------------- | -------- | --------------------------------------------------- |
| `type` | `string` | The event type (e.g., `individual_client.updated`). |
| `timestamp` | `string` | ISO 8601 timestamp of when the event occurred. |
| `data.id` | `string` | Unique identifier of the entity. |
| `data.referenceId` | `string` | External reference ID (if set). |
| `data.updated` | `object` | Only the fields that changed in this update. |
| `data.previousValues` | `object` | The previous values for each changed field. |
***
## Individual Client
**Events:** `individual_client.created`, `individual_client.updated`
```json theme={null}
{
"type": "individual_client.created",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123",
"entity": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123",
"accountStatus": "APPROVED",
"activityStatus": "ACTIVE",
"general": {
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"gender": "MALE",
"dateOfBirth": "1993-08-15",
"citizenship": "USA",
"jurisdiction": "US",
"personalId": "123-45-6789"
},
"address": {
"addressLine1": "123 Main Street",
"addressLine2": "Apt 4B",
"city": "New York",
"country": "USA",
"postalCode": "10001"
},
"contact": {
"emailAddress": "john.doe@example.com",
"phoneNumber": "+1-555-123-4567"
},
"application": {
"submittedAt": "2023-08-15T10:30:00Z",
"onboardedAt": "2023-08-20T14:00:00Z",
"nextPeriodicReview": "2024-08-20T14:00:00Z",
"kycTier": "TIER_1"
},
"financial": {
"annualDepositEstimate": "100000"
},
"work": {
"occupation": "Software Engineer"
},
"currentRisk": {
"score": 15,
"level": "LOW",
"calculatedAt": "2023-08-20T14:00:00Z"
},
"onboardingRisk": {
"score": 15,
"level": "LOW",
"calculatedAt": "2023-08-20T14:00:00Z"
},
"riskHistory": [],
"politicalExposure": {
"isPoliticallyExposed": false
},
"sanctions": {
"isSanctioned": false
},
"adverseMedia": {
"isAdverseMedia": false
},
"tags": ["vip-client"],
"controls": [],
"declaredAssets": ["BTC", "ETH"],
"alerts": [],
"financialOperations": [],
"createdAt": "2023-08-15T10:30:00Z",
"updatedAt": "2023-08-20T14:30:00Z"
}
}
}
```
```json theme={null}
{
"type": "individual_client.updated",
"timestamp": "2024-02-10T08:15:00.000Z",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123",
"updated": {
"accountStatus": "FROZEN",
"currentRisk": {
"score": 85,
"level": "HIGH",
"reason": "Multiple high-value transactions in high-risk jurisdictions",
"calculatedAt": "2024-02-10T08:15:00Z"
}
},
"previousValues": {
"accountStatus": "APPROVED",
"currentRisk": {
"score": 15,
"level": "LOW",
"calculatedAt": "2023-08-20T14:00:00Z"
}
}
}
}
```
| Field | Type | Description |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `accountStatus` | `string` | `APPROVED`, `WAITING_FOR_REVIEW`, `IN_REVIEW`, `REJECTED`, `OFF_BOARDED`, `FROZEN`, `PENDING_DOCUMENTS`, `CLOSED_BY_CLIENT`, `APPLICATION_IN_PROGRESS`. |
| `activityStatus` | `string` | `ACTIVE`, `NOT_ACTIVE`. |
| `general` | `object` | First name, last name, middle name, gender, date of birth, citizenship, jurisdiction, personal ID. |
| `address` | `object` | Address line 1/2, city, country, postal code. |
| `contact` | `object?` | Email address, phone number. |
| `application` | `object` | Submitted at, onboarded at, next periodic review, KYC tier (`TIER_1`, `TIER_2`, `TIER_3`). |
| `financial` | `object?` | Annual deposit estimate. |
| `work` | `object?` | Occupation. |
| `currentRisk` | `object?` | Risk assessment (`score`, `level`, `reason`, `calculatedAt`). |
| `onboardingRisk` | `object?` | Onboarding risk assessment. |
| `riskHistory` | `array` | Historical risk assessments. |
| `politicalExposure` | `object` | PEP information (`isPoliticallyExposed`). |
| `sanctions` | `object` | Sanctions information (`isSanctioned`). |
| `adverseMedia` | `object` | Adverse media information (`isAdverseMedia`). |
| `tags` | `string[]` | Tags associated with the client. |
| `customFields` | `object?` | Custom fields defined for the platform. |
| `declaredAssets` | `string[]?` | Asset symbols (e.g., `BTC`, `ETH`). |
| `alerts` | `string[]?` | Associated alert IDs. |
| `financialOperations` | `string[]?` | Associated financial operation IDs. |
| `integrations` | `object?` | Third-party integration IDs (Sardine, Chainalysis, SumSub, Plain). |
| `partnerClientId` | `string?` | ID of the partner corporate client. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Corporate Client
**Events:** `corporate_client.created`, `corporate_client.updated`
```json theme={null}
{
"type": "corporate_client.created",
"timestamp": "2024-01-10T09:00:00.000Z",
"data": {
"id": "c8f2e3a1-b5d4-4e6f-9a1b-2c3d4e5f6a7b",
"referenceId": "CORP-001",
"entity": {
"id": "c8f2e3a1-b5d4-4e6f-9a1b-2c3d4e5f6a7b",
"referenceId": "CORP-001",
"accountStatus": "APPROVED",
"activityStatus": "ACTIVE",
"general": {
"legalEntityName": "Acme Corporation Ltd",
"jurisdiction": "US",
"dateOfIncorporation": "2020-01-01",
"countryOfIncorporation": "USA"
},
"address": {
"registrationAddress": {
"country": "USA",
"city": "New York",
"postalCode": "10001",
"addressLine1": "456 Corporate Blvd",
"addressLine2": "Floor 12"
},
"businessAddress": {
"country": "USA",
"city": "San Francisco",
"postalCode": "94105",
"addressLine1": "789 Market Street"
}
},
"application": {
"submittedAt": "2023-12-01T00:00:00Z",
"onboardedAt": "2024-01-10T09:00:00Z",
"nextPeriodicReview": "2025-01-10T09:00:00Z"
},
"business": {
"industry": "Technology",
"description": "A blockchain technology company",
"businessType": "BLOCKCHAIN_NATIVE",
"businessSubType": "TOKEN_PROJECT",
"ownershipType": "PRIVATELY_HELD",
"ownershipComplexity": "SIMPLE_OWNERSHIP",
"incorporationType": "CORPORATION"
},
"sourceOfFundsInfo": {
"sourceOfFunds": "PROPRIETARY_FUNDS",
"sourceOfFundsDetails": "Investment portfolio",
"sourceOfFundsJurisdictions": ["GBR", "USA"],
"monthlyTransactionVolume": 500000,
"annualTransactionVolume": 6000000
},
"adverseMedia": {
"adverseMediaRiskLevel": "NONE",
"adverseMediaScore": 0
},
"politicalExposure": {
"isPoliticallyExposed": false,
"pepTier": "NO_PEP",
"pepScore": 0
},
"screening": {
"hasSubpoena": false,
"hasSAR": false
},
"currentRisk": {
"score": 45,
"level": "LOW",
"calculatedAt": "2024-01-10T09:00:00Z"
},
"riskHistory": [],
"tags": ["fintech"],
"controls": [],
"declaredAssets": ["BTC", "ETH", "USDT"],
"createdAt": "2024-01-10T09:00:00Z",
"updatedAt": "2024-01-10T09:00:00Z"
}
}
}
```
```json theme={null}
{
"type": "corporate_client.updated",
"timestamp": "2024-03-05T14:20:00.000Z",
"data": {
"id": "c8f2e3a1-b5d4-4e6f-9a1b-2c3d4e5f6a7b",
"referenceId": "CORP-001",
"updated": {
"activityStatus": "NOT_ACTIVE",
"tags": ["fintech", "under-review"]
},
"previousValues": {
"activityStatus": "ACTIVE",
"tags": ["fintech"]
}
}
}
```
| Field | Type | Description |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `accountStatus` | `string` | `APPROVED`, `WAITING_FOR_REVIEW`, `IN_REVIEW`, `REJECTED`, `OFF_BOARDED`, `FROZEN`, `PENDING_DOCUMENTS`, `CLOSED_BY_CLIENT`, `APPLICATION_IN_PROGRESS`. |
| `activityStatus` | `string` | `ACTIVE`, `NOT_ACTIVE`. |
| `general` | `object` | Legal entity name, jurisdiction, date/country of incorporation. |
| `address` | `object` | Registration address, business address. |
| `application` | `object` | Submitted at, onboarded at, next periodic review. |
| `business` | `object` | Industry, description, business type/sub-type, ownership type/complexity, incorporation type. |
| `sourceOfFundsInfo` | `object?` | Source, details, jurisdictions, monthly/annual volumes. |
| `adverseMedia` | `object?` | Risk level (`NONE`, `LOW`, `MEDIUM`, `HIGH`), score, date, details, fines. |
| `politicalExposure` | `object?` | PEP tier (`NO_PEP`, `TIER_1`–`TIER_4`), score, details, jurisdictions. |
| `screening` | `object?` | Subpoena, SAR flags. |
| `currentRisk` | `object?` | Risk assessment (`score`, `level`, `reason`, `calculatedAt`). |
| `onboardingRisk` | `object?` | Onboarding risk assessment. |
| `riskHistory` | `array` | Historical risk assessments. |
| `members` | `object?` | Individual and corporate members. |
| `tags` | `string[]` | Tags. |
| `customFields` | `object?` | Custom fields. |
| `declaredAssets` | `string[]?` | Declared asset symbols. |
| `alerts` | `string[]?` | Associated alert IDs. |
| `financialOperations` | `string[]?` | Associated financial operation IDs. |
| `integrations` | `object?` | Third-party integration IDs (Chainalysis, SumSub, Plain). |
| `partnerClientId` | `string?` | Partner corporate client ID. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Alert
**Events:** `alert.created`, `alert.updated`
```json theme={null}
{
"type": "alert.created",
"timestamp": "2024-01-20T11:00:00.000Z",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"referenceId": "ALT-2024-001",
"entity": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"referenceId": "ALT-2024-001",
"category": "SCREENING_SANCTIONS",
"priority": "HIGH",
"status": "NEW",
"description": "Sanctions screening match detected for client",
"raisedAt": "2024-01-20T11:00:00.000Z",
"source": {
"vendor": "CHAINALYSIS",
"vendorAlertId": "CHAIN-456",
"vendorData": {
"riskScore": 85,
"category": "sanctions_match"
},
"link": "https://vendor.com/alerts/CHAIN-456",
"alertSource": "CHAINALYSIS"
},
"statusHistory": [
{
"status": "NEW",
"evaluatedAt": "2024-01-20T11:00:00.000Z",
"evaluatedBy": "system"
}
],
"associatedTransactions": [
{
"id": "tx-98765432-abcd-efgh-ijkl-mnopqrstuvwx",
"referenceId": "TX-2024-100"
}
],
"associatedClients": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123"
}
],
"associatedCases": [],
"customFields": {},
"attachmentIds": [],
"createdAt": "2024-01-20T11:00:00.000Z",
"updatedAt": "2024-01-20T11:00:00.000Z"
}
}
}
```
```json theme={null}
{
"type": "alert.updated",
"timestamp": "2024-01-22T09:30:00.000Z",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"referenceId": "ALT-2024-001",
"updated": {
"status": "RESOLVED",
"assigneeId": "analyst-001",
"statusHistory": [
{
"status": "NEW",
"evaluatedAt": "2024-01-20T11:00:00.000Z",
"evaluatedBy": "system"
},
{
"status": "IN_REVIEW",
"evaluatedAt": "2024-01-21T08:00:00.000Z",
"evaluatedBy": "analyst-001"
},
{
"status": "RESOLVED",
"evaluatedAt": "2024-01-22T09:30:00.000Z",
"evaluatedBy": "analyst-001"
}
]
},
"previousValues": {
"status": "IN_REVIEW",
"assigneeId": null,
"statusHistory": [
{
"status": "NEW",
"evaluatedAt": "2024-01-20T11:00:00.000Z",
"evaluatedBy": "system"
},
{
"status": "IN_REVIEW",
"evaluatedAt": "2024-01-21T08:00:00.000Z",
"evaluatedBy": "analyst-001"
}
]
}
}
}
```
| Field | Type | Description |
| ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `category` | `string` | `KYC`, `KYB`, `TRANSACTION_MONITORING`, `ONCHAIN_TRANSACTION_MONITORING`, `SCREENING_SANCTIONS`, `SCREENING_PEP`, `SCREENING_ADVERSE_MEDIA`, `SCREENING_REGULATORY`, `SCREENING_OTHER`, `FRAUD`, `PERIODIC_REVIEW`, `EDD`, `OTHER`. |
| `subCategory` | `string?` | Subcategory for granular classification. |
| `priority` | `string` | `LOW`, `MEDIUM`, `HIGH`. |
| `status` | `string` | `NEW`, `IN_REVIEW`, `ESCALATED`, `RESOLVED`. |
| `description` | `string` | Description of the alert. |
| `assigneeId` | `string?` | Assigned analyst ID. |
| `raisedAt` | `string` | ISO timestamp when the alert was raised. |
| `dueDate` | `string?` | ISO timestamp when the alert is due. |
| `source` | `object` | `vendor`, `vendorAlertId`, `vendorData`, `link`, `alertSource` (`CHAINALYSIS`, `SARDINE`, `MANUAL`, `API`, `TRM_LABS`, `SUMSUB`, `TRANSACTION_MONITORING`). |
| `statusHistory` | `array` | Status changes (status, evaluated at, evaluated by). |
| `associatedTransactions` | `array` | Linked transactions. |
| `associatedClients` | `array` | Linked clients. |
| `associatedCases` | `array` | Linked cases. |
| `customFields` | `object?` | Custom fields. |
| `attachmentIds` | `string[]?` | Attachment IDs. |
| `researchRiskLevel` | `string?` | Deep research screening risk level (`NONE`, `LOW`, `MEDIUM`, `HIGH`). |
| `researchRiskExplanation` | `string?` | Research risk explanation. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Case
**Events:** `case.created`, `case.updated`
```json theme={null}
{
"type": "case.created",
"timestamp": "2024-01-25T13:00:00.000Z",
"data": {
"id": "case-abc123def456",
"referenceId": "REF-2024-001234",
"entity": {
"id": "case-abc123def456",
"referenceId": "REF-2024-001234",
"priority": "HIGH",
"category": "TRANSACTION_MONITORING",
"status": "NEW",
"description": "Suspicious pattern of high-value transactions detected across multiple accounts",
"assigneeId": "analyst-001",
"reviewersIds": ["supervisor-001"],
"statusHistory": [
{
"status": "NEW",
"reason": "Case created from alert escalation",
"evaluatedAt": "2024-01-25T13:00:00.000Z",
"evaluatedBy": "system"
}
],
"alerts": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"referenceId": "ALT-2024-001"
}
],
"transactions": [
{
"id": "tx-98765432-abcd-efgh-ijkl-mnopqrstuvwx",
"referenceId": "TX-2024-100"
}
],
"clients": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123"
}
],
"attachmentIds": [],
"createdAt": "2024-01-25T13:00:00.000Z",
"updatedAt": "2024-01-25T13:00:00.000Z"
}
}
}
```
```json theme={null}
{
"type": "case.updated",
"timestamp": "2024-02-01T16:45:00.000Z",
"data": {
"id": "case-abc123def456",
"referenceId": "REF-2024-001234",
"updated": {
"status": "UNDER_INVESTIGATION",
"investigation": {
"content": "Reviewed client documentation and conducted enhanced due diligence procedures.",
"nickname": "High-Value TM Review",
"lastEditedAt": "2024-02-01T16:45:00.000Z",
"lastEditorId": "analyst-001"
}
},
"previousValues": {
"status": "NEW",
"investigation": null
}
}
}
```
| Field | Type | Description |
| --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `category` | `string` | `KYC`, `KYB`, `TRANSACTION_MONITORING`, `ONCHAIN_TRANSACTION_MONITORING`, `SCREENING_SANCTIONS`, `SCREENING_PEP`, `SCREENING_ADVERSE_MEDIA`, `SCREENING_REGULATORY`, `SCREENING_OTHER`, `FRAUD`, `PERIODIC_REVIEW`, `EDD`, `OTHER`. |
| `subCategory` | `string?` | Subcategory for granular classification. |
| `priority` | `string` | `LOW`, `MEDIUM`, `HIGH`. |
| `status` | `string` | `NEW`, `UNDER_INVESTIGATION`, `PENDING_EDD`, `PENDING_RFI`, `PENDING_REVIEW`, `CLOSED_DISMISSED`, `CLOSED_ESCALATION_TO_SAR`. |
| `description` | `string?` | Description. |
| `assigneeId` | `string?` | Assigned analyst ID. |
| `reviewersIds` | `string[]` | Reviewer IDs. |
| `dueDate` | `string?` | ISO timestamp when the case is due. |
| `statusHistory` | `array` | Status changes (status, reason, sub-status, evaluated at, evaluated by). |
| `investigation` | `object?` | Investigation notes (content, nickname, last edited at, last editor ID). |
| `alerts` | `array` | Associated alerts. |
| `transactions` | `array` | Associated transactions. |
| `clients` | `array` | Associated clients. |
| `attachmentIds` | `string[]?` | Attachment IDs. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Transaction
**Events:** `transaction.created`, `transaction.updated`
```json theme={null}
{
"type": "transaction.created",
"timestamp": "2024-01-18T10:30:00.000Z",
"data": {
"id": "tx-98765432-abcd-efgh-ijkl-mnopqrstuvwx",
"referenceId": "TX-2024-100",
"entity": {
"id": "tx-98765432-abcd-efgh-ijkl-mnopqrstuvwx",
"referenceId": "TX-2024-100",
"type": "DEPOSIT",
"currentStatus": {
"type": "PENDING",
"timestamp": "2024-01-18T10:30:00Z",
"reason": "Awaiting blockchain confirmation"
},
"statusHistory": [
{
"type": "PENDING",
"timestamp": "2024-01-18T10:30:00Z"
}
],
"amount": {
"amount": 1.5,
"currency": "BTC",
"netAmount": 1.485
},
"convertedAmount": {
"amount": 140439.61,
"currency": "USD"
},
"from": {
"client": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123"
},
"walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
},
"to": {
"walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
},
"paymentMethod": "CRYPTO_TRANSFER",
"transferType": "INTERNATIONAL",
"txHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
"initiatedAt": "2024-01-18T10:30:00Z",
"integrations": {
"chainalysisTransactionId": "chainalysis-tx-001"
},
"createdAt": "2024-01-18T10:30:00Z",
"updatedAt": "2024-01-18T10:30:00Z"
}
}
}
```
```json theme={null}
{
"type": "transaction.updated",
"timestamp": "2024-01-18T10:45:00.000Z",
"data": {
"id": "tx-98765432-abcd-efgh-ijkl-mnopqrstuvwx",
"referenceId": "TX-2024-100",
"updated": {
"currentStatus": {
"type": "SUCCESS",
"timestamp": "2024-01-18T10:45:00Z"
}
},
"previousValues": {
"currentStatus": {
"type": "PENDING",
"timestamp": "2024-01-18T10:30:00Z",
"reason": "Awaiting blockchain confirmation"
}
}
}
}
```
| Field | Type | Description |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `type` | `string` | `DEPOSIT`, `WITHDRAW`, `TRADE`, `TRANSFER`. |
| `currentStatus` | `object` | Current status. `type`: `SUCCESS`, `PENDING`, `CANCELLED`, `FAILED`, `FROZEN`. Also `timestamp`, `reason`, `subStatus`. |
| `statusHistory` | `array?` | History of status changes. |
| `amount` | `object` | Transaction amount (`amount`, `currency`, `netAmount`). |
| `convertedAmount` | `object?` | Converted amount in platform's preferred currency. |
| `from` | `object` | Source (`client`, `bankAccountNumber`, `walletAddress`, `wallet`). |
| `to` | `object?` | Destination (`client`, `bankAccountNumber`, `walletAddress`, `wallet`). |
| `sideInTrade` | `string?` | `BUY` or `SELL`. |
| `paymentMethod` | `string?` | Payment method (e.g., `CRYPTO_TRANSFER`). |
| `paymentRail` | `string?` | Payment rail (e.g., `SWIFT`, `SEPA`, `ACH`, `Fedwire`, `NIP`, `PIX`, `MobileMoney`, `SPEI`). |
| `transferType` | `string?` | `INTERNATIONAL`, `DOMESTIC`, `INTERNAL`. |
| `txHash` | `string?` | Blockchain transaction hash. |
| `initiatedAt` | `string` | ISO timestamp of initiation. |
| `customFields` | `object?` | Custom fields. |
| `integrations` | `object?` | Third-party IDs (`sardineTransactionId`, `chainalysisTransactionId`, `trmTransactionId`, `utilaTransactionId`). |
| `session` | `object?` | Session data (IP, device, geo-location). |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Deposit
**Events:** `deposit.created`, `deposit.updated`
```json theme={null}
{
"type": "deposit.created",
"timestamp": "2024-01-18T10:30:00.000Z",
"data": {
"id": "dep-11223344-5566-7788-99aa-bbccddeeff00",
"referenceId": "DEP-2024-001",
"entity": {
"id": "dep-11223344-5566-7788-99aa-bbccddeeff00",
"referenceId": "DEP-2024-001",
"initiatedBy": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123"
},
"initiatedAt": "2024-01-18T10:30:00Z",
"depositTransaction": {
"id": "tx-98765432-abcd-efgh-ijkl-mnopqrstuvwx",
"referenceId": "TX-2024-100",
"type": "DEPOSIT",
"currentStatus": {
"type": "PENDING",
"timestamp": "2024-01-18T10:30:00Z"
},
"amount": {
"amount": 50000,
"currency": "USD"
},
"from": {
"bankAccountNumber": "1234567890"
},
"to": {
"client": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123"
}
},
"paymentRail": "ACH",
"initiatedAt": "2024-01-18T10:30:00Z",
"createdAt": "2024-01-18T10:30:00Z",
"updatedAt": "2024-01-18T10:30:00Z"
},
"createdAt": "2024-01-18T10:30:00Z",
"updatedAt": "2024-01-18T10:30:00Z"
}
}
}
```
```json theme={null}
{
"type": "deposit.updated",
"timestamp": "2024-01-18T11:00:00.000Z",
"data": {
"id": "dep-11223344-5566-7788-99aa-bbccddeeff00",
"referenceId": "DEP-2024-001",
"updated": {
"depositTransaction": {
"currentStatus": {
"type": "SUCCESS",
"timestamp": "2024-01-18T11:00:00Z"
}
}
},
"previousValues": {
"depositTransaction": {
"currentStatus": {
"type": "PENDING",
"timestamp": "2024-01-18T10:30:00Z"
}
}
}
}
}
```
| Field | Type | Description |
| -------------------- | --------- | ------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `depositTransaction` | `object` | Underlying transaction (see Transaction payload). |
| `initiatedBy` | `object?` | Initiator (`id`, `referenceId`). |
| `initiatedAt` | `string` | ISO timestamp of initiation. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Withdrawal
**Events:** `withdrawal.created`, `withdrawal.updated`
```json theme={null}
{
"type": "withdrawal.created",
"timestamp": "2024-02-05T14:00:00.000Z",
"data": {
"id": "wdr-aabbccdd-1122-3344-5566-778899001122",
"referenceId": "WDR-2024-001",
"entity": {
"id": "wdr-aabbccdd-1122-3344-5566-778899001122",
"referenceId": "WDR-2024-001",
"initiatedBy": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123"
},
"initiatedAt": "2024-02-05T14:00:00Z",
"withdrawTransaction": {
"id": "tx-ffffffff-aaaa-bbbb-cccc-ddddeeee0001",
"referenceId": "TX-2024-200",
"type": "WITHDRAW",
"currentStatus": {
"type": "PENDING",
"timestamp": "2024-02-05T14:00:00Z"
},
"amount": {
"amount": 2.0,
"currency": "ETH",
"netAmount": 1.995
},
"convertedAmount": {
"amount": 4800.0,
"currency": "USD"
},
"from": {
"client": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123"
}
},
"to": {
"walletAddress": "0xabcdef1234567890abcdef1234567890abcdef12"
},
"paymentMethod": "CRYPTO_TRANSFER",
"initiatedAt": "2024-02-05T14:00:00Z",
"createdAt": "2024-02-05T14:00:00Z",
"updatedAt": "2024-02-05T14:00:00Z"
},
"createdAt": "2024-02-05T14:00:00Z",
"updatedAt": "2024-02-05T14:00:00Z"
}
}
}
```
```json theme={null}
{
"type": "withdrawal.updated",
"timestamp": "2024-02-05T14:30:00.000Z",
"data": {
"id": "wdr-aabbccdd-1122-3344-5566-778899001122",
"referenceId": "WDR-2024-001",
"updated": {
"withdrawTransaction": {
"currentStatus": {
"type": "SUCCESS",
"timestamp": "2024-02-05T14:30:00Z"
},
"txHash": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba"
}
},
"previousValues": {
"withdrawTransaction": {
"currentStatus": {
"type": "PENDING",
"timestamp": "2024-02-05T14:00:00Z"
},
"txHash": null
}
}
}
}
```
| Field | Type | Description |
| --------------------- | --------- | ------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `withdrawTransaction` | `object` | Underlying transaction (see Transaction payload). |
| `initiatedBy` | `object?` | Initiator (`id`, `referenceId`). |
| `initiatedAt` | `string` | ISO timestamp of initiation. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Trade
**Events:** `trade.created`, `trade.updated`
```json theme={null}
{
"type": "trade.created",
"timestamp": "2024-02-10T09:15:00.000Z",
"data": {
"id": "trd-00112233-4455-6677-8899-aabbccddeeff",
"referenceId": "TRD-2024-001",
"entity": {
"id": "trd-00112233-4455-6677-8899-aabbccddeeff",
"referenceId": "TRD-2024-001",
"tradeType": "BUY",
"price": 42500.00,
"quantity": 0.5,
"instrumentBaseAsset": "BTC",
"instrumentQuoteAsset": "USD",
"initiatedBy": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123"
},
"initiatedAt": "2024-02-10T09:15:00Z",
"transactions": [
{
"id": "tx-trade-buy-001",
"type": "TRADE",
"currentStatus": {
"type": "SUCCESS",
"timestamp": "2024-02-10T09:15:30Z"
},
"amount": {
"amount": 0.5,
"currency": "BTC"
},
"convertedAmount": {
"amount": 21250.00,
"currency": "USD"
},
"from": {
"client": {
"id": "123e4567-e89b-12d3-a456-426614174000"
}
},
"sideInTrade": "BUY",
"initiatedAt": "2024-02-10T09:15:00Z",
"createdAt": "2024-02-10T09:15:00Z",
"updatedAt": "2024-02-10T09:15:30Z"
}
],
"statusHistory": [
{
"status": "SUCCESS",
"timestamp": "2024-02-10T09:15:30Z"
}
],
"createdAt": "2024-02-10T09:15:00Z",
"updatedAt": "2024-02-10T09:15:30Z"
}
}
}
```
```json theme={null}
{
"type": "trade.updated",
"timestamp": "2024-02-10T09:20:00.000Z",
"data": {
"id": "trd-00112233-4455-6677-8899-aabbccddeeff",
"referenceId": "TRD-2024-001",
"updated": {
"statusHistory": [
{
"status": "PENDING",
"timestamp": "2024-02-10T09:15:00Z"
},
{
"status": "SUCCESS",
"timestamp": "2024-02-10T09:20:00Z"
}
]
},
"previousValues": {
"statusHistory": [
{
"status": "PENDING",
"timestamp": "2024-02-10T09:15:00Z"
}
]
}
}
}
```
| Field | Type | Description |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `tradeType` | `string` | `BUY`, `SELL`. |
| `price` | `number` | Price of the trade. |
| `quantity` | `number` | Quantity traded. |
| `instrumentBaseAsset` | `string` | Base asset (e.g., `BTC`). |
| `instrumentQuoteAsset` | `string` | Quote asset (e.g., `USD`). |
| `transactions` | `array` | Underlying transactions (see Transaction payload). |
| `statusHistory` | `array?` | Status changes. `status`: `PENDING`, `SUCCESS`, `FAILED`, `EXPIRED`, `REJECTED`. Also `reason`, `subStatus`, `timestamp`. |
| `initiatedBy` | `object?` | Initiator (`id`, `referenceId`). |
| `initiatedAt` | `string` | ISO timestamp of initiation. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Individual Member
**Events:** `individual_member.created`, `individual_member.updated`
```json theme={null}
{
"type": "individual_member.created",
"timestamp": "2024-01-12T08:00:00.000Z",
"data": {
"id": "mem-11111111-2222-3333-4444-555566667777",
"referenceId": "MEM-IND-001",
"entity": {
"id": "mem-11111111-2222-3333-4444-555566667777",
"referenceId": "MEM-IND-001",
"memberType": "INDIVIDUAL",
"firstName": "Jane",
"lastName": "Smith",
"middleName": "Marie",
"email": "jane.smith@acme.com",
"phoneNumber": "+1-555-987-6543",
"dateOfBirth": "1985-03-20T00:00:00Z",
"citizenship": "USA",
"personalIdNumber": "987-65-4321",
"residentialAddressLine1": "456 Oak Avenue",
"residentialAddressCity": "Chicago",
"residentialAddressPostalCode": "60601",
"residentialAddressCountry": "USA",
"title": "Chief Financial Officer",
"roleType": "OFFICER",
"ownershipPercentage": 25.5,
"status": "APPROVED",
"statusDate": "2024-01-12T08:00:00Z",
"sanctionsStatus": "CLEAR",
"sanctionsStatusDate": "2024-01-11T10:00:00Z",
"pepStatus": "CLEAR",
"pepStatusDate": "2024-01-11T10:00:00Z",
"adverseMediaStatus": "CLEAR",
"adverseMediaStatusDate": "2024-01-11T10:00:00Z",
"identityDocuments": [
{
"id": "doc-a1b2c3d4",
"documentType": "PASSPORT",
"documentNumber": "X12345678",
"documentIssuingCountry": "USA",
"documentExpirationDate": "2029-03-20T00:00:00Z"
}
],
"corporates": ["c8f2e3a1-b5d4-4e6f-9a1b-2c3d4e5f6a7b"],
"platformId": "platform-123",
"createdAt": "2024-01-12T08:00:00Z",
"updatedAt": "2024-01-12T08:00:00Z"
}
}
}
```
```json theme={null}
{
"type": "individual_member.updated",
"timestamp": "2024-03-15T11:30:00.000Z",
"data": {
"id": "mem-11111111-2222-3333-4444-555566667777",
"referenceId": "MEM-IND-001",
"updated": {
"sanctionsStatus": "FLAGGED",
"sanctionsStatusDate": "2024-03-15T11:30:00Z",
"status": "UNDER_REVIEW",
"statusDate": "2024-03-15T11:30:00Z"
},
"previousValues": {
"sanctionsStatus": "CLEAR",
"sanctionsStatusDate": "2024-01-11T10:00:00Z",
"status": "APPROVED",
"statusDate": "2024-01-12T08:00:00Z"
}
}
}
```
| Field | Type | Description |
| ------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `memberType` | `string` | Always `INDIVIDUAL`. |
| `firstName` | `string` | First name. |
| `lastName` | `string` | Last name. |
| `middleName` | `string?` | Middle name. |
| `email` | `string?` | Email address. |
| `phoneNumber` | `string?` | Phone number. |
| `dateOfBirth` | `string?` | Date of birth (ISO format). |
| `citizenship` | `string?` | Citizenship country code. |
| `personalIdNumber` | `string?` | Personal identification number. |
| `residentialAddressLine1` | `string?` | First line of residential address. |
| `residentialAddressLine2` | `string?` | Second line of residential address. |
| `residentialAddressCity` | `string?` | Residential address city. |
| `residentialAddressPostalCode` | `string?` | Residential address postal code. |
| `residentialAddressCountry` | `string?` | Residential address country code. |
| `title` | `string` | Title or position. |
| `roleType` | `string` | `OWNER`, `DIRECTOR`, `OFFICER`, `AUTHORIZED_REPRESENTATIVE`, `BENEFICIAL_OWNER`, `SHAREHOLDER`, `SIGNATORY`, `TRUSTEE`, `PROTECTOR`, `SETTLOR`, `OTHER`. |
| `ownershipPercentage` | `number?` | Ownership percentage (0–100). |
| `status` | `string` | `APPROVED`, `REJECTED`, `UNDER_REVIEW`. |
| `statusDate` | `string` | Date of status determination. |
| `sanctionsStatus` | `string` | `CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`. |
| `sanctionsStatusDate` | `string?` | Date of sanctions status determination. |
| `pepStatus` | `string` | `CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`. |
| `pepStatusDate` | `string?` | Date of PEP status determination. |
| `adverseMediaStatus` | `string` | `CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`. |
| `adverseMediaStatusDate` | `string?` | Date of adverse media status determination. |
| `identityDocuments` | `array?` | Identity documents (`id`, `documentType`, `documentNumber`, `documentIssuingCountry`, `documentExpirationDate`). Document types: `PASSPORT`, `DRIVERS_LICENSE`, `NATIONAL_ID`, `RESIDENCE_PERMIT`, `BIRTH_CERTIFICATE`, `OTHER`. |
| `corporates` | `string[]?` | Associated corporate client IDs. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Corporate Member
**Events:** `corporate_member.created`, `corporate_member.updated`
```json theme={null}
{
"type": "corporate_member.created",
"timestamp": "2024-01-12T09:00:00.000Z",
"data": {
"id": "mem-aaaabbbb-cccc-dddd-eeee-ffff00001111",
"referenceId": "MEM-CORP-001",
"entity": {
"id": "mem-aaaabbbb-cccc-dddd-eeee-ffff00001111",
"referenceId": "MEM-CORP-001",
"memberType": "CORPORATE",
"legalEntityName": "Acme Holdings Inc.",
"countryOfIncorporation": "USA",
"registrationNumber": "12345678",
"dateOfIncorporation": "2010-05-15T00:00:00Z",
"businessAddressLine1": "123 Business Street",
"businessAddressLine2": "Suite 400",
"businessAddressCity": "New York",
"businessAddressPostalCode": "10001",
"businessAddressCountry": "USA",
"email": "contact@acme-holdings.com",
"phoneNumber": "+1-555-100-2000",
"title": "Parent Company",
"roleType": "SHAREHOLDER",
"ownershipPercentage": 80.0,
"status": "APPROVED",
"statusDate": "2024-01-12T09:00:00Z",
"sanctionsStatus": "CLEAR",
"sanctionsStatusDate": "2024-01-11T14:00:00Z",
"pepStatus": "CLEAR",
"pepStatusDate": "2024-01-11T14:00:00Z",
"adverseMediaStatus": "CLEAR",
"adverseMediaStatusDate": "2024-01-11T14:00:00Z",
"corporates": ["c8f2e3a1-b5d4-4e6f-9a1b-2c3d4e5f6a7b"],
"platformId": "platform-123",
"createdAt": "2024-01-12T09:00:00Z",
"updatedAt": "2024-01-12T09:00:00Z"
}
}
}
```
```json theme={null}
{
"type": "corporate_member.updated",
"timestamp": "2024-04-01T10:00:00.000Z",
"data": {
"id": "mem-aaaabbbb-cccc-dddd-eeee-ffff00001111",
"referenceId": "MEM-CORP-001",
"updated": {
"ownershipPercentage": 65.0,
"legalEntityName": "Acme Holdings International Inc."
},
"previousValues": {
"ownershipPercentage": 80.0,
"legalEntityName": "Acme Holdings Inc."
}
}
}
```
| Field | Type | Description |
| --------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `memberType` | `string` | Always `CORPORATE`. |
| `legalEntityName` | `string` | Legal entity name. |
| `countryOfIncorporation` | `string?` | Country of incorporation. |
| `registrationNumber` | `string?` | Registration number. |
| `dateOfIncorporation` | `string?` | Date of incorporation (ISO format). |
| `title` | `string` | Role description. |
| `roleType` | `string` | `OWNER`, `DIRECTOR`, `OFFICER`, `AUTHORIZED_REPRESENTATIVE`, `BENEFICIAL_OWNER`, `SHAREHOLDER`, `SIGNATORY`, `TRUSTEE`, `PROTECTOR`, `SETTLOR`, `OTHER`. |
| `ownershipPercentage` | `number?` | Ownership percentage (0–100). |
| `status` | `string` | `APPROVED`, `REJECTED`, `UNDER_REVIEW`. |
| `statusDate` | `string` | Date of status determination. |
| `sanctionsStatus` | `string` | `CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`. |
| `sanctionsStatusDate` | `string?` | Date of sanctions status determination. |
| `pepStatus` | `string` | `CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`. |
| `pepStatusDate` | `string?` | Date of PEP status determination. |
| `adverseMediaStatus` | `string` | `CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`. |
| `adverseMediaStatusDate` | `string?` | Date of adverse media status determination. |
| `email` | `string?` | Contact email. |
| `phoneNumber` | `string?` | Contact phone number. |
| `businessAddressLine1` | `string?` | Business address line 1. |
| `businessAddressLine2` | `string?` | Business address line 2. |
| `businessAddressCity` | `string?` | City. |
| `businessAddressPostalCode` | `string?` | Postal code. |
| `businessAddressCountry` | `string?` | Country code. |
| `corporates` | `string[]?` | Associated corporate client IDs. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Blockchain Wallet
**Events:** `blockchain_wallet.created`, `blockchain_wallet.updated`
```json theme={null}
{
"type": "blockchain_wallet.created",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"id": "bw-12345678-abcd-efgh-ijkl-mnopqrst0001",
"referenceId": "REF-WALLET-001",
"entity": {
"id": "bw-12345678-abcd-efgh-ijkl-mnopqrst0001",
"referenceId": "REF-WALLET-001",
"address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
"chain": "ethereum",
"screeningDate": "2024-01-15T10:30:00.000Z",
"currentRisk": {
"score": 10,
"level": "LOW",
"calculatedAt": "2024-01-15T10:30:00.000Z"
},
"riskHistory": [],
"associatedClients": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123",
"name": "Primary Trading Wallet"
}
],
"integrations": {
"utilaWalletId": "utila-wallet-123"
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
}
}
```
```json theme={null}
{
"type": "blockchain_wallet.updated",
"timestamp": "2024-03-01T16:00:00.000Z",
"data": {
"id": "bw-12345678-abcd-efgh-ijkl-mnopqrst0001",
"referenceId": "REF-WALLET-001",
"updated": {
"currentRisk": {
"score": 90,
"level": "HIGH",
"reason": "Exposure to sanctioned entity detected",
"calculatedAt": "2024-03-01T16:00:00.000Z"
},
"screeningDate": "2024-03-01T16:00:00.000Z"
},
"previousValues": {
"currentRisk": {
"score": 10,
"level": "LOW",
"calculatedAt": "2024-01-15T10:30:00.000Z"
},
"screeningDate": "2024-01-15T10:30:00.000Z"
}
}
}
```
| Field | Type | Description |
| ------------------- | --------- | ------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `address` | `string` | Wallet address on the blockchain. |
| `chain` | `string?` | Blockchain network (e.g., `ethereum`, `bitcoin`). |
| `screeningDate` | `string?` | Date when the wallet was last screened. |
| `currentRisk` | `object?` | Risk assessment (`score`, `level`, `reason`, `calculatedAt`). |
| `riskHistory` | `array` | Historical risk assessments. |
| `associatedClients` | `array?` | Associated clients. |
| `customFields` | `object?` | Custom fields. |
| `integrations` | `object?` | Third-party integration IDs (`utilaWalletId`). |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Bank Account
**Events:** `bank_account.created`, `bank_account.updated`
```json theme={null}
{
"type": "bank_account.created",
"timestamp": "2024-01-16T12:00:00.000Z",
"data": {
"id": "ba-99887766-5544-3322-1100-aabbccddeeff",
"referenceId": "REF-BA-001",
"entity": {
"id": "ba-99887766-5544-3322-1100-aabbccddeeff",
"referenceId": "REF-BA-001",
"bankName": "Chase Bank",
"accountNumber": "1234567890",
"routingNumber": "021000021",
"accountHolderName": "John Doe",
"accountType": "checking",
"currency": "USD",
"balanceInCurrency": 150000.50,
"balanceInConvertedAmount": 150000.50,
"countries": ["USA"],
"currentRisk": {
"score": 5,
"level": "LOW",
"calculatedAt": "2024-01-16T12:00:00.000Z"
},
"riskHistory": [],
"associatedClients": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123",
"name": "Primary Business Account",
"status": "ACTIVE"
}
],
"createdAt": "2024-01-16T12:00:00.000Z",
"updatedAt": "2024-01-16T12:00:00.000Z"
}
}
}
```
```json theme={null}
{
"type": "bank_account.updated",
"timestamp": "2024-04-10T08:00:00.000Z",
"data": {
"id": "ba-99887766-5544-3322-1100-aabbccddeeff",
"referenceId": "REF-BA-001",
"updated": {
"balanceInCurrency": 275000.00,
"balanceInConvertedAmount": 275000.00
},
"previousValues": {
"balanceInCurrency": 150000.50,
"balanceInConvertedAmount": 150000.50
}
}
}
```
| Field | Type | Description |
| -------------------------- | ----------- | ----------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `bankName` | `string?` | Name of the bank. |
| `accountNumber` | `string` | Bank account number. |
| `routingNumber` | `string?` | Bank routing number. |
| `accountHolderName` | `string?` | Account holder name. |
| `accountType` | `string?` | Account type (e.g., `checking`, `savings`). |
| `currency` | `string?` | Account currency (ISO 4217). |
| `balanceInCurrency` | `number?` | Balance in the account currency. |
| `balanceInConvertedAmount` | `number?` | Balance in platform's preferred currency. |
| `countries` | `string[]?` | Associated country codes. |
| `currentRisk` | `object?` | Risk assessment (`score`, `level`, `reason`, `calculatedAt`). |
| `riskHistory` | `array` | Historical risk assessments. |
| `associatedClients` | `array?` | Associated clients (id, referenceId, name, status: `ACTIVE`, `INACTIVE`, `CLOSED`). |
| `customFields` | `object?` | Custom fields. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Payment Account
**Events:** `payment_account.created`, `payment_account.updated`
```json theme={null}
{
"type": "payment_account.created",
"timestamp": "2024-03-10T09:00:00.000Z",
"data": {
"id": "pa-11223344-5566-7788-99aa-bbccddeeff00",
"referenceId": "REF-PA-001",
"entity": {
"id": "pa-11223344-5566-7788-99aa-bbccddeeff00",
"referenceId": "REF-PA-001",
"identifier": "+55 11 91234-5678",
"identifierType": "MOBILE_MONEY",
"accountHolderName": "Maria Silva",
"currency": "BRL",
"countries": ["BRA"],
"currentRisk": {
"score": 10,
"level": "LOW",
"calculatedAt": "2024-03-10T09:00:00.000Z"
},
"riskHistory": [],
"associatedClients": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "IND123",
"name": "Primary Payment Account"
}
],
"createdAt": "2024-03-10T09:00:00.000Z",
"updatedAt": "2024-03-10T09:00:00.000Z"
}
}
}
```
```json theme={null}
{
"type": "payment_account.updated",
"timestamp": "2024-04-01T14:00:00.000Z",
"data": {
"id": "pa-11223344-5566-7788-99aa-bbccddeeff00",
"referenceId": "REF-PA-001",
"updated": {
"currentRisk": {
"score": 75,
"level": "HIGH",
"reason": "Unusual transaction pattern detected",
"calculatedAt": "2024-04-01T14:00:00.000Z"
}
},
"previousValues": {
"currentRisk": {
"score": 10,
"level": "LOW",
"calculatedAt": "2024-03-10T09:00:00.000Z"
}
}
}
}
```
| Field | Type | Description |
| ------------------- | ----------- | -------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier. |
| `referenceId` | `string?` | External reference ID. |
| `identifier` | `string` | Primary identifier (e.g., PIX key, phone number, CLABE). |
| `identifierType` | `string?` | Type of identifier: `MOBILE_MONEY`, `PIX`, `CLABE`, `INTERNAL`, `CREDIT_CARD`, `DEBIT_CARD`. |
| `accountHolderName` | `string?` | Account holder name. |
| `currency` | `string?` | Account currency (ISO 4217). |
| `countries` | `string[]?` | Associated country codes (ISO 3166-1 alpha-3). |
| `currentRisk` | `object?` | Risk assessment (`score`, `level`, `reason`, `calculatedAt`). |
| `riskHistory` | `array` | Historical risk assessments. |
| `associatedClients` | `array?` | Associated clients. |
| `customFields` | `object?` | Custom fields. |
| `createdAt` | `string` | ISO timestamp of creation. |
***
## Checklist
**Events:** `checklist.created`, `checklist.updated`
```json theme={null}
{
"type": "checklist.created",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"id": "client-uuid-123",
"referenceId": "ext-12345",
"entity": {
"id": "checklist-uuid-456",
"entityId": "client-uuid-123",
"entityType": "INDIVIDUAL_CLIENT",
"referenceId": "ext-12345",
"name": "Client Onboarding Checklist",
"description": "Complete onboarding checklist for new individual client",
"status": "ACTIVE",
"items": [
{
"id": "item-uuid-001",
"name": "Passport Copy",
"note": "Please provide a clear copy of your passport",
"category": "PERSONAL_IDENTIFICATION",
"status": "PENDING"
}
],
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}
}
```
```json theme={null}
{
"type": "checklist.updated",
"timestamp": "2024-01-15T11:00:00.000Z",
"data": {
"id": "client-uuid-123",
"referenceId": "ext-12345",
"entity": {
"id": "checklist-uuid-456",
"entityId": "client-uuid-123",
"entityType": "INDIVIDUAL_CLIENT",
"referenceId": "ext-12345",
"name": "Client Onboarding Checklist",
"description": "Complete onboarding checklist for new individual client",
"status": "COMPLETED",
"items": [
{
"id": "item-uuid-001",
"name": "Passport Copy",
"category": "PERSONAL_IDENTIFICATION",
"status": "PENDING"
}
],
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T11:00:00Z"
},
"updated": {
"status": "COMPLETED"
},
"previousValues": {
"status": "ACTIVE"
}
}
}
```
The examples show commonly used entity fields. Checklist payloads can include additional template, item, and audit metadata.
| Field | Type | Description |
| ------------- | --------- | ------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier of the checklist. |
| `entityId` | `string` | ID of the entity (client, alert, or case) this checklist belongs to. |
| `entityType` | `string` | Entity type: `INDIVIDUAL_CLIENT`, `CORPORATE_CLIENT`, `ALERT`, or `CASE`. |
| `referenceId` | `string?` | External reference ID. |
| `name` | `string?` | Display name of the checklist. |
| `description` | `string?` | Description of the checklist. |
| `status` | `string` | Status: `ACTIVE`, `COMPLETED`, or `ARCHIVED`. |
| `items` | `array` | Checklist items. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
**Checklist item fields:**
| Field | Type | Description |
| ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier of the item. |
| `name` | `string?` | Display name of the item. |
| `note` | `string?` | Descriptive note for the item. |
| `category` | `string?` | Category: `PERSONAL_IDENTIFICATION`, `FINANCIAL_INFORMATION`, `CORPORATE_INFORMATION`, `DECLARATIONS_COMPLIANCE`, or `OTHER`. |
| `status` | `string` | Current status of the item (default or custom). |
| `attachmentId` | `string?` | ID of the linked attachment. |
| `documentMimeType` | `string?` | MIME type of the attached document. |
| `expirationDate` | `string?` | ISO timestamp of document expiration. |
***
## Attachment
**Events:** `attachment.created`, `attachment.updated`, `attachment.deleted`
Attachment events fire when files are uploaded, linked, updated, or removed. The `deleted` event uses the `created` envelope structure (containing the last known entity state).
```json theme={null}
{
"type": "attachment.created",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"id": "att_123e4567-e89b-12d3-a456-426614174000",
"entity": {
"id": "att_123e4567-e89b-12d3-a456-426614174000",
"attachmentId": "att_123e4567-e89b-12d3-a456-426614174000",
"uploadedBy": "user-uuid-789",
"fileName": "kyc-passport.pdf",
"fileType": "application/pdf",
"fileSizeInBytes": 245000,
"entityType": "client",
"entityId": "client-uuid-123",
"source": "DOCUMENT_REPOSITORY",
"metadata": "{\"category\": \"KYC\"}",
"reviewStatus": "NOT_REVIEWED",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}
}
```
```json theme={null}
{
"type": "attachment.updated",
"timestamp": "2024-01-15T11:00:00.000Z",
"data": {
"id": "att_123e4567-e89b-12d3-a456-426614174000",
"entity": {
"id": "att_123e4567-e89b-12d3-a456-426614174000",
"attachmentId": "att_123e4567-e89b-12d3-a456-426614174000",
"uploadedBy": "user-uuid-789",
"fileName": "kyc-passport.pdf",
"fileType": "application/pdf",
"fileSizeInBytes": 245000,
"entityType": "case",
"entityId": "case-uuid-456",
"source": "DOCUMENT_REPOSITORY",
"metadata": "{\"category\": \"KYC\"}",
"reviewStatus": "NOT_REVIEWED",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T11:00:00Z"
},
"updated": {
"entityType": "case",
"entityId": "case-uuid-456"
},
"previousValues": {
"entityType": "client",
"entityId": "client-uuid-123"
}
}
}
```
```json theme={null}
{
"type": "attachment.deleted",
"timestamp": "2024-01-15T12:00:00.000Z",
"data": {
"id": "att_123e4567-e89b-12d3-a456-426614174000",
"entity": {
"id": "att_123e4567-e89b-12d3-a456-426614174000",
"attachmentId": "att_123e4567-e89b-12d3-a456-426614174000",
"uploadedBy": "user-uuid-789",
"fileName": "kyc-passport.pdf",
"fileType": "application/pdf",
"entityType": "client",
"entityId": "client-uuid-123",
"reviewStatus": "NOT_REVIEWED"
}
}
}
```
The examples show commonly used entity fields. Attachment payloads can include additional storage and metadata fields.
| Field | Type | Description |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier of the attachment. |
| `attachmentId` | `string` | Attachment identifier repeated for compatibility with attachment consumers. |
| `uploadedBy` | `string` | ID of the user or service that uploaded the attachment. |
| `fileName` | `string` | Original file name. |
| `fileType` | `string` | MIME type of the file. |
| `fileSizeInBytes` | `number?` | File size in bytes. |
| `entityType` | `string` | Entity the attachment is linked to: `client`, `transaction`, `case`, `alert`, `report`, `comment`, `checklist_item`, `message`, `signature`, `platform_logo`, or `user_avatar`. |
| `entityId` | `string` | ID of the linked entity. |
| `source` | `string?` | Source of the attachment (e.g., `DOCUMENT_REPOSITORY`). |
| `metadata` | `string?` | JSON-encoded custom metadata string. |
| `reviewStatus` | `string` | Review state: `NOT_REVIEWED`, `IN_REVIEW`, `ACCEPTED`, or `REJECTED`. |
| `createdAt` | `string` | ISO timestamp of creation. |
| `updatedAt` | `string` | ISO timestamp of last update. |
***
## Form Template
**Events:** `form_template.public_form_submitted`
This event fires when a client submits a form. Unlike other events, this is not a `created`/`updated` pair — it is a single action event. The payload uses the `created` envelope structure with a `data.entity` containing the submission details.
```json theme={null}
{
"type": "form_template.public_form_submitted",
"timestamp": "2024-05-20T11:45:00.000Z",
"data": {
"id": "sub-aabbccdd-1122-3344-5566-778899aabbcc",
"entity": {
"submissionId": "sub-aabbccdd-1122-3344-5566-778899aabbcc",
"formTemplateId": "tmpl-11223344-5566-7788-99aa-bbccddeeff00",
"formName": "KYC Form",
"formType": "KYC",
"clientId": "123e4567-e89b-12d3-a456-426614174000",
"clientName": "John Doe",
"sentBy": "user-99887766-5544-3322-1100-ffeeddccbbaa",
"clientEntityUpdated": true
}
}
}
```
| Field | Type | Description |
| --------------------- | ---------- | --------------------------------------------------------------------- |
| `submissionId` | `string` | Unique identifier of the form submission. |
| `formTemplateId` | `string` | ID of the form template that was submitted. |
| `formName` | `string` | Display name of the form. |
| `formType` | `string?` | Type of form (e.g., `KYC`, `KYB`). |
| `clientId` | `string` | ID of the client who submitted the form. |
| `clientName` | `string?` | Display name of the client. |
| `sentBy` | `string` | ID of the platform user who sent the form link to the client. |
| `clientEntityUpdated` | `boolean?` | Whether the client entity was updated as a result of this submission. |
| `updatedAt` | `string` | ISO timestamp of last update. |