Passport Upload

Endpoint Overview

POST /api/v1/passport/passport/{client_id}/upload

Description

This API endpoint allows you to upload a passport image for a specific client and extract key information from it. The service performs OCR (Optical Character Recognition) on the uploaded passport image, extracts relevant data fields, and returns a structured response containing passport details such as personal information, document numbers, validity dates, and MRZ (Machine Readable Zone) data.

Key Benefits

Automated extraction of passport data eliminates manual data entry and reduces human error

Validates passport authenticity through MRZ code verification

Accelerates customer onboarding processes with instant document verification

Ensures compliance with KYC (Know Your Customer) regulations

Use Cases

Financial Services

Travel & Hospitality

Government & Immigration

Customer onboarding for banking and financial institutions

Identity verification for loan and credit card applications

Compliance with KYC and AML regulations

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 for authentication (JWT format)
Content-Type	Yes	Must be set to `multipart/form-data` for file upload

Path Parameters

Parameter	Required	Description
client_id	Yes	Unique identifier for the client whose passport is being uploaded

Request Body

Parameter	Type	Required	Description
file	File	Yes	Image of the passport (JPG or PNG format, max 5MB)

File Requirements

Supported Formats: JPG, PNG

Maximum File Size: 5MB

Image Quality: Clear, legible image of the passport with all text visible

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all extracted passport information
data.doe	String	Date of expiry (YYYY-MM-DD)
data.dob	String	Date of birth (YYYY-MM-DD)
data.father	String	Father's name
data.given_name	String	Given name of the passport holder
data.mrz_line_1	String	First line of the Machine Readable Zone
data.old_passport_num	String	Previous passport number, if applicable
data.file_num	String	File number of the passport
data.client_id	String	Client identifier
data.place_of_issue	String	Location where the passport was issued
data.spouse	String	Spouse's name, if applicable
data.country_code	String	Three-letter country code
data.address	String	Address of the passport holder
data.surname	String	Surname/family name of the passport holder
data.mrz_line_2	String	Second line of the Machine Readable Zone
data.passport_num	String	Passport number
data.doi	String	Date of issue (YYYY-MM-DD)
data.old_doi	String	Date of issue of previous passport, if applicable
data.gender	String	Gender of the passport holder
data.nationality	String	Nationality of the passport holder
data.place_of_birth	String	Place of birth
data.mother	String	Mother's name
data.old_place_of_issue	String	Place where previous passport was issued, if applicable
data.pin	String	PIN code/postal code
data.passport_validity	String	Validity status of the passport
status_code	Integer	HTTP status code indicating the result of the operation
message	String	Additional information or error message
success	Boolean	Indicates whether the operation was successful

Example Successful Response

{
    "data": {
        "doe": "2020-09-15",
        "dob": "1990-08-31",
        "father": "KALEEN BHAIYA",
        "given_name": "MUNNA BHAIYA",
        "mrz_line_1": "PPINDBHAIYA<<MUNNA<<<<<<<<<<<<<<<<<<<<<<<<<<",
        "old_passport_num": "F0233736",
        "file_num": "UPHM00597710",
        "client_id": "TTJmMxbZQi",
        "place_of_issue": "MIRZAPUR",
        "spouse": "",
        "country_code": "IND",
        "address": "TRIPATHI HAVELI, MIRZAPUR",
        "surname": "BAGGA",
        "mrz_line_2": "J0933933<1IND9008319M2009155<<<<<<<<<<<<<<04",
        "passport_num": "J0933836",
        "doi": "2010-10-15",
        "old_doi": "2005-10-15",
        "gender": "MALE",
        "nationality": "INDIAN",
        "place_of_birth": " MIRZAPUR",
        "mother": "BEENA TRIPATHI",
        "old_place_of_issue": "MIRZAPUR",
        "pin": "231001",
        "passport_validity": null
    },
    "status_code": 200,
    "message": "",
    "success": true
}

Possible Error Responses

Authentication Error

File Format Error

File Size Error

OCR Failure

{
    "data": null,
    "status_code": 401,
    "message": "Invalid or expired token",
    "success": false
}

This error 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 refresh mechanisms to handle token expiration

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

Implement proper error handling to avoid exposing sensitive information

Delete passport images after processing to minimize data storage risks

User Experience Guidelines

Provide clear instructions to users on passport image requirements

Implement client-side validation for file format and size before upload

Display a loading indicator during the upload and processing phase

Offer guidance on how to capture a clear passport image

Implement a review step allowing users to verify extracted information

Code Samples

cURL

Python

Node.js

Related APIs

Passport Verification API: Verifies passport details against government databases

OCR Document Extraction API: Extracts information from various document types

Client Management API: Manages client profiles and associated documents

Compliance and Legal Considerations

When implementing passport verification, be aware of data protection regulations such as GDPR, CCPA, or local data privacy laws. Ensure you have proper consent for processing personal data and implement appropriate data retention policies. Passport data should be handled with strict security measures and stored only as long as necessary for the intended purpose.

{ "data": { "doe": "2020-09-15", "dob": "1990-08-31", "father": "KALEEN BHAIYA", "given_name": "MUNNA BHAIYA", "mrz_line_1": "PPINDBHAIYA<<MUNNA<<<<<<<<<<<<<<<<<<<<<<<<<<", "old_passport_num": "F0233736", "file_num": "UPHM00597710", "client_id": "TTJmMxbZQi", "place_of_issue": "MIRZAPUR", "spouse": "", "country_code": "IND", "address": "TRIPATHI HAVELI, MIRZAPUR", "surname": "BAGGA", "mrz_line_2": "J0933933<1IND9008319M2009155<<<<<<<<<<<<<<04", "passport_num": "J0933836", "doi": "2010-10-15", "old_doi": "2005-10-15", "gender": "MALE", "nationality": "INDIAN", "place_of_birth": " MIRZAPUR", "mother": "BEENA TRIPATHI", "old_place_of_issue": "MIRZAPUR", "pin": "231001", "passport_validity": null }, "status_code": 200, "message": "", "success": true }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Passport Upload

Passport Upload#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Request Body#

File Requirements#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Passport Upload

Description

Use Cases

Technical Implementation

Request Headers

Path Parameters

Request Body

File Requirements

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples