Session status

Retrieving the status and results of a single KYC session by sessionId or clientKey.

  • Method: POST
  • Path: kyc/session/status
  • Content-Type: application/json

Authorization

Two authorization methods are supported:

1. JWT token in the token header:

token: <jwt-token>

2. API token (timeuuid) in the request body:

{"token": "<api-token>", "sessionId": "..."}

Without a token (neither in the header nor in the body), the request will return "access denied".

Request parameters

ParameterTypeRequiredDescription
sessionIdstring (timeuuid)no*UUID v1 (timeuuid) of the session
clientKeystring (non-empty)no*Client key (non-empty string, max. 36 characters)

Parameter Priority

If both parameters are passed simultaneously, clientKey takes precedence — the search will be performed using clientKey, and sessionId will be ignored.

Limitations

  • sessionId must be a valid timeuuid (UUID v1)
  • clientKey — a non-empty string with a maximum length of 36 characters

Response format

Successful response (200)

{
  "status": "success",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "errors": [],
  "schemaId": "660e8400-e29b-41d4-a716-446655440000",
  "clientId": "770e8400-e29b-41d4-a716-446655440000",
  "spent": 24.184,
  "createdAt": "2026-03-19T10:31:06.000Z",
  "isClientNew": false,
  "clientKey": "my_client_key_123",
  "clientUser": "",
  "secondsToLive": 0,
  "responseTime": "2026-03-19T10:31:30.000Z",
  "results": [...],
  "email": "user@example.com",
  "wallet": "0x1234...abcd"
}

Response field description

FieldTypeDescription
statusstringSession status (see table below)
sessionIdstring (timeuuid)Session UUID v1 (timeuuid)
errorsarrayGeneral session errors
scenarioIdstring (UUID)KYC scenario UUID
clientIdstring (UUID)Client UUID (empty string if client is not identified)
spentnumberTotal processing time in seconds
createdAtstring (ISO 8601)Date and time of session creation
isClientNewbooleantrue — first client visit, false — repeat visit
clientKeystringClient key passed during session creation
clientUserstringClient user ID
secondsToLivenumberRemaining session lifetime in seconds (0 = expired)
responseTimestring (ISO 8601)Response generation time
resultsarrayArray of task results (see below)
emailstringClient email (optional)
walletstringClient crypto wallet address (optional)

Session statuses

StatusDescription
idleSession created, processing not started
processingSession in processing
successAll tasks completed successfully
failedOne or more tasks failed
exceptionA system error occurred
expiredSession lifetime expired

Task results (results)

The results array contains the results for each task of the KYC session. Task types: document, selfie, faces.

Task of type document

{
  "status": "success",
  "type": "document",
  "spent": 1.367,
  "errors": [],
  "docName": "ID Card",
  "tries": 1,
  "startedAt": "2026-03-19T10:31:08.000Z",
  "isBackSide": false,
  "countryCode": "GBR",
  "checks": [
    {
      "caption": "fraud",
      "items": [
        { "status": "success", "caption": "isPrinted", "confidence": 1 },
        { "status": "success", "caption": "isEdited", "confidence": 0.001 },
        { "status": "success", "caption": "isDisplay", "confidence": 0.938 }
      ]
    }
  ],
  "ocr": {
    "status": "success",
    "fields": [
      { "title": "Surname", "value": "DOE", "conf": "high" },
      { "title": "Given name(s)", "value": "JOHN", "conf": "high" },
      { "title": "Date of birth", "value": "01.01.1970", "conf": "high" }
    ]
  },
  "images": ["https://api.example.com/images/kyc/.../document_0/0"],
  "imagesFull": ["https://api.example.com/images/kycfull/.../document_0_0.jpg"],
  "imageObjects": ["https://api.example.com/images/kyc/.../stamp/0"],
  "history": [...]
}
FieldTypeDescription
statusstringTask status: idle, processing, success, failed
typestringTask type: document
spentnumberProcessing time in seconds
errorsarrayProcessing errors (e.g. "[document] unknown document type")
docNamestringRecognized document type (e.g. "ID Card", "ePassport (2005-2008)")
triesnumberNumber of recognition attempts
startedAtstring (ISO 8601)Processing start time
isBackSidebooleanIs the back side of the document
countryCodestringDocument country code (ISO 3166-1 alpha-3)
checksarrayCheck results (fraud checks)
ocrobjectText recognition results
imagesarrayLinks to processed images (thumbnails)
imagesFullarrayLinks to full-size images
imageObjectsarrayLinks to recognized objects (stamps, signatures)
historyarrayHistory of previous attempts (if tries > 1)

