JONGAOCR
API Docs

API Endpoints

Complete reference for all Jonga OCR API endpoints. Six OCR document endpoints plus utility endpoints for health, tokens, and diagnostics.

Base URL: https://your-domain.vercel.app/api/v1

Request Format

OCR endpoints accept images in two formats. Choose whichever is most convenient for your integration.

Option 1: Multipart Form Data

multipart/form-databash
curl -X POST https://your-domain.vercel.app/api/v1/ocr/sa-id-smart-front \
  -H "Authorization: Bearer jonga_YOUR_TOKEN" \
  -F "image=@./id-front.jpg"

Option 2: JSON Body (Base64)

application/jsonbash
curl -X POST https://your-domain.vercel.app/api/v1/ocr/sa-id-smart-front \
  -H "Authorization: Bearer jonga_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-image>",
    "mediaType": "image/jpeg"
  }'

Response Envelope

All responses follow a consistent envelope structure.

Success Responsejson
{
  "success": true,
  "documentType": "sa-id-smart-front",
  "confidence": "high",
  "data": {
    "surname": "MALUNGANA",
    "names": "THEODORE",
    "sex": "M",
    "dateOfBirth": "1989-10-06",
    "idNumber": "8910065781082",
    "countryOfBirth": "RSA",
    "citizenshipStatus": "Citizen",
    "nationality": "RSA"
  },
  "meta": {
    "processedAt": "2026-04-05T10:00:00Z",
    "latencyMs": 3200
  }
}
Error Responsejson
{
  "success": false,
  "error": {
    "code": "IMAGE_MISSING",
    "message": "No image provided"
  }
}

OCR Endpoints

POST/api/v1/ocr/sa-id-smart-frontBearer Token

Extract data from the front of a South African Smart ID card. Returns personal information including name, ID number, date of birth, and citizenship status.

Response Fields

surnamestring|nullSurname as printed on the card
namesstring|nullFirst names as printed on the card
sex"M"|"F"|nullSex of the card holder
dateOfBirthstring|nullDate of birth (YYYY-MM-DD format)
idNumberstring|nullSA ID number (13 digits)
countryOfBirthstring|nullCountry of birth code
citizenshipStatus"Citizen"|"Permanent Resident"|nullCitizenship status
nationalitystring|nullNationality code
POST/api/v1/ocr/sa-id-smart-backBearer Token

Extract data from the back of a South African Smart ID card. Returns the card number and issue date.

Response Fields

cardNumberstring|nullUnique card number printed on the back
dateOfIssuestring|nullDate the card was issued (YYYY-MM-DD format)
POST/api/v1/ocr/sa-id-greenbookBearer Token

Extract data from a South African Green Book ID biographical page. Returns personal information and barcode data.

Response Fields

surnamestring|nullSurname of the holder
namesstring|nullFirst names of the holder
dateOfBirthstring|nullDate of birth (YYYY-MM-DD format)
idNumberstring|nullSA ID number (13 digits)
sexstring|nullSex of the holder
citizenshipStatusstring|nullCitizenship status
nationalitystring|nullNationality
countryOfBirthstring|nullCountry of birth
barcodeDatastring|nullRaw barcode data if readable
POST/api/v1/ocr/passportBearer Token

Extract data from an international passport biographical page from ANY country. ICAO Doc 9303 compliant — uses the standardized Machine Readable Zone (MRZ) for reliable cross-country extraction. Works with passports from all ICAO member states.

Response Fields

documentTypestring|nullDocument type code (e.g., "P", "PP", "PM")
issuingCountrystring|nullIssuing country as ISO 3166-1 alpha-3 (e.g., "ZAF", "USA", "GBR")
passportNumberstring|nullPassport number (alphanumeric, country-specific length)
surnamestring|nullPrimary/family name of the holder
givenNamesstring|nullGiven names of the holder
nationalitystring|nullNationality as ISO 3166-1 alpha-3
dateOfBirthstring|nullDate of birth (YYYY-MM-DD format)
sex"M"|"F"|"X"|nullSex of the holder (X supported for non-binary passports)
dateOfExpirystring|nullDate of expiry (YYYY-MM-DD format)
personalNumberstring|nullCountry-specific personal identifier (optional)
dateOfIssuestring|nullDate of issue (YYYY-MM-DD format)
placeOfBirthstring|nullPlace of birth as printed
issuingAuthoritystring|nullIssuing authority (e.g., "DHA", "U.S. Department of State")
mrzLine1string|nullMRZ line 1 (44 chars, includes < characters)
mrzLine2string|nullMRZ line 2 (44 chars, includes < characters)
POST/api/v1/ocr/sa-drivers-frontBearer Token

Extract data from the front of a South African driver's license. Returns personal information, license details, and vehicle codes.

Response Fields

surnamestring|nullSurname of the holder
initialsstring|nullInitials of the holder
idNumberstring|nullSA ID number (13 digits)
dateOfBirthstring|nullDate of birth (YYYY-MM-DD format)
licenseNumberstring|nullLicense number
dateOfIssuestring|nullDate of issue (YYYY-MM-DD format)
dateOfExpirystring|nullDate of expiry (YYYY-MM-DD format)
vehicleCodesstring[]|nullVehicle category codes (e.g. A1, B, C, EB)
pdpExpirystring|nullProfessional driving permit expiry date
restrictionsstring|nullLicense restrictions (e.g. corrective lenses)
POST/api/v1/ocr/sa-drivers-backBearer Token

Extract data from the back of a South African driver's license. Barcode data is encrypted and cannot be decoded.

Response Fields

rawBarcodeDecodednullAlways null — SA license barcodes are encrypted
idNumberstring|nullSA ID number (13 digits)
licenseNumberstring|nullLicense number
vehicleCodesstring[]|nullVehicle category codes
dateOfExpirystring|nullDate of expiry (YYYY-MM-DD format)

Utility Endpoints

GET/api/v1/health

Health check endpoint. No authentication required. Returns API status, version, database connectivity, and server timestamp.

Response Fields

statusstringAPI status (e.g. "healthy")
versionstringAPI version (e.g. "1.0.0")
databasestringDatabase connection status
timestampstringServer timestamp (ISO 8601)
GET/api/v1/tokens/meBearer Token

Retrieve metadata about the authenticated token. Returns scopes, usage statistics, and expiration info.

Response Fields

tokenPrefixstringFirst 10 characters of the token
projectNamestringProject name
scopesstring[]Authorized scopes
isActivebooleanWhether the token is active
expiresAtstring|nullExpiration date
createdAtstringCreation timestamp
lastUsedAtstring|nullLast usage timestamp
requestCountnumberTotal number of requests made

Confidence Levels

Every OCR response includes a confidence field indicating the quality of the extraction.

highAll fields were successfully read from the document
medium30% or fewer fields returned null
lowMore than 30% of fields returned null

Rate Limit Headers

Every OCR response includes rate limit information in the response headers.

X-RateLimit-LimitMaximum number of requests allowed per window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp when the rate limit window resets