Identity Event

Webhook triggered for identity verification (KYC) events

Overview

The identity event is triggered when an identity verification (KYC) process is completed. This event includes verified identity information extracted from government-issued identity documents, along with a fraud and risk decision.

Example Payload

{
  "eventType": "identity",
  "requestId": "68c5a1b2c3d4e5f678901234",
  "issuerDid": "did:via:org-abc123",
  "user": {
    "contact": "[phone]",
    "did": "did:via:user-xyz789",
    "internalId": "user_kyc_001"
  },
  "decisionDate": "2024-01-15T20:15:00.000Z",
  "identity": {
    "fullName": "John Michael Doe",
    "gender": "M",
    "birth": "1990-05-15T00:00:00.000Z",
    "docId": "A123456789",
    "fullDocId": "A12345678901234",
    "expiresAt": "2030-05-15T00:00:00.000Z",
    "issueDate": "2020-05-15T00:00:00.000Z",
    "placeOfBirth": "New York",
    "documentType": "PASSPORT",
    "countryAlpha3": "USA"
  },
  "decision": {
    "success": true,
    "isFraud": false,
    "riskScore": 0.05,
    "message": "Identity verified successfully"
  }
}

Base Fields

All identity events include these common fields:

Field	Type	Required	Description
eventType	string	Yes	Always "identity"
requestId	string	Yes	Request identifier
internalId	string	No	Your internal identifier for the request
issuerDid	string	Yes	DID of the organization/issuer
user	object	Yes	Object containing user identity fields
decisionDate	Date	Yes	Timestamp when the identity was verified

User Object

Field	Type	Required	Description
contact	string	Yes	User’s contact information (phone or email)
did	string	Yes	DID of the user/subject
internalId	string	No	Your internal identifier for the user

Identity Object

The identity field contains verified identity information:

Field	Type	Required	Description
fullName	string	Yes	Full name as it appears on the document
gender	string	Yes	Gender identifier (M/F/O)
birth	Date	Yes	Date of birth
docId	string	Yes	Document identification number
fullDocId	string	Yes	Full document ID (extended version)
expiresAt	Date	Yes	Document expiration date
issueDate	Date	Yes	Document issue date
placeOfBirth	string	Yes	Place of birth
documentType	string	Yes	Type of document (PASSPORT, DRIVER_LICENSE, etc.)
countryAlpha3	string	Yes	ISO 3166-1 alpha-3 country code

Decision Object

The decision field contains the outcome of the identity verification:

Field	Type	Required	Description
success	boolean	Yes	Whether the identity verification passed
isFraud	boolean	Yes	Whether the submission was flagged as fraudulent
riskScore	number	Yes	Risk score (0–1, lower is better)
message	string	No	Human-readable description of the decision

Document Types

Common values for documentType:

Value	Description
PASSPORT	National passport
DRIVER_LICENSE	Driver’s license
ID_CARD	National identity card
RESIDENCE_PERMIT	Residence permit

Risk Score

The decision.riskScore is a value between 0 and 1:

Range	Risk Level	Description
0.00 - 0.10	Very Low	High confidence in document and identity
0.10 - 0.30	Low	Minor concerns, generally acceptable
0.30 - 0.50	Medium	Some concerns, manual review recommended
0.50 - 0.70	High	Significant concerns, careful review needed
0.70 - 1.00	Very High	Major concerns, likely fraudulent