API Documentation

Introduction

The Extract Passport Data API lets you extract data from passports of any country programmatically. It uses artificial intelligence to process the images, extract every field on the data page, and validate the MRZ with the ICAO 9303 check digits.

Authentication

Every API request must be authenticated with an API key. Include your API key in the X-API-Key header of each request.

curl https://extractpassportdata.com/api/v1/balance \
  -H "X-API-Key: pass_your_api_key"

You can create and manage your API keys from the dashboard.

Upload Methods

The API supports several ways to send images. The method is detected automatically from the Content-Type header.

Endpoints

curl -X POST https://extractpassportdata.com/api/v1/extract \
  -H "X-API-Key: pass_your_api_key" \
  -F "image_front=@./passport.jpg" \
  -F "image_back=@./passport_extra.jpg"

IMAGE_FRONT=$(base64 < ./passport.jpg | tr -d '\n')

printf '{"image_front": "%s"}' "$IMAGE_FRONT" | curl -X POST https://extractpassportdata.com/api/v1/extract \
  -H "X-API-Key: pass_your_api_key" \
  -H "Content-Type: application/json" \
  --data-binary @-

curl -X POST https://extractpassportdata.com/api/v1/extract \
  -H "X-API-Key: pass_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_front_url": "https://storage.example.com/passport.jpg",
    "image_back_url": "https://storage.example.com/passport_extra.jpg"
  }'

curl -X POST https://extractpassportdata.com/api/v1/extract \
  -H "X-API-Key: pass_your_api_key" \
  -H "Content-Type: image/jpeg" \
  --data-binary @./passport.jpg

{
  "success": true,
  "extraction_id": "clx1234567890",
  "data": {
    "passportNumber": "G12345678",
    "surname": "GOMEZ VELAZQUEZ",
    "givenNames": "MARGARITA",
    "nationality": "MEXICANA",
    "dateOfBirth": "05/07/1980",
    "sex": "F",
    "placeOfBirth": "COAHUILA",
    "dateOfIssue": "05/07/2023",
    "dateOfExpiry": "05/07/2033",
    "issuingCountry": "MEX",
    "issuingAuthority": "SRE",
    "personalNumber": "GOVM800705MCLRLR01",
    "mrzLine1": "P<MEXGOMEZ<VELAZQUEZ<<MARGARITA<<<<<<<<<<<<<",
    "mrzLine2": "G123456786MEX8007050F3307054<<<<<<<<<<<<<<08"
  },
  "tokens_remaining": 19,
  "upload_method": "multipart"
}

curl -X POST https://extractpassportdata.com/api/v1/extract \
  -H "X-API-Key: pass_your_api_key" \
  -H "X-Destination-Id: <your destination id>" \
  -F "image_front=@./passport.jpg"

{
  "success": true,
  "extraction_id": "...",
  "data": { ... },
  "delivery": {
    "destination_id": "...",
    "succeeded": true,
    "http_status": 200,
    "latency_ms": 312,
    "error_code": null
  }
}

curl https://extractpassportdata.com/api/v1/balance \
  -H "X-API-Key: pass_your_api_key"

{
  "success": true,
  "balance": 20
}

Capture links and webhooks

Send your customer a single-use link: they photograph their document on their phone and the data lands in your destination (webhook, email or Telegram), without the image passing through your system. Available to every account (beta). Destinations are set up in the dashboard, under Destinations.

curl -X POST https://extractpassportdata.com/api/v1/capture-links \
  -H "X-API-Key: pass_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationId": "<id de tu destino>",
    "documentType": "passport",
    "reference": "reserva-8841",
    "requireBack": true
  }'

{
  "success": true,
  "id": "clx_enlace_456",
  "url": "https://extractpassportdata.com/c/…",
  "reference": "reserva-8841",
  "documentType": "passport",
  "requireBack": true,
  "askGuestPersona": false,
  "expiresAt": "2026-09-30T18:15:00.000Z"
}

Webhooks: what your server receives

Every delivery to a webhook destination, whether from a capture link, from /api/v1/extract with X-Destination-Id or from the dashboard, is a signed POST. It is attempted once, follows no redirects and waits 10 seconds; answer 2xx.

POST /tu-webhook
Content-Type: application/json
X-Signature: sha256=5f2b…
X-Signature-Timestamp: 1790000000
X-Idempotency-Key: clx1234567890

{
  "version": "1",
  "event": "extraction.completed",
  "idempotencyKey": "clx1234567890",
  "documentType": "passport",
  "source": "capture-link",
  "captureLinkId": "clx_enlace_456",
  "reference": "reserva-8841",
  "extractedAt": "2026-09-30T18:05:02.000Z",
  "data": { "curp": "…", "nombre": "…" }
}

source is api, web or capture-link. image (front/back in base64) is only present if the destination has image delivery on. Use X-Idempotency-Key to drop duplicates.

Signature: X-Signature is sha256= plus the hex HMAC-SHA256, keyed with the destination secret (whsec_…), of X-Signature-Timestamp + "." + the raw body. Verify over the bytes received (not re-serialized JSON), compare in constant time and reject timestamps older than 5 minutes. The official SDKs do this for you.

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(secret, rawBody, signature, timestamp) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signature ?? '')
  return a.length === b.length && timingSafeEqual(a, b)
}

Error codes

Extracted fields

The API extracts the following fields from the passport data page: