PAN Card Masking

Endpoint Overview

POST /api/v1/ocr/pan-masking

Description

The PAN Card Masking API automatically detects and masks the Permanent Account Number (PAN) on Indian PAN cards. It accepts the document in three flexible input formats — a binary file upload, a base64-encoded string, or a publicly accessible URL — and returns a pre-signed S3 URL pointing to the masked version, ensuring sensitive financial identity information is redacted before storage, sharing, or display.

This API is particularly valuable in workflows where PAN card documents are collected for KYC (Know Your Customer) verification, but downstream systems, agents, or storage layers should not have access to the raw PAN number. The masking is performed server-side and the result is stored securely on AWS S3, accessible via a time-limited signed URL.

Key Benefits

Privacy by Design: Automatically redacts PAN numbers before any downstream processing, reducing data exposure risk.

Flexible Input Formats: Accepts the PAN card document as a binary file upload, a base64-encoded string, or a publicly accessible URL — integrate using whichever method fits your existing pipeline.

PDF & Image Support: Handles both standard image formats and multi-page PDF documents via the use_pdf flag.

Instant S3 Delivery: The masked output is uploaded directly to secure AWS S3 storage and returned as a pre-signed URL — no manual file handling required.

Simple Integration: Minimal request parameters and a consistent response structure make this easy to drop into existing KYC or document-processing pipelines.

Use Cases

Financial Services

HR & Payroll

Healthcare & Insurance

Mask PAN numbers on scanned documents before storing in loan origination systems to limit PII exposure to downstream teams.

Redact PAN details from KYC document images before sharing with third-party underwriters or compliance reviewers.

Sanitize PAN cards uploaded via customer portals prior to archiving in document management systems.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer <YOUR_JWT_TOKEN>.

Different authentication tokens are used for sandbox and production environments:

Sandbox Base URL: https://sandbox.surepass.app

Production Base URL: https://kyc-api.surepass.app

