Recognize documents and selfies from an array of images

POST /kyc/process

Description

The method defines, selects, and recognizes documents and selfies from an array of images. It allows uploading multiple files, performing OCR, and saving results in a session. A token is required, see Authorization.

Request format

  • HTTP method: POST
  • URL: /kyc/process
  • Content type: multipart/form-data

Authorization

Pass the token in one of two ways:

  • the token: <jwt-token> header — a temporary JWT token obtained with user/login;
  • the token field in the request body — a permanent API token (UUID) from your account.

Without a token the request returns 401 access denied.

Query Parameters

ParameterTypePassed inRequiredDescription
tokenstringform-data—Permanent API token (UUID), if the token header is not sent
imagesarrayform-data✅Images (files), 1 to 10 per request
sessionIdstring (UUID)form-data❌Session to upload images to. If omitted, a new session is created with schemaId
schemaIdstring (UUID)form-data✅ for a new sessionScenario ID. Required unless sessionId of an existing session is passed
modestringform-data❌Execution mode: ‘async’ or ‘sync’ (default ‘sync’)
clientKeystringform-data❌Your client identifier, up to 36 characters. Without sessionId the session is looked up by it; if there is none, a new one is created with schemaId and this key
clientUserstringform-data❌Your operator identifier, up to 36 characters. It is stored in the session and returned in its status
stepIndexstringform-data❌Zero-based number of the scenario step the image is meant for — the position of the step in the session’s results. Without it the step is chosen automatically. With several images the field is repeated once per image, in the same order: either for every image or for none
ocrbooleanform-data❌Perform OCR of documents (default true)

stepIndex

  • The number is a string of digits.
  • With several images the number of values must equal the number of images, and the numbers must not repeat. Otherwise — 400 [rest.kycProcess]: invalid schema with details on the stepIndex field.
  • A number the step cannot accept gives 400 [request] invalid stepIndex: <reason>:
ReasonMeaning
out of rangeThe scenario has no step with this number
step kind mismatchThe step is of a different kind than the image (for example, a selfie sent to a document step)
step closedThe step is already passed, out of tries, or at its critical error limit

A refused request processes no image and does not change the session. A session of linked scenarios has a single step until the scenario is chosen (selectedSchemaId is null): send the first document without a number or with 0.

Example Request (cURL)

curl -X POST "https://api.neuro-vision.ru/v1/kyc/process" -H "token: <jwt-token>" -F "images=@/path/to/passport.jpg" -F "images=@/path/to/selfie.jpg" -F "schemaId=660e8400-e29b-41d4-a716-446655440000" -F "ocr=true" -F "mode=sync"

Example Answers

Success (200 OK)

The checks field in the step results holds the fraud checks; their names and statuses are described in the "Fraud checks (checks)" section of the Session status page.

{
  "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": "GBR — Passport(2006)",
      "images": ["url"],
      "imagesFull": ["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:15:46.972Z",
  "isClientNew": false
}

Success (selfie & doc)

{
  "sessionId": "10000000-0000-0000-0000-000000000000",
  "clientId": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "spent": 36.11,
  "results": [
    {
      "status": "success",
      "type": "document",
      "spent": 4.453,
      "errors": [],
      "docName": "GBR — 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"
          }
        ]
      },
      "images": ["url_to_passport_image"],
      "imagesFull": ["url_to_full_passport_image"]
    },
    {
      "status": "success",
      "type": "selfie",
      "spent": 4.664,
      "errors": [],
      "docName": "GBR — Passport (2006)",
      "checks": [
        {
          "caption": "fraud",
          "items": [
            {
              "status": "success",
              "caption": "isEdited"
            }
          ]
        }
      ],
      "faceSelfie": "url_to_selfie_image",
      "faceDoc": "url_to_face_document_image",
      "withDoc": "passport",
      "images": ["url_to_selfie_image"],
      "imagesFull": ["url_to_full_selfie_image"]
    },
    {
      "status": "success",
      "type": "faces",
      "spent": 0.004,
      "errors": [],
      "checks": [
        {
          "caption": "Face matching",
          "items": [
            {
              "status": "success",
              "index": 0,
              "caption": "document_0 & selfie_document_1",
              "images": [
                "url_to_selfie_with_passport_image",
                "url_to_passport_image"
              ]
            },
            {
              "status": "success",
              "index": 1,
              "caption": "document_0 & selfie_2",
              "images": [
                "url_to_selfie_image",
                "url_to_passport_image_for_selfie_comparison"
              ]
            }
          ]
        }
      ]
    }
  ],
  "createdAt": "2025-05-21T08:15:46.975Z",
  "isClientNew": false
}

Error (400)

{
  "status": "error",
  "message": "[rest.kycProcess]: invalid schema"
}
ResponseCause
400 at least 1 image is requiredThe request has no images
400 [rest.kycProcess]: invalid schemaThe parameters do not match the description (for example, clientKey or clientUser is longer than 36 characters); see details
400 Maximum supported image size N MbAn image exceeds the allowed size; N is the current limit in megabytes
400 bad schemaIdThe request creates a session, but schemaId is not passed
400 [rest.kycProcess] no schema for request, please create at least 1No scenario with the passed schemaId in your account
400 [request] invalid stepIndex: <reason>The step with the given number cannot accept the image, see “stepIndex”
400More than 10 images in one request
401 access deniedNo token, or the token is invalid

Error (failed)

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