Identity Event

Webhook triggered for identity verification (KYC) events

Overview

The identity event is triggered when an identity verification (KYC) process is completed or rejected. This event includes verified identity information extracted from identity documents.

Example Payload

{
  "eventType": "identity",
  "issuerId": "680a65a4da4a16c0ea64face",
  "requestId": "68c5a1b2c3d4e5f678901234",
  "subjectId": "68c5a1b2c3d4e5f678901235",
  "subjectInternalId": "user_kyc_001",
  "rejected": false,
  "decisionDate": "2024-01-15T20:15:00.000Z",
  "convergedIntoSubjectId": null,
  "metadata": {
    "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",
    "veriffId": "veriff_abc123",
    "veriffRiskScore": 0.05,
    "countryAlpha3": "USA"
  }
}

Base Fields

All identity events include these common fields:

Field	Type	Required	Description
eventType	string	Yes	Always "identity"
issuerId	string	Yes	Organization/issuer identifier
requestId	string	Yes	Request identifier
subjectId	string	Yes	Subject (user) identifier
subjectInternalId	string	No	Internal subject identifier
rejected	boolean	Yes	Whether the identity verification was rejected
decisionDate	Date	Yes	Timestamp when the identity decision was made

Identity-Specific Fields

Field	Type	Required	Description
convergedIntoSubjectId	string	No	Subject ID if identities were merged (see Identity Merging)
metadata	object	No	Verified identity information (IdentityMetadata)

Identity Metadata

When metadata is present, it 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.)
veriffId	string	Yes	Veriff verification ID
veriffRiskScore	number	Yes	Veriff risk score (0-1, lower is better)
countryAlpha3	string	Yes	ISO 3166-1 alpha-3 country code

Identity Merging

When convergedIntoSubjectId is present, it indicates that this identity was merged with another existing identity. The identity data from this event has been consolidated into the subject identified by convergedIntoSubjectId.

Example:

{
  "eventType": "identity",
  "subjectId": "68c5a1b2c3d4e5f678901235",
  "convergedIntoSubjectId": "68c5a1b2c3d4e5f678901999"
  // ... other fields
}

In this case, the identity from subjectId was merged into the identity with convergedIntoSubjectId.