Task of type selfie

{
  "status": "success",
  "type": "selfie",
  "spent": 0.14,
  "errors": [],
  "docName": "ID Card",
  "tries": 1,
  "withDoc": ["ID Card"],
  "checks": [
    {
      "caption": "fraud",
      "items": [
        { "status": "success", "caption": "isFaceDeepFake" },
        { "status": "success", "caption": "isAgeMismatch", "value": 15 },
        { "status": "success", "caption": "isDisplaySelfie", "confidence": 1 },
        { "status": "success", "caption": "isGenderMismatch", "value": "female" }
      ]
    }
  ],
  "faceSelfie": "https://api.example.com/images/kycthumb/.../selfie/0",
  "faceDoc": "https://api.example.com/images/kycthumb/.../selfie_document/0",
  "images": ["https://api.example.com/images/kyc/.../selfie_0/0"],
  "imagesFull": ["https://api.example.com/images/kycfull/.../selfie_0_0.jpg"]
}
FieldTypeDescription
withDocarray/stringDocument(s) to which the selfie is matched
faceSelfiestringLink to the face cutout from the selfie
faceDocstringLink to the face cutout from the document

Task of type faces

Face comparison result. Appears when both a document and a selfie are present in the session.

{
  "status": "success",
  "type": "faces",
  "spent": 0.003,
  "errors": [],
  "checks": [
    {
      "caption": "Face matching",
      "items": [
        {
          "status": "success",
          "caption": "document_0 & selfie",
          "value": "92%",
          "images": [
            "https://api.example.com/images/kycthumb/.../document_0",
            "https://api.example.com/images/kycthumb/.../selfie"
          ]
        },
        {
          "status": "success",
          "caption": "document_0 & selfie_document",
          "value": "96%",
          "images": [...]
        }
      ]
    }
  ]
}
FieldTypeDescription
checks[].items[].valuestringPercentage of face match
checks[].items[].imagesarrayPair of compared images

Errors

Invalid scheme (400)

If the parameter format is violated:

{
  "status": "error",
  "message": "invalid schema",
  "details": [
    {
      "expected": {},
      "actual": "not-a-uuid",
      "path": "sessionId"
    }
  ]
}

Typical reasons:

  • sessionId is not a valid timeuuid (UUID v1)
  • clientKey is longer than 36 characters
  • clientKey — an empty string

Session not found (200)

{
  "status": "error",
  "message": "session not found"
}

Possible reasons:

  • Session with the specified sessionId or clientKey does not exist

ID not specified (400)

{
  "status": "error",
  "message": "sessionId or clientKey is required"
}

Occurs when neither sessionId nor clientKey is passed in the body.

No authorization (401)

{
  "status": "error",
  "message": "access denied"
}

Examples of queries

Search by sessionId

curl -X POST https://api.enface.ai/kyc/session/status 
  -H 'Content-Type: application/json' 
  -H 'token: <jwt-token>' 
  -d '{"sessionId": "550e8400-e29b-41d4-a716-446655440000"}'

Search by clientKey

curl -X POST https://api.enface.ai/kyc/session/status 
  -H 'Content-Type: application/json' 
  -H 'token: <jwt-token>' 
  -d '{"clientKey": "my_client_key_123"}'

Typical fraud checks

For documents (type: «document»)

CaptionDescription
isMRZValidMRZ zone validity
isStampsOkStamps/seals check
isPrintedDocument is printed (not a photo of the screen)
isDamagedDocument is not damaged
isOtherObjectsOkNo extraneous objects
isXerocopyDocument is not a xerocopy
isEditedDocument is not edited
isSignatureOwnerOkOwner’s signature
isSignatureIssuerOkIssuing authority’s signature
isDisplayDocument is not photographed from the screen
isFieldsModifiedFields are not modified
isCroppedDocument is not cropped
isFieldsCorrectedFields were not corrected
isMobileTaken from a mobile device
isPhotoApplicationPhoto without an editor application
isLogicalMismatchNo logical inconsistencies

For selfies (type: «selfie»)

CaptionDescription
isFaceDeepFakeDeepfake check
isAgeMismatchAge match (value = difference in years)
isCroppedPhoto is not cropped
isXerocopyNot a photocopy
isGenderMismatchGender match (value = specific gender)
isDisplaySelfieNot a photo from the screen
isMobileTaken with a mobile phone