South Africa passport OCR API

Recognising a South Africa passport

A South Africa passport follows the ICAO 9303 standard: a two-line, 44-character machine-readable zone (format TD3) printed at the foot of the data page, below the human-readable visual inspection zone. Its first five characters are P<ZAF – the document code, then the issuing stateas the ISO 3166-1 alpha-3 code ZAF. The API reads both zones, cross-checks the MRZ check digits, and returns one response shape with every key present.

South Africa is ZA in an alpha-2 list and ZAF in the zone: here the longer code is the shorter one with F after it. That holds for this pair and not as a rule, so deriving one from the other is a bug waiting for the first country it does not fit.

What is particular to the South Africa passport

Issued by Department of Home Affairs.

• The ordinary tourist passport is issued to citizens aged 16 or older, is valid for 10 years and has 32 pages; the 48-page maxi passport is also valid for 10 years.
• A minor's tourist passport is issued to citizens aged 15 or younger and is valid for five years.
• Names are printed as they appear in the National Population Register at the time of application.
• Home Affairs no longer issues temporary passports.

Sources:

• Department of Home Affairs – travel documents

Machine-readable zones issued by South Africa

9303 defines three zone layouts, and the API reads all three. Below is one invented holder – she is nobody, and paradeigma is the Greek word for example – in each layout, with ZAF as the issuing state. Every check digit is computed from the characters beside it rather than typed in, so each zone here validates.

P<ZAFPARADEIGMA<<ELENI<SOFIA<<<<<<<<<<<<<<<<
AM73045184ZAF9403084F3203101PN48291630<<<<72

I<ZAFPARADEIGMA<<ELENI<SOFIA<<<<<<<<
TR61850420GRC9403084F2911043<<<<<<<2

IDZAFAK472913<4PN48291630<<<<<
9403084F3405204GRC<<<<<<<<<<<9
PARADEIGMA<<ELENI<SOFIA<<<<<<<

No check digit covers the issuing state: on all three layouts the arithmetic runs over the document number, the dates and the optional data, never over the three characters that say who issued the document. A zone whose digits all pass has not proved it came from South Africa – the visual zone and the document's own security features do that.

Paste an MRZ into the MRZ parser to validate its check digits, or build one with the MRZ generator.

Fields you get back

Every recognised South African passport returns the same structured fields. A value that could not be read is null, never a missing key.

• Surname and given names
• Date of birth and sex
• Document number and personal number
• Nationality and issuing state (ZAF)
• Issue and expiry dates, days remaining
• The MRZ verdict, and the lines it was read from

See every field in the document field explorer.

Make the call

Run this against the public sandbox – no registration, real recognition, free for a limited number of documents and 10 requests per hour per IP. Swap the sandbox key for your own live key to keep recognising South African passports.

curl -X POST https://api.doc.cheap/v1/scans \
  -H "Authorization: Bearer sk_sandbox_public" \
  -H "Content-Type: application/json" \
  -d "{\"image\": \"$(base64 < document.jpg | tr -d '\n')\"}"

Where this is documented

This page covers what is specific to South Africa. The four pages below carry everything that is not.

• Recognize a passport

  The call above with a real document, in curl, JavaScript and Python, and every key of the answer read out.

• The MRZ and the visual zone

  Why a document prints the same facts twice, which zone to believe when they disagree, and what the check digits above can and cannot prove.

• Field languages and scripts

  The zone is Latin transliteration; the visual zone is not. Which reading carries the original script, and how a language identifier resolves to a language.

• Errors

  Every error code the API can answer with, in one table: what causes it, whether a retry can succeed, and whether the call was billed.