National ID OCR

Our National ID OCR API provides enterprise-grade data extraction for identity cards worldwide, with specialized support for European (e.g., Romania), South American, and African regions. It automatically handles complex multi-line addresses, specialized personal numbers (CNP, CPF, NIN), and derived data fields to ensure seamless KYC and identity verification.

Endpoint

POSThttps://api.structocr.com/v1/national-id

Request Parameters

Important: This endpoint requires application/json Content-Type. Images must be sent as Base64 strings.

Parameter	In	Required	Description
x-api-key	Header	Required	Your unique API key generated from the dashboard.
Content-Type	Header	Required	Must be set to `application/json`.
img	Body (JSON)	Required	The Base64 encoded string of the ID card image. Supports standard Data URI (e.g., `data:image/jpeg;base64,...`) Supports raw Base64 strings Max file size: 4.5MB Formats: JPG, PNG, WebP

Response Schema

The following fields are extracted into the data object. All dates are normalized to YYYY-MM-DD.

Field	Description
type	Document type indicator (fixed as 'national_id').
country_code	ISO 3166-1 alpha-3 country code (e.g., 'ROU', 'BRA').
document_number	The unique serial number of the physical ID card.
personal_number	National ID number (CNP for Romania, CPF for Brazil, NIN for Nigeria).
card_series	Document series identifier (common in EU IDs, e.g., 'RX').
surname	The holder's last name or family name.
given_names	The holder's first and middle names.
sex	Gender indicator, typically 'M' or 'F'.
date_of_birth	Holder's birth date in YYYY-MM-DD format.
place_of_birth	Full text location of birth (City/Region).
address	Full residential address (supports multi-line extraction).
date_of_issue	The date when the identification card was issued.
date_of_expiry	The date when the document's validity expires.
issuing_authority	The government agency that issued the document.

Code Examples

Request Implementation

curl -X POST https://api.structocr.com/v1/national-id \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "img": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }'

Success Response (200 OK)

{
  "success": true,
  "data": {
    "type": "national_id",
    "country_code": "ROU",
    "nationality": "ROMANA",
    "document_number": "123456",
    "card_series": "KS",
    "personal_number": "1920319123456",
    "surname": "POPESCU",
    "given_names": "ANDREI",
    "sex": "M",
    "date_of_birth": "1992-03-19",
    "place_of_birth": "Jud. CS Mun. Reșița",
    "address": "Jud. CS Orș. Bocșa Str. Nucilor Nr. 15",
    "date_of_issue": "2020-05-10",
    "date_of_expiry": "2030-05-10",
    "issuing_authority": "SPCLEP Bocșa"
  }
}

Error Responses

400 Bad Request - Invalid Input

Returned when JSON is invalid or image data is missing.

{
  "error": "INVALID_JSON" 
  // or "NO_IMAGE_DATA", "INVALID_BASE64"
}

402 Payment Required - Insufficient Credits

{
  "success": false,
  "error": "INSUFFICIENT_CREDITS",
  "message": "Your account balance is insufficient to complete this operation."
}

413 Payload Too Large

{
  "error": "FILE_TOO_LARGE"
}

415 Unsupported Media Type

{
  "error": "INVALID_CONTENT_TYPE_USE_JSON"
}

422 Unprocessable Entity - Policy Violation

{
  "success": false,
  "error": "CONTENT_POLICY_VIOLATION",
  "message": "The document content could not be processed due to safety policies."
}

500 Internal Server Error

{
  "success": false,
  "error": "PROCESSING_ERROR",
  "message": "An internal error occurred while processing the document. Please contact support if the problem persists."
}

503 Service Unavailable - System Busy

{
  "success": false,
  "error": "SYSTEM_BUSY",
  "message": "StructOCR is currently processing a high volume of requests. Please try again in a few seconds."
}

Status Code Definitions

Code	Error Code	Description
200	SUCCESS	Recognition success
400	INVALID_JSON	Invalid Body or corrupted Base64
402	INSUFFICIENT_CREDITS	Account balance too low
413	FILE_TOO_LARGE	Decoded image exceeds 4.5MB
415	INVALID_CONTENT_TYPE	Not using application/json
422	CONTENT_POLICY_VIOLATION	AI safety/policy block
503	SYSTEM_BUSY	API Rate limit reached