Detect

Endpoint Overview

POST /api/v1/ocr/document-detect

Description

The Document Detect API automatically identifies and classifies document types from uploaded images. This endpoint analyzes the visual characteristics of a document image and determines its type (such as Aadhaar card, PAN card, passport, etc.) without requiring manual specification. The service employs advanced computer vision and machine learning algorithms to accurately detect document types, enabling automated document processing workflows.

Key Benefits

Eliminates manual document type selection, reducing user friction and errors

Supports multiple Indian identity documents with high accuracy detection

Streamlines document verification workflows with automatic classification

Reduces development effort by handling document type detection automatically

Use Cases

Financial Services

Insurance

HR & Employment

Streamline customer onboarding by automatically detecting and processing KYC documents

Simplify loan application processes with automatic document classification

Enhance account opening workflows with intelligent document recognition

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 TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

1. For File Upload

Parameter	Type	Description
file	Image	Upload Cheque Image
use_pdf	Boolean	If the file type is PDF, set this to true

2. For Base64 Input

Parameter	Type	Description
base_64	String	Cheque Image in Base64 format

3. For Image URL Input

Parameter	Type	Description
link	String	Cheque Image Link/URL

Example Request

{
  "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/..."
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the main response data
data.documents	Array	Array of Document objects
status_code	Integer	HTTP status code indicating the result
message_code	String	Code representing the result status
message	String	Additional message, if any
success	Boolean	Indicates whether the request was successful

Documents(Object)

Parameter	Type	Description
type	String	Type of the document identified
score	Float	Confidence score for classification

Example Successful Response

{
  "data": {
    "documents": [
      {
        "type": "aadhaar_front_bottom",
        "score": 0.9931775331497192
      }
    ]
  },
  "status_code": 200,
  "message_code": "success",
  "message": null,
  "success": true
}

Possible Error Responses

Authentication Error

Invalid Image

Invalid File Format

Server Error

{
    "error": null,
    "message": "Your token is invalid. Please ensure that correct token is being used.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

Occurs when the JWT token is missing, invalid, or expired.

Integration Best Practices

Security Recommendations

Ensure all API communications use HTTPS to protect data in transit

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration gracefully

Apply proper input validation before sending images to the API

User Experience Guidelines

Implement a loading indicator while document detection is in progress

Provide clear feedback to users when document detection fails

Allow users to manually select document type as a fallback option

Optimize image capture to ensure good quality images for better detection accuracy

Code Samples

cURL

Python

Node.js

Related APIs

OCR Document Extract - Extracts information from detected documents

OCR Document Verify - Verifies the authenticity of detected documents

Face Match - Compares face on document with a selfie for identity verification

Compliance and Legal Considerations

When implementing document detection for KYC purposes, ensure compliance with relevant regulations such as PMLA (Prevention of Money Laundering Act) and RBI guidelines for digital KYC. Document detection should be part of a comprehensive KYC process that meets regulatory requirements for customer identification and verification.

{ "data": { "documents": [ { "type": "aadhaar_front_bottom", "score": 0.9931775331497192 } ] }, "status_code": 200, "message_code": "success", "message": null, "success": true }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Detect

Detect#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

1. For File Upload#

2. For Base64 Input#

3. For Image URL Input#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Detect

Description

Use Cases

Technical Implementation

Request Headers

Request Body

1. For File Upload

2. For Base64 Input

3. For Image URL Input

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples