Check Document Number & MRZ & Identity API Documentation

This API provides comprehensive tools for verifying identification documents, parsing Machine Readable Zones (MRZ), and validating Polish national identification numbers (PESEL, NIP, REGON).

🛡️ Authentication

The API supports two methods of authentication. Include one of the following in your request headers:

• RapidAPI Key: X-Rapid-Secret: <your_key>
• Bearer Token: Authorization: Bearer <your_jwt_token>

📂 1. General Document Verification

Verify the checksum and format of international identity documents like ID Cards, Passports, and Driving Licenses.

POST /document/check

Validates a single 9-character document number.

Request Body:

JSON

{
  "documentNumber": "AL4080267"
}

Response (200 OK):

JSON

{
  "documentNumber": "AL4080267",
  "isValid": true,
  "checkDigit": 7,
  "checkSum": 254
}

POST /documents/check-multiple

Process a list of document numbers in a single request.

✈️ 2. MRZ (Machine Readable Zone) Parser

Validate and extract data from the MRZ found on passports and identity cards. Supports TD1, TD2, TD3, MRVA, and MRVB standards.

POST /mrz/check

Parses raw MRZ text or an array of lines.

Request Example (TD3 Passport):

JSON

{
  "rawMrzText": "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\nL898902C36UTO7408122F1204159ZE184226B<<<<<<10"
}

Detailed Response:

• Identity Info: Names, Surname, Gender, Birth Date.
• Document Info: Type (Passport/ID), Issuer Country, Expiry Date.
• Validation: Individual check digits for Doc Number, Expiry, and Birth Date.

🇵🇱 3. Polish Identity Validators

Specific endpoints for validating Polish national identifiers using local checksum algorithms (Modulo 10 and 11).

POST /polish-id/check-pesel

Validates the PESEL (Universal Electronic System for Registration of the Population).

Request:

JSON

{ "value": "02231404396" }

POST /polish-id/check-nip

Validates the NIP (Tax Identification Number). Supports formats with or without dashes.

Request:

JSON

{ "value": "123-456-78-19" }

POST /polish-id/check-regon

Validates the REGON (National Business Registry Number). Supports both 9-digit (entities) and 14-digit (local branches) formats.

POST /polish-id/identify

A “smart” endpoint that checks the input against all Polish validators and identifies the ID type.

🧩 Data Models

MrzCheckResponse

🚫 Error Handling

The API uses standard HTTP status codes:

• 400 Bad Request: Input does not match the required pattern (e.g., wrong length).
• 401 Unauthorized: Missing or invalid credentials.
• 500 Internal Server Error: Unexpected server-side failure.

Note: For all MRZ fields, the character < is treated as a filler (space) and is automatically handled by the parser.

Why Choose Our API?

In an era of increasing data privacy regulations and security threats, choosing the right tool for identity verification is critical. Our API is designed with a Privacy-First and Security-By-Design approach.

🛡️ Top-Tier Security & Data Privacy

1. Encrypted Data Transmission (HTTPS) All requests to our API are mandatory over SSL/TLS encrypted channels. This ensures that sensitive information, such as PESEL or Passport numbers, is protected from “man-in-the-middle” attacks and remains confidential between your application and our servers.
2. No Data Retention Policy (Stateless Processing) We believe in the principle of data minimization. The operator does not collect, store, or log any personal data sent to the API endpoints. Once the validation is performed and the result is returned to you, the data is immediately purged from the server’s volatile memory. We provide the logic; you keep the data.
3. Secure POST Method for All Identifiers Unlike many services that accept parameters in the URL (GET), we strictly use the POST method for all identity-related endpoints. This prevents sensitive numbers (like PESEL or NIP) from appearing in browser history, web server access logs, or proxy caches.
4. GDPR Compliant - European Infrastructure All processing takes place on high-performance servers located exclusively within the European Union. This ensures full compliance with the General Data Protection Regulation (GDPR/RODO) and provides the highest standards of legal protection for your users’ data.

🚀 Key Benefits for Your Business

• Trust: Build user confidence by using a service that respects privacy and follows international security standards.
• Compliance: Simplify your audit process by using a stateless API that doesn’t add to your data storage footprint.
• Speed & Accuracy: Instant verification of MRZ, PESEL, NIP, and REGON using official mathematical algorithms, reducing manual entry errors.

