MENU navbar-image

Introduction

This documentation aims to provide all the information you need to work with our API.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>

Authenticating requests

This API is not authenticated.

Debug

Debug a barcode payload

Accepts the same base64-encoded barcode as /api/decode-licence and returns a detailed binary analysis: full hex dump, magic-byte locations, E0-delimited field slices, entropy windows, and a brute-force RSA key skip search. Intended for development and reverse-engineering use only.

Warning: Remove or protect this endpoint behind authentication before deploying to production.

How to prepare the barcode value — same as /api/decode-licence:

  1. Scan the PDF417 barcode on the back of the SA driver's licence.
  2. Take the raw binary bytes from the scanner output.
  3. Base64-encode those bytes (standard or URL-safe base64 accepted).
  4. Send the base64 string as the barcode field.
Example request:
curl --request POST \
    "http://localhost/api/debug-barcode" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"barcode\": \"`SGVsbG8gV29ybGQ=`\"
}"

const url = new URL(
    "http://localhost/api/debug-barcode"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "barcode": "`SGVsbG8gV29ybGQ=`"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200, Successful analysis):


{
    "total_bytes": 720,
    "magic_searches": {
        "WI\\x04 (SA DL WSQ header)": [
            456
        ],
        "FF D8 (JPEG SOI)": []
    },
    "e0_field_slices": [
        {
            "start": 0,
            "end": 11,
            "length": 12,
            "hex": "41424344...",
            "ascii": "ABCD....",
            "e0_at": 12,
            "after_e0_hex": "E00102"
        }
    ],
    "entropy_windows": [
        {
            "offset": 0,
            "entropy": 7.82
        }
    ],
    "brute_force_skip": [],
    "full_hex_dump": [
        "0000  41 42 43 44 ...  ABCD...."
    ]
}

Example response (200, Invalid base64):


{
    "error": "base64_decode failed"
}

Request      

POST api/debug-barcode

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

barcode   string     

Base64-encoded raw bytes of the PDF417 barcode. Same format as /api/decode-licence. Both standard (+/) and URL-safe (-_) base64 alphabets are accepted. Example: SGVsbG8gV29ybGQ=

Licence Decoding

Decode a SA driver's licence barcode

Decodes a South African driver's licence PDF417 barcode and returns all structured fields including identity, personal details, vehicle classes, and a base64-encoded photo.

How to prepare the barcode value:

  1. Scan the PDF417 barcode on the back of the SA driver's licence card.
  2. Obtain the raw binary bytes from the scanner (do not convert to hex or string).
  3. Base64-encode those raw bytes (standard or URL-safe base64 both accepted).
  4. Send the resulting base64 string as the barcode field.

The decoded byte length must be at least 720 bytes — this is the encrypted RSA payload size used on SA driver's licences.

Example request:
curl --request POST \
    "http://localhost/api/decode-licence" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"barcode\": \"`SGVsbG8gV29ybGQ=`\"
}"

const url = new URL(
    "http://localhost/api/decode-licence"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "barcode": "`SGVsbG8gV29ybGQ=`"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200, Successful decode):


{
    "status": "success",
    "result": {
        "identity_document": {
            "number": "8001015009087",
            "type": "ID",
            "country_of_issue": "ZA"
        },
        "person": {
            "surname": "SMITH",
            "initials": "JA",
            "driver_restrictions": "00",
            "date_of_birth": "1980/01/01",
            "gender": "M"
        },
        "driving_license": {
            "certificate_number": "DP-123456",
            "country_of_issue": "ZA"
        },
        "card": {
            "issue_number": "01",
            "date_valid_from": "2020/01/01",
            "date_valid_until": "2025/01/01"
        },
        "professional_driving_permit": null,
        "vehicle_classes": [
            {
                "code": "B",
                "vehicle_restrictions": "00",
                "first_issue_date": "2000/06/15"
            }
        ],
        "photo_base64": "data:image/png;base64,iVBORw0KGgo..."
    }
}

Example response (422, Invalid base64 or payload too short):


{
    "success": false,
    "error": "Invalid base64 barcode data (expected ≥720 decoded bytes)."
}

Example response (422, Decryption or parse failure):


{
    "success": false,
    "error": "RSA decryption failed: ..."
}

Request      

POST api/decode-licence

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

barcode   string     

Base64-encoded raw bytes of the PDF417 barcode scanned from the South African driver's licence card. The base64 string must decode to at least 720 bytes. Both standard (+/) and URL-safe (-_) base64 alphabets are accepted. Example: SGVsbG8gV29ybGQ=