Scan Agent (SmartScan)

Scan Agent is the SmartScan OCR entry point used by trained project flows to extract structured fields from identity documents. It complements Scan Prompt (flexible prompts) and Scan Studio (trained models).

Endpoint

POST https://api.verifik.co/v2/ocr/scan-agent

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Parameters

Exact fields depend on your project flow configuration (document type, sides to capture, and validation steps). Typical payloads include document images (image, backImage, or flow-specific keys) and a projectFlow identifier.

Name	Type	Required	Description
colombianBarcodeValidation	boolean	No	When true, runs Colombian cédula PDF417 barcode anti-fraud validation on the rear capture to detect altered or counterfeit cards, attaching results under OCRExtraction.barcodeValidation. If omitted, the project flow’s colombianBarcodeValidation setting applies.

Colombian barcode validation

For Colombian CC flows, barcode cross-checking acts as an automated anti-fraud shield. If a fraudster presents a card with doctored front text (altered name or document number), barcode validation automatically flags the discrepancy (verdict: "mismatch") and flags the registration for manual review (NEEDS_MANUAL_VERIFICATION). If the barcode itself has been tampered with or corrupted, decoding fails (verdict: "unreadable").

Enable barcode validation in either place:

1. Project flow — turn on colombianBarcodeValidation in the SmartScan / SmartEnroll project flow settings in the Verifik client panel.
2. Request body — pass colombianBarcodeValidation: true on POST /v2/ocr/scan-agent to force the read for that call (useful for tests or one-off API integrations).

When enabled and a usable back image is present, the OCR extraction includes barcodeValidation with the same verdicts and fields as the standalone barcode API (decoded / unreadable, or confirmed / mismatch / unreadable when cross-check inputs are available from the flow).

Standalone reference, fraud prevention guide, and billing rules: Colombia — Cédula barcode (PDF417).

Response excerpt (barcode enabled)

200

{
  "data": {
    "OCRExtraction": {
      "documentType": "CC",
      "documentNumber": "1234567890",
      "firstName": "MARIA",
      "lastName": "LOPEZ GARCIA",
      "barcodeValidation": {
        "verdict": "confirmed",
        "attempts": 1,
        "barcode": {
          "documentNumber": "1234567890",
          "primerNombre": "MARIA",
          "segundoNombre": "ELENA",
          "primerApellido": "LOPEZ",
          "segundoApellido": "GARCIA",
          "gender": "F",
          "dateOfBirth": "15/03/1992",
          "bloodType": "O+",
          "fullName": "MARIA ELENA LOPEZ GARCIA"
        },
        "matchScores": {
          "documentNumber": 1,
          "firstName": 0.98,
          "lastName": 0.97
        },
        "disagreements": []
      }
    }
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "October 21, 2026 3:00 PM"
  },
  "id": "SA12B"
}

Notes

• Barcode validation requires a clear rear image; front-only uploads skip or mark the barcode step unreadable.
• Credit usage follows your SmartScan / smartENROLL feature configuration (client panel or Postman). See Smart Scan overview.
• Hosted document capture can also run barcode validation when the project enables it — see App registration document validation.