Scan Passports and ID Cards with the DOCSCAN API

Before You Start

1. 1A PixLab API key from the 7-day free trial in the PixLab Console.
2. 2Python 3 with the requests package, or Node.js 18 or newer.
3. 3A clear PNG, JPEG, or BMP image of a supported document that you are authorized to process.
4. 4The DOCSCAN API reference for the complete parameter list and supported-document directory.

How a DOCSCAN Request Works

DOCSCAN uses one endpoint for document scanning and field extraction:

https://api.pixlab.io/docscan

If the document type is not known, DOCSCAN supports type=unknown on Team and Enterprise plans. Automatic unknown-country inference is also plan-dependent, so provide the type and country when your application already knows them.

Step 1

Start the Trial and Create an API Key

Start the 7-day free trial and create an API key in the PixLab Console, then store the key in an environment variable instead of writing it directly into application code.

PowerShell

$env:PIXLAB_API_KEY="YOUR_API_KEY"

Bash or Zsh

export PIXLAB_API_KEY="YOUR_API_KEY"

Keep DOCSCAN calls on your backend. Do not expose a private API key in browser JavaScript, a public mobile bundle, or a client-side repository.

Step 2

Prepare a Readable Document Image

Input quality affects the fields DOCSCAN can extract. Before sending an image:

• Keep the document edges visible where possible.
• Avoid motion blur, glare, heavy compression, and deep shadows.
• Use a resolution that keeps printed text and MRZ characters readable.
• Correct severe perspective distortion before scanning.
• Send the correct type and country when your workflow knows them.

DOCSCAN handles common orientation and rotation issues, but a sharp, evenly lit image remains the best input.

Step 3

Scan a Public Passport Image with Python

Use GET when the source image is available at a public URL. This example scans the PixLab passport specimen and disables face cropping because it only needs document fields.

Install the dependency:

python -m pip install requests

Create scan_passport_url.py:

import os
import requests

endpoint = "https://api.pixlab.io/docscan"

params = {
    "img": "https://pixlab.io/id-scan-api/passport_sample.png",
    "type": "passport",
    "facecrop": "false",
    "key": os.environ["PIXLAB_API_KEY"],
}

response = requests.get(endpoint, params=params, timeout=30)
reply = response.json()

if reply.get("status") != 200:
    raise RuntimeError(reply.get("error", "DOCSCAN request failed"))

fields = reply.get("fields", {})

print("Document type:", reply.get("type"))
print("Full name:", fields.get("fullName"))
print("Document number:", fields.get("documentNumber"))
print("Issuing country:", fields.get("issuingCountry"))
print("Date of birth:", fields.get("dateOfBirth"))
print("Expiry date:", fields.get("dateOfExpiry"))

Run the script:

python scan_passport_url.py

Use .get() when reading response fields. Not every document contains every field, and the available values vary by document type and issuing country.

Step 4

Upload a Local Passport or ID Image with Python

For private local files, use a multipart/form-data POST request. The image goes in the file field, while the API key and document settings are sent as form data.

import os
import requests

endpoint = "https://api.pixlab.io/docscan"
image_path = "./passport.jpg"

with open(image_path, "rb") as image_file:
    response = requests.post(
        endpoint,
        files={
            "file": ("passport.jpg", image_file, "image/jpeg"),
        },
        data={
            "key": os.environ["PIXLAB_API_KEY"],
            "type": "passport",
            "facecrop": "false",
        },
        timeout=30,
    )

reply = response.json()

if reply.get("status") != 200:
    raise RuntimeError(reply.get("error", "DOCSCAN request failed"))

fields = reply.get("fields", {})
print("Scanned document:", reply.get("type"))
print("Available fields:", sorted(fields.keys()))

For a national ID card or driver's license, change type and include the issuing country when required:

data={
    "key": os.environ["PIXLAB_API_KEY"],
    "type": "idcard",
    "country": "France",
    "facecrop": "false",
}

Use the country value documented in the supported ID documents and countries list.

See the DOCSCAN HTTP parameters for current request options.

Step 5

