Business Entities

Overview

This document explains the structure and relationships of key entities in the X-Faces system involved in user verification.

---

General Flow

A User undergoes one or more verification attempts (Challenges), each of which contains results of verification steps like face_verification and id_recognition. After successful verification, the user is marked as verified.

---

1. User - user data

User Data Structure

{
  "created_at": "timestamptz",
  "updated_at": "timestamptz",
  "u_uuid": "string uuid",
  "external_id": "string",
  "verified": true,
  "have_actual_document": "bool", // nullable
  "require_manual_check": "bool",
  "rejection_reasons": ["rejectionReason", ...],
  "verified_at": "timestamptz",
  "c_uuid": "string uuid"
}

• created_at: date and time of creation
• updated_at: date and time of the last update
• u_uuid: internal user ID in X-Faces
• external_id: your internal user ID
• verified: whether verification was completed
• have_actual_document: whether the document is expired or not
• require_manual_check: whether the user needs to be checked manually by the operator
• rejection_reasons: array of reasons by which the user has not passed the verification
• c_uuid: the last challenge that this user was seen in

---

2. Challenge - data on the user’s verification process

Challenge Data Structure

{
  "created_at": "timestamptz",
  "completed_at": "timestamptz",
  "c_uuid": "string uuid",
  "user_id": "string uuid",
  "confidence": 0.95,
  "face_verification": {
    "verified": true,
    "verified_confidence": 0.98,
    "liveness": true,
    "liveness_confidence": 0.96
  },
  "id_recognition": {
    "recognized": true,
    "confidence": 0.93,
    "cnp": "1234567890123",
    "id_seria": "AB",
    "id_number": "123456",
    "lastname": "Doe",
    "firstname": "John",
    "valid_until": "2028-12-31"
  },
  "images": {
    "face": ["uuid1", "uuid2"],
    "id_card": ["uuid3"]
  }
}

---

3. Challenge Step

Verification steps in the response can be of two types:

• face_verification
• id_recognition

face_verification

{
  "verified": true,
  "verified_confidence": 0.97,
  "liveness": true,
  "liveness_confidence": 0.94
}

• verified: whether the service considers the face on the ID card and selfie identical
• verified_confidence: service confidence (from 0 to 1, where 0 is absolutely no, 1 is absolutely yes)
• liveness: whether the service considers the selfie real
• liveness_confidence: service confidence (from 0 to 1, where 0 is absolutely no, 1 is absolutely yes)

id_recognition

{
  "type": 2,
  "cnp": "1234567890123",
  "last_name": "Doe",
  "first_name": "John",
  "seria": "AB",
  "NR": "123456",
  "expire_date": "2028-12-31",
  "sex": "M",
  "birth_date": "1990-01-01"
}

• type: document type code (2 - id card, 3 - passport, 6 - driving license)
• cnp: CNP number
• last_name: last name
• first_name: first name
• seria: series
• NR: number
• expire_date: document expiration date (as in document)
• birth_date: user birth date (as in document)
• recognized: whether the ID card is recognized by the service
• confidence: level of confidence in recognition (0 - card not recognized)

---