Secure Document OCR

Endpoint Overview

POST /api/v1/ocr/secure-document-ocr

Description

The Secure Document OCR API enables automated extraction of key information from identity documents — currently supporting PAN cards and Aadhaar cards. By submitting a document image (including password-protected files), the API returns structured, confidence-scored field data such as name, date of birth, document number, and father's name.

This API is designed for organizations that need to verify customer identity as part of onboarding, KYC (Know Your Customer), or compliance workflows. It eliminates manual data entry, reduces human error, and accelerates identity verification pipelines — all while handling sensitive documents securely via authenticated, encrypted API calls.

Key Benefits

High-Confidence Extraction: Each returned field includes a confidence score, enabling downstream systems to flag low-confidence results for manual review.

Password-Protected Document Support: Accepts encrypted/password-protected files, ensuring compatibility with real-world document formats.

Structured Output: Returns clean, field-level JSON — no parsing of raw OCR text required.

Dual Environment Support: Separate sandbox and production base URLs make it safe to build and test integrations without touching live data.

Use Cases

Banking & Finance

Insurance

HR & Staffing

Automate KYC onboarding by extracting PAN and Aadhaar details during account opening

Pre-fill loan application forms with verified document data to reduce drop-offs

Cross-verify customer-submitted details against OCR-extracted values for fraud prevention

Enable instant digital account opening without branch visits or manual document checks

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer Token. Follow these steps to authenticate:

Obtain API Credentials: Register with Surepass to receive your API key for the appropriate environment.

Generate JWT Token: Use your API key to generate a JWT token as per Surepass's token generation process.

Include in Requests: Add the token to every request's Authorization header in the following format:

Authorization: Bearer <YOUR_JWT_TOKEN>

Use the correct base URL for your environment:

Environment	Base URL
Sandbox	`https://sandbox.surepass.app`
Production	`https://kyc-api.surepass.app`

⚠️ Important: JWT tokens are environment-specific. A sandbox token will not work against the production endpoint and vice versa.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication. Format: `Bearer <JWT_TOKEN>`
`Content-Type`	Yes	Must be `multipart/form-data` since the request includes a file upload

Request Body

The request must be sent as multipart/form-data with the following fields:

Parameter	Type	Required	Description
`image_type`	String	Yes	Type of identity document being submitted. Accepted values: `pan` or `aadhaar`
`password`	String	Yes	Password for the document file if it is password-protected. Leave empty if the file is not encrypted
`file`	File (binary)	Yes	The document image file to be processed. Send as `application/octet-stream`

Example Request

The file field must be uploaded as a multipart file part with application/octet-stream content type. See the Code Samples section below for language-specific implementations.

Process Response

Response Parameters

Parameter	Type	Description
`status_code`	Integer	HTTP status code of the response (e.g., `200` for success)
`success`	Boolean	`true` if the request was processed successfully, `false` otherwise
`message`	String / null	Human-readable message describing the result. `null` on success
`message_code`	String	Machine-readable status code. `"success"` on successful processing
`data`	Object	Root object containing the OCR result
`data.client_id`	String	A unique identifier for this OCR request, generated by the system
`data.image_type`	String	The document type that was processed, echoing the value sent in the request (`pan` or `aadhaar`)
`data.ocr_response`	Object	Container for the OCR output
`data.ocr_response.ocr_fields`	Array	Array of extracted field objects. Typically contains one object per submitted document
`ocr_fields[].document_type`	String	Document type identified during processing
`ocr_fields[].pan_number`	Object	Extracted PAN number (present for `pan` document type)
`ocr_fields[].pan_number.value`	String	The extracted PAN number value
`ocr_fields[].pan_number.confidence`	Integer	Confidence score (0–100) for the extracted PAN number
`ocr_fields[].full_name`	Object	Extracted full name of the document holder
`ocr_fields[].full_name.value`	String	The extracted full name value
`ocr_fields[].full_name.confidence`	Integer	Confidence score (0–100) for the extracted full name
`ocr_fields[].father_name`	Object	Extracted father's name of the document holder
`ocr_fields[].father_name.value`	String	The extracted father's name value
`ocr_fields[].father_name.confidence`	Integer	Confidence score (0–100) for the extracted father's name
`ocr_fields[].dob`	Object	Extracted date of birth
`ocr_fields[].dob.value`	String	The extracted date of birth in `DD/MM/YYYY` format
`ocr_fields[].dob.confidence`	Integer	Confidence score (0–100) for the extracted date of birth

Example Successful Response