Upload an ID Document with Server-Side JavaScript

The same direct-upload flow works with the built-in fetch, FormData, and Blob APIs in Node.js 18 or newer. Create scan-id-document.mjs:

import { readFile } from "node:fs/promises";

const endpoint = "https://api.pixlab.io/docscan";
const apiKey = process.env.PIXLAB_API_KEY;

if (!apiKey) {
  throw new Error("PIXLAB_API_KEY is not set");
}

const image = await readFile("./passport.jpg");
const form = new FormData();

form.append("file", new Blob([image], { type: "image/jpeg" }), "passport.jpg");
form.append("key", apiKey);
form.append("type", "passport");
form.append("facecrop", "false");

const response = await fetch(endpoint, {
  method: "POST",
  body: form,
});

const reply = await response.json();

if (reply.status !== 200) {
  throw new Error(reply.error || "DOCSCAN request failed");
}

const fields = reply.fields || {};

console.log({
  type: reply.type,
  fullName: fields.fullName,
  documentNumber: fields.documentNumber,
  issuingCountry: fields.issuingCountry,
  dateOfExpiry: fields.dateOfExpiry,
});

Run it from a terminal where PIXLAB_API_KEY is already defined:

node scan-id-document.mjs

Step 6

Read the Structured JSON Response

A successful DOCSCAN request returns JSON. The exact fields depend on the document, but a passport response can follow this structure:

{
  "status": 200,
  "type": "passport",
  "face_url": false,
  "mrz_raw_text": "P<UTO...",
  "fields": {
    "fullName": "SPECIMEN HOLDER",
    "issuingCountry": "UTO",
    "documentNumber": "SAMPLE123",
    "dateOfBirth": "1990-01-01",
    "dateOfExpiry": "2030-01-01",
    "nationality": "UTO"
  }
}

Important response properties

• status: 200 indicates success. Other values indicate an error.
• type: The scanned document type.
• fields: Available normalized values extracted from the document.
• mrz_raw_text: Raw MRZ text for supported passports and visas.
• face_url: false, a Base64-encoded PNG, or a URL in your connected AWS S3 bucket, depending on face-crop configuration.
• error: Error information when status is not 200.

Do not assume every key will be present. Build around the fields required for your workflow, validate them, and provide a review path when important data is missing or unclear.

Supported Document Types

DOCSCAN supports more than 11,000 MRZ and non-MRZ document types from over 200 countries and territories. Common type values include:

Check the supported ID documents and countries directory before deployment because required values and coverage can vary by document type and country.

Optional Face-Crop Output

Face extraction is optional. Choose the output that fits your application:

• Set facecrop=false when you do not need a face crop.
• Set faceblob=true to receive a transient Base64-encoded PNG in the response.
• Connect your own AWS S3 bucket through the PixLab Console when you need a persistent URL. The extracted image is written directly to your bucket.

PixLab does not provide persistent PixLab-hosted storage for face crops. Your application controls persistent storage through its own connected S3 bucket.

Privacy and Document Retention

Scan an ID Document from a PDF

DOCSCAN accepts images rather than complete PDF files. For an ID document supplied as a PDF:

1. 1Convert the required page to an image with the PixLab PDFTOIMG endpoint.
2. 2Submit the generated image URL with a DOCSCAN GET request, or upload the converted image with POST.
3. 3Process the returned JSON in the same way as any other DOCSCAN response.

Convert only the pages required by your workflow and avoid retaining intermediate images longer than necessary.

Production Integration Checklist

• Keep the API key in a server-side secret store or environment variable.
• Use HTTPS for every request.
• Validate the top-level status field before reading data.
• Treat document fields as optional unless your application confirms they are present.
• Set request timeouts and separate network failures from API errors.
• Retry only temporary failures with bounded exponential backoff.
• Review important fields when image quality is poor or required data is missing.
• Do not log document images, MRZ text, face crops, or personal fields.
• Use queues and workers for large batches while respecting account limits.
• Test every document type and issuing country your application supports.

Troubleshooting Common DOCSCAN Requests