API

Overview

This document describes the API endpoints used in the X-Faces verification system. It also explains the reasoning behind each call, the expected data flow, and how the system behaves in each step.

Authentication

All requests must include the API token received from your X-Faces representative.

---

Response Wrapper Format

All responses from X-Faces follow this format:

{
  "result": true,
  "data": { ... }
}

Verification Flow

1. Register User

Endpoint: POST /user/create
Description: Creates a new user and returns a unique u_uuid.

2. Redirect to Verification

Endpoint: GET /user/verify/{u_uuid}
Description: Redirects the user to the X-Faces platform to complete the verification process.

3. Complete Challenge

Description: The user completes the verification challenge. X-Faces automatically updates their verification status.

4. Retrieve Results

Endpoint: GET /user/get/{u_uuid}
Description: Retrieves the user’s current status and the results of the verification challenge.

5. Manual Update (Optional)

Endpoint: POST /user/update/{u_uuid}
Description: Manually updates the user’s verification status or applies decisions if needed.

6. Retrieve Uploaded Image

Endpoint: GET /images/{i_uuid}
Description: Returns image associated with the verification process.

---

Create User

AUTH REQUIRED
Endpoint: POST https://api.x-faces.xyz/v1/user/create
Content-Type: application/json

Body:

{
  "external_id": "your-unique-user-id",
  "notification_url": "https://your-app.com/notify",
  "redirect_url": "https://your-app.com/thanks",
  "expected_data": {
    "cnp": "1234567890123"
  }
}

• external_id: user identifier in the external system
• notification_url: link for sending notifications about user changes
• redirect_url: link to display to the user after successfully passing the challenge

Response:

{
  "result": true,
  "data": {
    "id": "user-uuid"
  }
}

• result: whether user creation was successful
• id: user identifier in x-faces (UUID)

Test Request

Headers

token

Body

external_id

notification_url

redirect_url

Send API

---

Verify URL

To send the user for verification, the external service creates a link of the following form:

GET https://api.x-faces.xyz/v1/user/verify/<u_uuid>

Where guid is taken from the response of the POST:

POST `https://api.x-faces.xyz/v1/user/create`

In the response body, the id field represents the guid.

---

Get User Data

AUTH REQUIRED
Endpoint: GET https://api.x-faces.xyz/v1/user/get/<u_uuid>

Endpoint for retrieving detailed user data, their status, and challenges.

Response:

{
  "result": "bool",
  "data": {
    "user": {
      "created_at": "timestamptz",
      "updated_at": "timestamptz",
      "u_uuid": "string uuid",
      "external_id": "string",
      "verified": "bool",
      "have_actual_document": "bool", // nullable
      "require_manual_check": "bool",
      "rejection_reasons": "list of str",
      "verified_at": "timestamptz",
      "challenge_id": "integer",
      "c_uuid": "string uuid"
    },
    "challenges": {
      "challenge_id": { ... }
    }
  }

}

• user: user data (see user business entity structure)
• challenges: challenge data (see challenge business entity structure)
• have_actual_document: if null that means that X-Faces can’t correctly read the expiration data of uploaded document.

Test Request

Headers

token

Params

u_uuid

Send API

---

Update User

AUTH REQUIRED
Endpoint: POST https://api.x-faces.xyz/v1/user/update/<u_uuid>
Content-Type: application/json

Body:

{
  "notification_url": "https://your-app.com/notify",
  "redirect_url": "https://your-app.com/thanks",
  "verified": true,
  "reject_reason": "idCardExpired",
  "expected_data": {
    "cnp": "1234567890123"
  }
}

If some of the fields (like verified or expected_data) do not exist in the body - those fields of the user not be updated.

Test Request

Headers

token

Body

notification_url

redirect_url

verified

reject_reason

Params

u_uuid

Send API

Get Image

AUTH REQUIRED
Endpoint: GET https://api.x-faces.xyz/v1/images/<i_uuid>

i_uuid is obtained from the images block in the challenge business entity. Separately for face and id_card. The response is a normal image/jpeg (possibly image/png).

Test Request

Headers

token

Params

i_uuid

Send API