{
    "data": {
        "client_id": "secure_document_ocr_wuFcsieHGuSgafhjhohv",
        "image_type": "pan",
        "ocr_response": {
            "ocr_fields": [
                {
                    "document_type": "pan",
                    "pan_number": {
                        "value": "ABCPD1234E",
                        "confidence": 99
                    },
                    "full_name": {
                        "value": "Ram Kumar",
                        "confidence": 98
                    },
                    "father_name": {
                        "value": "Rajendra Kumar Singh",
                        "confidence": 97
                    },
                    "dob": {
                        "value": "01/01/2001",
                        "confidence": 99
                    }
                }
            ]
        }
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

401 Unauthorized

400 Bad Request

500 Internal Server Error

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Authentication credentials were not provided or are invalid.",
    "message_code": "unauthorized"
}

Returned when the Authorization header is missing, malformed, or contains an expired/invalid JWT token. Ensure you are using the correct token for the target environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Never expose JWT tokens client-side: Always make API calls from your backend server. Embedding tokens in frontend code or mobile apps creates significant security risks.

Use environment-specific tokens: Maintain separate JWT tokens for sandbox and production environments. Do not reuse credentials across environments.

Rotate tokens regularly: Implement a token rotation policy and invalidate compromised tokens immediately through the Surepass dashboard.

Transmit over HTTPS only: All requests must be made over HTTPS. Never send identity document data over unencrypted connections.

Validate confidence scores: Before using extracted field values in automated decisions, enforce a minimum confidence threshold (e.g., ≥ 85) and route low-confidence results to manual review.

Sanitize file inputs: Validate file type, size, and format on your side before sending to the API to prevent unnecessary API calls and potential abuse.

User Experience Guidelines

Provide upload guidance: Instruct users to upload clear, well-lit, flat images of documents. Avoid shadows, glare, or cropped edges, as these reduce OCR accuracy and confidence scores.

Show real-time feedback: Display a progress indicator while the document is being processed. OCR calls may take a few seconds depending on file size.

Handle low-confidence gracefully: If any field returns a confidence score below your acceptable threshold, prompt the user to re-upload a clearer image rather than silently failing or passing incorrect data downstream.

Pre-fill and confirm: When using extracted data to populate forms, show users the pre-filled values for confirmation before submission to reduce errors from misread fields.

Communicate document type clearly: If your application supports both PAN and Aadhaar, guide users to select the correct document type before uploading to ensure the image_type parameter is set correctly.

Code Samples

cURL

Python

Node.js

Related APIs

ID Card OCR — Extract structured data from standard national identity cards beyond PAN and Aadhaar formats.

Aadhaar Verification API — Verify that an Aadhaar number is valid and active using UIDAI's official verification service.

PAN Verification API — Cross-check extracted PAN number data against the Income Tax Department database for identity validation.

Liveness Detection API — Complement document OCR with real-time face liveness checks to prevent spoofing during KYC.

Face Match API — Compare the photograph extracted from an identity document against a live selfie to confirm the document belongs to the presenting individual.

Compliance and Legal Considerations

Data Privacy: PAN cards and Aadhaar cards are classified as sensitive personal information under India's Digital Personal Data Protection Act, 2023 (DPDPA). You must obtain explicit, informed consent from individuals before collecting, processing, or storing their identity document data.

Aadhaar Regulations: The use of Aadhaar data is governed by the Aadhaar Act, 2016 and associated UIDAI regulations. Only entities authorized by UIDAI may perform Aadhaar-based identity verification. Ensure your organization has the appropriate authorizations before deploying Aadhaar OCR in a production context.

Data Retention: Do not store raw document images or extracted PII beyond what is necessary for your stated processing purpose. Implement data retention policies and purge schedules in compliance with applicable regulations.

Audit Trails: Maintain logs of all OCR API calls, including the client_id returned in each response, to support audit and compliance requirements. Ensure logs themselves are stored securely with restricted access.

Cross-Border Transfers: If your infrastructure involves transferring data outside India, ensure compliance with applicable cross-border data transfer provisions under the DPDPA before doing so.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://kyc-api.surepass.app/api/v1/ocr/secure-document-ocr' \ --header 'Authorization: Bearer <token>' \ --form 'file=@""' \ --form 'image_type="aadhaar"' \ --form 'password="123456"'

{ "data": { "client_id": "secure_document_ocr_wpXWyuMptqwyZlTripwr", "image_type": "aadhaar", "ocr_response": { "ocr_fields": [ { "document_type": "aadhaar_front_bottom", "full_name": { "value": "Rajiv Talwar", "confidence": 93 }, "gender": { "value": "M", "confidence": 91 }, "mother_name": { "value": "", "confidence": 0 }, "father_name": { "value": "", "confidence": 0 }, "dob": { "value": "1994-04-08", "confidence": 94, "yob": false }, "aadhaar_number": { "value": "123456789012", "confidence": 91, "is_masked": false, "input_validation": false }, "image_url": null, "uniqueness_id": "c038d592851976e720a6eed7e577074f131cbb208a7462b948c7aaccdc747b20" }, { "document_type": "aadhaar_back", "address": { "value": "S/O: Ram Talwar, Connaught Place, New Delhi, Delhi, India, 110001", "confidence": 91, "first_line": "", "second_line": "", "locality": "", "landmark": "", "house_number": "Connaught Place, New Delhi, Delhi, India", "district": "New Delhi", "city": "Connaught Place", "state": "Delhi", "country": "India", "zip": "110001" }, "zip": { "value": "110001", "confidence": 91 }, "care_of": { "value": "Ram Talwar", "confidence": 91, "relation": "father" }, "aadhaar_number": { "value": "123456789012", "confidence": 92, "is_masked": false, "input_validation": false }, "image_url": null } ] } }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses