License Upload

Endpoint Overview

POST /api/v1/ocr/license

Description

This API endpoint enables optical character recognition (OCR) for driver's license documents. It extracts key information from license images, including license number and date of birth, with confidence scores for each extracted field. This service helps businesses automate identity verification processes by eliminating manual data entry and reducing human error.

Key Benefits

Automated extraction of license data with confidence scores for verification reliability

Reduces manual data entry errors and processing time by up to 90%

Enhances KYC/AML compliance workflows with accurate document data extraction

Seamlessly integrates into existing onboarding and verification systems

Use Cases

Financial Services

Transportation & Mobility

Government & Public Sector

Customer onboarding for banking and financial institutions requiring identity verification

Loan application processing with automated document verification

Account opening workflows with streamlined KYC procedures

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	Bearer token authentication using JWT format: `Bearer <your_token>`
Content-Type	Yes	Must be set to `multipart/form-data` for file upload

Request Body

1. For File Upload

Parameter	Type	Required	Description
front	File (Image)	Yes	Upload front image of license
back	File (Image)	Yes	Upload back image of license

2. For Base64 Input

Parameter	Type	Required	Description
front_base64	String	Yes	Front image of license in Base64 format
back_base64	String	Yes	Back image of license in Base64 format

3. For Image URL Input

Parameter	Type	Required	Description
front_link	String	Yes	URL for front image of license
back_link	String	Yes	URL for back image of license

Example Request

# Using multipart/form-data

Content-Disposition: form-data; name="front"; filename="front.jpg"
Content-Type: image/jpeg

--boundary

Content-Disposition: form-data; name="back"; filename="back.jpg"
Content-Type: image/jpeg

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the extracted license information
data.document_type	String/null	Type of the document identified (null if not determined)
data.license_number	Object	Contains the extracted license number information
data.license_number.value	String	The extracted license number
data.license_number.confidence	Integer	Confidence score (0-100) for the extracted license number
data.dob	Object	Contains the extracted date of birth information
data.dob.value	String	The extracted date of birth in YYYY-MM-DD format
data.dob.confidence	Integer	Confidence score (0-100) for the extracted date of birth
data.image_url	String/null	URL to the processed image (if available)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API call was successful
message	String/null	Additional information about the response (null if no message)
message_code	String	Code indicating the status of the operation

Example Successful Response

{
    "data": {
        "document_type": null,
        "license_number": {
            "value": "ANO1 20131234567",
            "confidence": 83
        },
        "dob": {
            "value": "1990-01-01",
            "confidence": 84
        },
        "image_url": null
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

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

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

Implement token rotation and expiration policies to minimize security risks

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information in error messages

User Experience Guidelines

Provide clear instructions to users about acceptable image quality and formats

Implement a preview feature to allow users to verify the image is clear before submission

Display a loading indicator during OCR processing to inform users of ongoing operations

Implement fallback manual entry options in case OCR fails to extract information accurately

Code Samples

cURL

Python

Node.js

Related APIs

OCR PAN Card: Extracts information from PAN card documents

OCR Aadhaar Card: Extracts information from Aadhaar card documents

OCR Passport: Extracts information from passport documents

Face Match: Compares face in ID document with a selfie for verification

Compliance and Legal Considerations

When implementing this API, ensure compliance with data protection regulations such as GDPR, CCPA, or local data privacy laws. Always obtain explicit user consent before processing personal identification documents and maintain proper data retention policies. Document the purpose of data collection and processing as required by applicable regulations.

{ "data": { "document_type": null, "license_number": { "value": "ANO1 20131234567", "confidence": 83 }, "dob": { "value": "1990-01-01", "confidence": 84 }, "image_url": null }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

License Upload

License Upload#

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

License Upload

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