Get started

OCR API - Getting Started

This guide shows you how to use the OCR API to extract information from your document images.

Endpoint

POST https://crm-demo.cynopsis.co/service/v2/ocr

Request Example

Send a multipart/form-data request with at least the front document image (file0) and optionally the back image (file1).

curl --request POST \
  --url https://crm-demo.cynopsis.co/service/v2/ocr \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Domain-Id: <x-domain-id>' \
  --form file0=@example-file \
  --form file1=@example-file

Required headers:

• Authorization: Bearer <token>: Your JWT access token.
• X-Domain-Id: <x-domain-id>: Your assigned Domain ID.
• Content-Type: multipart/form-data: Required for file uploads.

Form fields:

• file0 (required): Main document file (front image).
• file1 (optional): Secondary document file (back image, if needed).

⚠️ Note:
Ensure that the file being uploaded is in a supported image format for OCR processing.

Response

Status Code: 201 Created
Content-Type: application/json

Fields Returned:

• task_id: Unique identifier for the OCR processing task.

• status_task: The current processing status. Example: SUCCESS.

• result: Contains extracted data such as:

  • first_name
  • last_name
  • full_name (combination of first_name and last_name)
  • full_name2 (combination of last_name and first_name)
  • gender
  • date_of_birth
  • passport_number
  • document_type
  • Other fields including address, issuing_country, and more.
  • Fields that cannot be extracted will have a null or empty value.
  Example:
  If first_name is "MICHAEL" and last_name is "LEE":

  • full_name would be "MICHAEL LEE"
  • full_name2 would be "LEE MICHAEL"

• docver_check: Contains document verification details such as id, code, person (with extracted personal details), document, reason, status, etc. This provides insights into the verification and validity of the uploaded document.

Sample Response

{
  "task_id": "156f047d-f8ad-4ba1-9296-a491675d0620",
  "status_task": "SUCCESS",
  "result": {
    "last_name": "LEE",
    "first_name": "WANG",
    "full_name": "WANG LEE",
    "full_name2": "LEE WANG"
    "gender": "",
    "race": "",
    "date_of_birth": null,
    "domicile": "",
    "address": "",
    "passport_number": "",
    "document_number": null,
    "personal_id_number": null,
    "issuing_country": "SINGAPORE",
    "country_of_birth": null,
    "nationality": null,
    "passport_expiry_date": "",
    "expiry_date": null,
    "issue_date": null,
    "optional_data": null,
    "final hash": "",
    "document number hash": "",
    "birth date hash": "",
    "profession": "",
    "expiry date hash": "",
    "optional data hash": "",
    "document type format": "",
    "valid country code": "",
    "valid nationality code": "",
    "birth date": null,
    "expiry date": null,
    "valid genre format": "",
    "mrz_raw_string": "",
    "identifier": "",
    "document number format": "",
    "optional data format": "",
    "employer": "",
    "status": "UNCERTAIN",
    "document_type": "RESIDENCE_PERMIT",
    "document_type_name": "NATIONAL ID",
    "docver_check": {
      "id": "8fd56097-caad-410b-8e57-fcaf24524007",
      "code": 9102,
      "person": {
        "gender": null,
        "idNumber": null,
        "lastName": null,
        "addresses": [],
        "firstName": "STEVANIE",
        "citizenship": null,
        "dateOfBirth": null,
        "nationality": null,
        "yearOfBirth": null,
        "placeOfBirth": null,
        "pepSanctionMatch": null
      },
      "reason": "Presented document tampered, document similarity to specimen",
      "status": "declined",
      "comments": [],
      "document": {
        "type": "RESIDENCE_PERMIT",
        "state": null,
        "number": null,
        "country": "SG",
        "validFrom": null,
        "validUntil": null
      },
      "attemptId": "f85ac94c-5927-4a01-b9e1-f84a40cc9b1e",
      "endUserId": null,
      "reasonCode": 508,
      "vendorData": null,
      "decisionTime": "2025-06-16T06:21:13.759386Z",
      "acceptanceTime": "2025-06-16T06:21:06.082696Z",
      "additionalVerifiedData": {},
      "recommendation": ""
    }
  }
}

---

Additional Notes

• Some fields in the response may be null or omitted, depending on the document and extraction quality.
• The docver_check object gives detailed information about the document verification outcome including codes and reasoning.

If you have further questions, please refer to the full API Reference or contact support.