Code Examples

1. C# (using HttpClient)

Standard modern implementation using System.Text.Json for .NET 6+.

C#

using System.Text;
using System.Text.Json;

// Initialize the HTTP client
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Rapid-Secret", "YOUR_API_KEY");

// EXAMPLE 1: Polish PESEL Validation
// Sending a national identification number for checksum verification
var peselRequest = new { value = "02231404396" };
var peselContent = new StringContent(JsonSerializer.Serialize(peselRequest), Encoding.UTF8, "application/json");

var peselResponse = await client.PostAsync("https://api.your-domain.com/polish-id/check-pesel", peselContent);
string peselResult = await peselResponse.Content.ReadAsStringAsync();
Console.WriteLine($"PESEL Check Result: {peselResult}");

// EXAMPLE 2: MRZ (Machine Readable Zone) Parsing
// Validating a TD3 Passport format (2 lines of 44 characters)
var mrzRequest = new { 
    rawMrzText = "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\nL898902C36UTO7408122F1204159ZE184226B<<<<<<10" 
};
var mrzContent = new StringContent(JsonSerializer.Serialize(mrzRequest), Encoding.UTF8, "application/json");

var mrzResponse = await client.PostAsync("https://api.your-domain.com/mrz/check", mrzContent);
Console.WriteLine($"MRZ Data Extracted: {await mrzResponse.Content.ReadAsStringAsync()}");

2. Python (using requests)

Clean and readable implementation using the popular requests library.

Python

import requests
import json

# API Configuration
base_url = "https://api.your-domain.com"
headers = {
    "X-Rapid-Secret": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# SCENARIO 1: Tax Identification Number (NIP) validation
# The API handles numbers with or without dashes automatically
nip_payload = {"value": "123-456-78-19"}
nip_resp = requests.post(f"{base_url}/polish-id/check-nip", json=nip_payload, headers=headers)
print(f"NIP Validation Result: {nip_resp.json()}")

# SCENARIO 2: Bulk MRZ Processing
# Validating multiple MRZ codes in a single request for better performance
bulk_mrz_payload = [
    {"rawMrzText": "I<UTOD231458907<<<<<<<<<<<<<<<\\n7408122F1204159UTO<<<<<<<<<<<6"},
    {"rawMrzText": "IDROUERIKSSON<<ANNA<MARIA<<<<<<<<<<<\\n6543210987ROU6908061F2406236<<<<<<<5"}
]
bulk_resp = requests.post(f"{base_url}/mrz/check-multiple", json=bulk_mrz_payload, headers=headers)
print("Bulk MRZ Results:", json.dumps(bulk_resp.json(), indent=2))

3. JavaScript (fetch / Node.js)

Universal implementation using the fetch API, compatible with browsers and Node.js.

JavaScript

const API_CONFIG = {
    baseUrl: "https://api.your-domain.com",
    headers: {
        "X-Rapid-Secret": "YOUR_API_KEY",
        "Content-Type": "application/json"
    }
};

/**
 * Validates a business entity registration number (REGON)
 * @param {string} regonValue - 9 or 14 digit identification number
 */
async function validateRegon(regonValue) {
    try {
        const response = await fetch(`${API_CONFIG.baseUrl}/polish-id/check-regon`, {
            method: 'POST',
            headers: API_CONFIG.headers,
            body: JSON.stringify({ value: regonValue })
        });
        
        const data = await response.json();
        console.log(`Is REGON ${regonValue} valid?`, data.isValid);
    } catch (error) {
        console.error("API Connection Error:", error);
    }
}

/**
 * Identifies the type of Polish identity number (NIP vs PESEL vs REGON)
 * Useful when the input source is unknown.
 */
async function identifyNumberType(inputString) {
    const response = await fetch(`${API_CONFIG.baseUrl}/polish-id/identify`, {
        method: 'POST',
        headers: API_CONFIG.headers,
        body: JSON.stringify({ value: inputString })
    });
    
    const result = await response.json();
    console.log("Identification Details:", result);
}

// Execution
validateRegon("12345678512347"); // 14-digit local branch REGON
identifyNumberType("7740001454");   // Will identify as NIP