API Documentation — MaskAadhaar

Overview

The MaskAadhaar API allows you to automatically detect and mask Aadhaar numbers in document images and PDFs. Designed for compliance teams, banks, NBFCs, and fintech companies that process Aadhaar documents at scale.

Base URL: https://api.maskaadhaar.com/api/v1
Protocol: HTTPS only
Authentication: API Key via X-API-Key header
Supported formats: PDF, JPEG, JPG, PNG
Max file size: 10 MB per request

Authentication

All API requests require an API key passed in the X-API-Key request header. Get your API key from the Pricing page after subscribing to a plan.

HTTP Header

X-API-Key: your_api_key_here

Keep your API key secret. Do not expose it in client-side code, public repositories, or logs. Rotate your key immediately if you suspect it has been compromised.

Quick Start

Make your first API call in under a minute. Send a multipart/form-data POST request with your document file.

cURL

curl -X POST https://api.maskaadhaar.com/api/v1/mask-aadhaar \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@/path/to/aadhaar.pdf" \
  --output masked_aadhaar.pdf

On success, the response body is the masked file (same format as input). Response headers include masking metadata.

POST /mask-aadhaar

POSThttps://api.maskaadhaar.com/api/v1/mask-aadhaar

Accepts a document (PDF, JPEG, or PNG) and returns the same document with all detected Aadhaar numbers masked. The first 8 digits of each 12-digit Aadhaar number are replaced with XXXX XXXX.

Request Parameters

Send as multipart/form-data.

Field	Type	Required	Description
`file`	File	Yes	The document to mask. Supported: PDF, JPEG, JPG, PNG. Max 10 MB.
`dpi`	Integer	No	DPI for PDF rasterisation (default: `200`, range: 72–300). Higher DPI improves accuracy for low-quality scans.
`scale`	Float	No	Scale factor for image processing (default: `2.0`, range: 1.0–3.0). Increase for small images.

Response

On success (200 OK), the response body is the masked file binary. Content-Type matches the input format.

Header	Description
`Content-Type`	`application/pdf`, `image/jpeg`, or `image/png`
`X-Masked-Count`	Number of Aadhaar numbers found and masked
`X-Quota-Used`	API calls used this billing period
`X-Quota-Remaining`	API calls remaining this billing period

Error Codes

HTTP Status	Code	Description
401	`INVALID_API_KEY`	API key is missing or invalid.
403	`PLAN_NOT_ACTIVE`	Your subscription is inactive or expired. Renew at /pricing.
422	`UNSUPPORTED_FILE_TYPE`	File format not supported. Use PDF, JPEG, or PNG.
422	`FILE_TOO_LARGE`	File exceeds 10 MB limit.
429	`QUOTA_EXCEEDED`	Monthly API call quota exhausted. Upgrade your plan.
500	`PROCESSING_ERROR`	Internal error during masking. Retry or contact support.

Error Response Body

JSON

{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly API quota exceeded. Upgrade your plan.",
  "quota_used": 100,
  "quota_limit": 100
}

API Plans

All plans include full API access. View full pricing →

Starter

₹999/month

For startups & small teams

100 API calls / month
Single file per request
PDF, JPEG, PNG support
Email support

Growth

₹2,999/month

For growing teams

1,000 API calls / month
Batch: up to 10 files
PDF, JPEG, PNG support
Priority support

Enterprise

Custom

For banks & NBFCs

Unlimited API calls
Batch: up to 100 files
SLA guarantee
Dedicated support

Rate Limits

In addition to monthly quotas, concurrent request rate limits apply per API key:

Plan	Monthly Quota	Max Concurrent	Batch Size
Starter	100 calls	5 req/sec	1 file
Growth	1,000 calls	20 req/sec	10 files
Enterprise	Unlimited	Custom	100 files

Requests exceeding rate limits return 429 Too Many Requests. Implement exponential back-off in your client.

Example: cURL

Shell

# Mask an Aadhaar PDF
curl -X POST https://api.maskaadhaar.com/api/v1/mask-aadhaar \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@aadhaar_front.jpg" \
  -D response_headers.txt \
  --output masked_aadhaar.jpg

# Check masking count from headers
grep X-Masked-Count response_headers.txt

Example: Python

Python

import requests

API_KEY = "your_api_key_here"
API_URL = "https://api.maskaadhaar.com/api/v1/mask-aadhaar"

def mask_aadhaar(file_path: str, output_path: str):
    with open(file_path, "rb") as f:
        response = requests.post(
            API_URL,
            headers={"X-API-Key": API_KEY},
            files={"file": f},
            timeout=30
        )

    response.raise_for_status()

    with open(output_path, "wb") as out:
        out.write(response.content)

    masked_count = response.headers.get("X-Masked-Count", "0")
    quota_remaining = response.headers.get("X-Quota-Remaining", "?")
    print(f"Masked {masked_count} Aadhaar numbers. Quota remaining: {quota_remaining}")

# Usage
mask_aadhaar("aadhaar.pdf", "masked_aadhaar.pdf")

Example: Node.js

JavaScript (Node.js)

const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

const API_KEY = 'your_api_key_here';
const API_URL = 'https://api.maskaadhaar.com/api/v1/mask-aadhaar';

async function maskAadhaar(inputPath, outputPath) {
  const form = new FormData();
  form.append('file', fs.createReadStream(inputPath));

  const response = await fetch(API_URL, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY, ...form.getHeaders() },
    body: form
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.message);
  }

  const buffer = await response.buffer();
  fs.writeFileSync(outputPath, buffer);

  console.log(`Masked: ${response.headers.get('X-Masked-Count')} numbers`);
  console.log(`Quota remaining: ${response.headers.get('X-Quota-Remaining')}`);
}

// Usage
maskAadhaar('aadhaar.pdf', 'masked_aadhaar.pdf')
  .catch(console.error);

MaskAadhaar API