Costa Rica identity card OCR: Extract Fields with Python

Costa Rica document intake: what needs review

Keep citizen identity documents distinct from residence documents and retain the printed document type during intake review. In a production intake, keep the uploaded document associated with the correct application record before extraction. A legible name alone does not establish that the number, dates and address were captured correctly. Avoid filling missing values from a previous booking or a customer profile without recording that separate source.

Map Costa Rica document evidence into your backend

Check the printed document type before assigning its number to an identity record. Submit a readable side at a time and keep the side association in your application. A field absent from the submitted side should remain unfilled until supported by another source. Send the image to the national id API and keep extracted evidence separate from your approval decision. The same endpoint handles the submitted image; the article's country or state context does not force the API to return that jurisdiction. Compare the returned country with the source before saving the result.

A reviewable intake workflow

• Costa Rica document intake: Keep citizen identity documents distinct from residence documents and retain the printed document type during intake review.
• Map fields without losing their meaning: Store document_number as text, keep surname and given_names in their own fields, and retain source images according to your document-handling policy. Date parsing failures should be reviewable instead of becoming today's date.
• Compare a resubmitted document: Keep a prior extraction and a new extraction as separate events. A change in number, name or expiry should produce a review item, not an automatic overwrite of a trusted record.
• Export only the fields your workflow uses: Map the response to your form explicitly. Keep the document number separate from any supported personal identifier.

Python request for Costa Rica identity card OCR

This REST example sends a local image as Base64 JSON. Run it on a backend and keep the API key in an environment variable. The printed example below is deliberately synthetic and is not a valid document-number format specimen.

Prerequisite: Python 3, pip install requests; STRUCTOCR_API_KEY set on the server

import base64
import os
import requests

with open("costa-rica-national-id.jpg", "rb") as source:
    encoded = base64.b64encode(source.read()).decode("ascii")

response = requests.post(
    "https://api.structocr.com/v1/national-id",
    headers={"x-api-key": os.environ["STRUCTOCR_API_KEY"]},
    json={"img": encoded},
    timeout=60,
)
response.raise_for_status()
result = response.json()
if not result.get("success"):
    raise RuntimeError("Extraction was not successful; inspect the response securely")
data = result.get("data") or {}
required = ["document_number", "surname", "date_of_expiry"]
missing = [field for field in required if not data.get(field)]
# Queue incomplete records; do not log identity data in production.
print({"needs_review": bool(missing), "missing_fields": missing})

Illustrative response fields

Synthetic subset of the response for mapping purposes. Values and dates are examples, not a real scan or an assertion about document validity periods. Actual fields depend on the submitted document.

{
  "success": true,
  "data": {
    "country_code": "CRI",
    "document_number": "EXAMPLE-NOT-A-REAL-ID",
    "surname": "EXAMPLE",
    "given_names": "PERSON",
    "date_of_birth": "1990-01-15",
    "date_of_issue": "2024-04-12",
    "date_of_expiry": "2029-04-12",
    "issuing_authority": null,
    "personal_number": null,
    "address": null,
    "additional_fields": {}
  }
}