Verification API

After a user completes KYC, you receive verification results via webhooks or by polling GET /v1/verifications/{sessionId} with your secret key — see Direct API → Getting the result.

Verification Object

typescript

{
  "id": "ver_xxxxxxxxxxxxxxxx",
  "sessionId": "ses_xxxxxxxxxxxxxxxx",
  "status": "approved",
  "confidence": 0.98,
  "documentType": "id_card",
  "extractedData": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-05-15",
    "documentNumber": "L01X00T47",
    "nationality": "DE",
    "sex": "M",
    "expiryDate": "2029-05-14"
  },
  "clientMetadata": {
    "email": "user@example.com",
    "userId": "user_123"
  },
  "aml": {
    "status": "clear",
    "provider": "dilisense",
    "checkedAt": "2026-10-05T12:04:30.000Z",
    "totalHits": 0,
    "matchedHits": 0,
    "clearedHits": 0,
    "confirmedHits": 0,
    "categories": []
  },
  "createdAt": "2024-01-15T12:05:00Z"
}

aml is always present: null when AML screening did not run for the verification, otherwise the summary. clearedHits and confirmedHits count the matches your reviewers decided on. Hit details are available only in the dashboard.

Verification Statuses

Status	Description
`approved`	Identity verified successfully
`rejected`	Verification failed

Extracted Data Fields

Field	Description
`fullName`	Complete name from document
`firstName`	First/given name
`lastName`	Last/family name
`dateOfBirth`	Date of birth (YYYY-MM-DD)
`documentNumber`	Document ID number
`nationality`	Nationality code (ISO 3166-1 alpha-2)
`sex`	Sex: `M`, `F`, or `X`
`expiryDate`	Document expiry date

Confidence Score

The confidence field (0.0 - 1.0) indicates verification reliability:

Score	Meaning
0.95 - 1.0	High confidence
0.80 - 0.94	Medium confidence
< 0.80	Low confidence

Webhook Events

`verification.completed`

When automated verification completes, you receive:

typescript

{
  "type": "verification.completed",
  "data": {
    "object": {
      "id": "ver_xxxxxxxxxxxxxxxx",
      "status": "completed",
      "confidence": 0.98,
      "extracted_data": { ... },
      "duplicate_verification": {
        "is_duplicate": true,
        "previous_verification_id": "cmohkbzfq000686fezoudgcuc",
        "previous_verified_at": "2026-04-27T19:01:03.000Z",
        "match_type": "document_number",
        "similarity_score": 1
      },
      "client_metadata": { ... }
    }
  }
}

duplicate_verification is optional. It is included only when Flonk detects that the same document or person was already successfully verified in the same project. The verification still completes normally; use this signal for your own fraud prevention, manual review, or account-linking logic. See Webhooks for field details.

`verification.status_changed`

When a verification is approved or rejected — by an admin from the dashboard, or when a manual review is rejected (a manual-review approval fires verification.completed instead). For a rejected manual-review session previous_status is manual_review:

typescript

{
  "type": "verification.status_changed",
  "data": {
    "object": {
      "id": "ver_xxxxxxxxxxxxxxxx",
      "status": "approved",       // or "rejected"
      "confidence": 0.98,
      "extracted_data": { ... },
      "previous_status": "completed",
      "rejection_reason": "...",  // only for rejected
      "reviewed_by": "admin@company.com"
    }
  }
}

`verification.updated`

When an admin manually edits verification data (document fields, file uploads):

typescript

{
  "type": "verification.updated",
  "data": {
    "object": {
      "id": "ver_xxxxxxxxxxxxxxxx",
      "status": "completed",
      "document_type": "passport",
      "extracted_data": {
        "full_name": "John Doe",
        "document_number": "AB1234567",
        "issue_date": "2020-01-01",
        "expiry_date": "2030-01-01"
      },
      "updated_at": "2026-03-31T12:00:00.000Z",
      "updated_by": "admin@company.com"
    }
  }
}

See Webhooks for full setup and handling guide.