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

{
  "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"
  },
  "createdAt": "2024-01-15T12:05:00Z"
}

typescript

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:

{
  "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": { ... }
    }
  }
}

typescript

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:

{
  "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"
    }
  }
}

typescript

`verification.updated`

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

{
  "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"
    }
  }
}

typescript

See Webhooks for full setup and handling guide.

Verification

Verification API

Verification Object

Verification Statuses

Extracted Data Fields

Confidence Score

Webhook Events

`verification.completed`

`verification.status_changed`

`verification.updated`

On this page

Quick Links

Need Help?