Check KYC session status

POST /kyc/session/status

Description

The method returns the current status of a KYC session, as well as detailed results for each verification stage (document, selfie, face matching, errors, and recognized fields). A JWT token in the header is required for access.

Request Format

HTTP method: POST
URL: /kyc/session/status
Content-Type: application/json
Authorization: required

Request Parameters

Parameter	Type	Where passed	Required	Description
token	string	Header	✅	User JWT token

Request Body (JSON)

Field	Type	Required	Description
token	string	✅	User JWT token
sessionId	string	✅	KYC session identifier
clientKey	string	❌	Client key

Request Example (cURL)

curl -X POST "https://api.enface.ai/kyc/session/status" 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer jwt.temporary.token" 
  -d '{
    "token": "jwt.temporary.token",
    "sessionId": "00000000-0000-0000-0000-000000000000",
    "clientKey": "abcde12345"
  }'

Response Examples

Success (200 OK)

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "clientId": "null",
  "status": "idle",
  "spent": 0,
  "results": [
    {
      "status": "idle",
      "type": "document",
      "spent": 0,
      "errors": [],
      "checks": []
    }
  ],
  "createdAt": "2025-05-21T08:12:05.336Z",
  "isClientNew": true
}

Success (example for document):

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "clientId": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "spent": 136.945,
  "results": [
    {
      "spent": 8.779,
      "status": "success",
      "type": "document",
      "docName": "UK - Passport (2006)",
      "image": "url",
      "imageFull": "url",
      "checks": [
        {
          "caption": "fraud",
          "items": [
            {
              "caption": "isEdited",
              "status": "success"
            }
          ]
        }
      ],
      "ocr": {
        "fields": [
          {
            "conf": "high",
            "title": "Surname",
            "value": "DOE"
          }
        ],
        "status": "success"
      },
      "errors": [
        "[document] text fields not visible"
      ]
    }
  ],
  "createdAt": "2025-05-21T08:12:05.338Z",
  "isClientNew": false
}

Success (example for selfie and document):

{
  "sessionId": "10000000-0000-0000-0000-000000000000",
  "clientId": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "spent": 36.11,
  "results": [
    {
      "status": "success",
      "type": "passport",
      "spent": 4.453,
      "errors": [],
      "docName": "UK - Passport (2006)",
      "checks": [
        {
          "caption": "fraud",
          "items": [
            {
              "status": "success",
              "caption": "isEdited"
            },
            {
              "status": "success",
              "caption": "isDisplay"
            },
            {
              "status": "success",
              "caption": "isPrinted"
            }
          ]
        }
      ],
      "ocr": {
        "status": "success",
        "fields": [
          {
            "title": "Surname",
            "value": "DOE",
            "conf": "high"
          }
        ]
      },
      "image": "url_to_passport_image",
      "imageFull": "url_to_full_passport_image"
    },
    {
      "status": "success",
      "type": "selfie",
      "spent": 4.664,
      "errors": [],
      "docName": "UK - Passport (2006)",
      "checks": [
        {
          "caption": "fraud",
          "items": [
            {
              "status": "success",
              "caption": "isEdited"
            }
          ]
        }
      ],
      "faceSelfie": "url_to_selfie_image",
      "faceDoc": "url_to_face_document_image",
      "withDoc": "passport",
      "image": "url_to_selfie_image",
      "imageFull": "url_to_full_selfie_image"
    },
    {
      "status": "success",
      "type": "faces",
      "spent": 0.004,
      "errors": [],
      "checks": [
        {
          "caption": "Face matching",
          "items": [
            {
              "status": "success",
              "caption": "selfie with passport & passport",
              "value": "92%",
              "images": [
                "url_to_selfie_with_passport_image",
                "url_to_passport_image"
              ]
            }
          ]
        }
      ]
    }
  ],
  "createdAt": "2025-05-21T08:12:05.340Z",
  "isClientNew": false
}

Error (400 Bad Request)

{
  "message": "invalid schema",
  "status": "error"
}

Error (failed)

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "clientId": "null",
  "status": "failed",
  "spent": 261.569,
  "results": [
    {
      "status": "failed",
      "type": "document",
      "spent": 0,
      "errors": [
        "[system] exception"
      ],
      "ocr": {
        "status": "idle",
        "fields": []
      }
    }
  ],
  "createdAt": "2025-05-21T08:12:05.346Z",
  "isClientNew": true
}