⚠️ Important: Never share or expose your JWT token in client-side code or public repositories. Use environment variables to manage tokens securely.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication. Format: `Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	Conditional	Must be `multipart/form-data` when sending a binary file upload. For base64 or link inputs, use `application/json`.

Request Body

Exactly one of file, base64, or url must be provided per request. These are mutually exclusive input methods.

Parameter	Type	Required	Description
`file`	File (binary)	One of `file` / `base64` / `url`	The PAN card image or PDF file to be masked. Send as `multipart/form-data` with content type `application/octet-stream`.
`base64`	String	One of `file` / `base64` / `url`	Base64-encoded string of the PAN card image or PDF. Send as a JSON body field.
`link`	String	One of `file` / `base64` / `link`	Publicly accessible URL pointing to the PAN card image or PDF. Send as a JSON body field.
`use_pdf`	String	Conditional	Set to `"true"` when the input document (via any method) is a PDF. Omit for image inputs.

Example Request (File Upload)

Example Request (Base64 Input)

POST /api/v1/ocr/pan-masking
Authorization: Bearer <YOUR_JWT_TOKEN>
Content-Type: application/json

{
    "base64": "<BASE64_ENCODED_IMAGE_OR_PDF_STRING>",
    "use_pdf": "true"
}

Example Request (Link Input)

POST /api/v1/ocr/pan-masking
Authorization: Bearer <YOUR_JWT_TOKEN>
Content-Type: application/json

{
    "link": "https://example.com/pan_card.jpg"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	Container object holding the result payload.
`data.client_id`	String	A unique identifier for this masking request, prefixed with `pan_masking_`. Used for tracking and support.
`data.masked_image`	String (URL)	A pre-signed AWS S3 URL pointing to the masked version of the uploaded document. This URL is time-limited.
`status_code`	Integer	HTTP-equivalent status code for the operation (e.g., `200` for success).
`success`	Boolean	`true` if the masking operation completed successfully; `false` otherwise.
`message`	String \| null	Human-readable message providing additional context. `null` on success.
`message_code`	String	Machine-readable status code. Value is `"success"` on successful completion.

Example Successful Response

{
    "data": {
        "client_id": "pan_masking_rcyHuMgNbdnzdJvvyDdL",
        "masked_image": "https://aadhaar-kyc-docs.s3.amazonaws.com/pan_masking_rcyHuMgNbdnzdJvvyDdL/masked_1777119672507.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260425%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=d77d480bc37a33a07d72cabpc8054d424d728605968ad05a3d2cc538ee45ac0c"
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

401 Unauthorized

400 Bad Request

422 Unprocessable Entity

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 the JWT token is invalid or expired. Ensure you are using the correct token for the target environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Store JWT tokens securely: Use server-side environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault). Never embed tokens in client-side code or version control.

Use environment-specific tokens: Maintain separate JWT tokens for sandbox and production environments to prevent accidental data exposure during testing.

Handle pre-signed URLs carefully: The masked_image URL is time-limited. Download and store the masked image in your own secure storage immediately after receiving the response — do not rely on the S3 URL for long-term access.

Validate file inputs before upload: Check file type, size, and basic readability on the client side before sending to the API to reduce unnecessary API calls and potential data leakage from malformed requests.

Use HTTPS exclusively: Always call the API over HTTPS. Never downgrade to HTTP, even for testing purposes.

User Experience Guidelines

Inform users about masking: Clearly communicate to end users that their PAN card will be masked before storage or sharing, building trust and demonstrating compliance.

Show a loading state during processing: Document masking may take a moment. Display a progress indicator or spinner to prevent users from resubmitting while the request is in-flight.

Provide clear upload instructions: Guide users to upload a clear, well-lit, flat scan or photo of their PAN card to maximize detection accuracy and reduce failure rates.

Handle errors gracefully: If a 422 Unprocessable Entity error is returned, prompt the user to re-upload a clearer image rather than showing a generic error — include actionable guidance.

Preview the masked output: Where possible, display the masked image to the user after processing so they can confirm the redaction was applied correctly before the document is submitted or stored.

Code Samples

cURL

Python

Node.js

Related APIs

PAN Card OCR – Extract structured data fields (name, PAN number, date of birth, etc.) from a PAN card image or PDF without masking.

Aadhaar Masking – Detect and mask the Aadhaar number on Aadhaar card documents, analogous to PAN masking for Aadhaar-based KYC flows.

Aadhaar OCR – Extract structured data from Aadhaar card documents for identity verification workflows.

Face Match – Compare a selfie or portrait image against the photo on a PAN or Aadhaar card to verify that the document belongs to the presenting individual.

Compliance and Legal Considerations

Handling PAN card data is subject to Indian data protection laws and RBI/SEBI KYC guidelines. Ensure that:

PAN data is collected only with the explicit, informed consent of the individual.

Masked outputs are stored in accordance with your organisation's data retention policy — avoid indefinite storage of even masked KYC documents.

The pre-signed S3 URLs returned by this API are time-limited; do not treat them as permanent storage links. Transfer masked documents to your own compliant storage immediately.

Access to raw (unmasked) PAN card data upstream of this API should be restricted to authorised personnel only, with full audit logging.

If operating under DPDP Act (Digital Personal Data Protection Act, 2023) obligations, classify PAN numbers as personal data and apply appropriate data processing agreements with Surepass as a data processor.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "pan_masking_rcyHuMgNbdnzdJvvyDdL", "masked_image": "https://aadhaar-kyc-docs.s3.amazonaws.com/pan_masking_rcyHuMgNbdnzdJvvyDdL/masked_1777119672507.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260425%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=d77d480bc37a33a07d72cabpc8054d424d728605968ad05a3d2cc538ee45ac0c" }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

PAN MASKING

PAN Card Masking#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request (File Upload)#

Example Request (Base64 Input)#

Example Request (Link Input)#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses