Getting Started

Introduction

The IDParse API is a data extraction API for identity documents. You upload a photo or a scan of a passport, an ID card or a visa. The API reads the MRZ (machine readable zone, the lines of letters, digits and < signs at the bottom of the document) and returns the data as JSON.

Key features:

One endpoint for extraction: one uploaded file is one scan.
Checksum-validated results. The check digits (control numbers that are printed inside the MRZ) protect the document number, the birth date and the expiry date. They detect many reading errors but do not guarantee that the extracted values are correct.
Fair billing. Only a validated success is charged. A document that could not be read is free of charge.
Privacy by design. Document content is not saved in application records or logs. See Privacy.
Clear limits. Response headers show your included scans and your usage.

Important

IDParse reads data from a document. It does not prove that a document is genuine, and it does not prove that the document belongs to the person who presents it. See Results and Billing.

Base URL

All API v1 requests use the following base URL:

text

https://api.idparse.com/v1/

Note

All requests must include a valid API key. See Authentication for details.

How to Get an API Key

Create a free account on IDParse.
Verify your email address.
Go to your Dashboard.
Navigate to API Keys.
Click Create New Key and give it a name.
Copy the key immediately. It is shown only once.

Important

Store your API key securely. Never expose it in client-side code, public repositories, or URLs.

Quick Start

Send one document file to the extract endpoint:

bash

curl -s -X POST "https://api.idparse.com/v1/extract" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@passport.jpg"

Response:

json

{
    "success": true,
    "documents": [
        {
            "success": true,
            "document_type": "TD3",
            "fields": {
                "surname": "ERIKSSON",
                "given_names": "ANNA MARIA",
                "birth_date": "1974-08-12",
                "sex": "F",
                "nationality": "UTO",
                "document_number": "L898902C3",
                "expiry_date": "2012-04-15",
                "issuing_country": "UTO"
            },
            "check_digits_valid": {
                "document_number": true,
                "birth_date": true,
                "expiry_date": true
            },
            "checksum_protected": {
                "surname": false,
                "given_names": false,
                "birth_date": true,
                "sex": false,
                "nationality": false,
                "document_number": true,
                "expiry_date": true,
                "issuing_country": false
            },
            "failure_reason": null,
            "notes": [
                "birth date century inferred",
                "expiry date century inferred"
            ],
            "page": 1,
            "region": { "x": 0.05, "y": 0.81, "width": 0.9, "height": 0.12 }
        }
    ],
    "document_count": 1,
    "verified_document_count": 1,
    "processing_complete": true,
    "truncation_reason": null,
    "failure_reason": null,
    "notes": ["engines tried: locator"],
    "duration_ms": 480,
    "service_version": "2.0.0"
}

The example shows the public ICAO specimen passport. It is not a real person.

Note

The answer of the extract endpoint is JSON without a data wrapper. It lists every document found in the file under documents. Always read the success field first, then success of each document. HTTP 200 is also returned when no document could be read. Errors return "success": false with an error object instead.

See the Endpoints, Results and Billing and Code Examples pages for more.