International Passport Upload

Endpoint Overview

POST /api/v1/ocr/international-passport

Description

This API endpoint extracts and validates information from international passport images using Optical Character Recognition (OCR) technology. It processes the Machine Readable Zone (MRZ) and other key fields from passport documents, returning structured data that can be used for identity verification, KYC processes, and automated document processing.

Key Benefits

Automated extraction of passport data without manual entry

Verification of document authenticity through MRZ validation

Structured data output for seamless integration with identity verification workflows

Support for international passports from multiple countries

Use Cases

Financial Services

Travel & Hospitality

Government & Security

Customer onboarding for banking and financial institutions

KYC verification for investment platforms

Identity verification for loan applications

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`

Request Body

1. For File Upload

Parameter	Type	Required	Description
file	Image	Yes	Upload Cheque Image
use_pdf	Boolean	No	Set to true if the file type is PDF

Example Request

# Multipart form data with passport image file
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

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

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the OCR results
data.client_id	String	Unique identifier for this OCR request
data.ocr_fields	Array	List of extracted document information
data.ocr_fields[].type	String	Type of document processed (always "international_passport")
data.ocr_fields[].details	Object	Extracted passport details
data.ocr_fields[].details.birth_date	String	Date of birth in YYMMDD format
data.ocr_fields[].details.birth_date_hash	String	Verification hash for birth date
data.ocr_fields[].details.country_code	String	3-letter country code of the issuing country
data.ocr_fields[].details.country	String	Full name of the issuing country
data.ocr_fields[].details.document_number	String	Passport number
data.ocr_fields[].details.document_number_hash	String	Verification hash for document number
data.ocr_fields[].details.document_type	String	Document type (P for passport)
data.ocr_fields[].details.expiry_date	String	Expiry date in YYMMDD format
data.ocr_fields[].details.expiry_date_hash	String	Verification hash for expiry date
data.ocr_fields[].details.final_hash	String	Final verification hash for the MRZ
data.ocr_fields[].details.name	String	First/given name of the passport holder
data.ocr_fields[].details.nationality_code	String	3-letter nationality code
data.ocr_fields[].details.nationality	String	Full nationality name (may be null)
data.ocr_fields[].details.optional_data	String	Optional data from the MRZ
data.ocr_fields[].details.optional_data_hash	String	Verification hash for optional data
data.ocr_fields[].details.sex	String	Gender (M/F)
data.ocr_fields[].details.surname	String	Last/family name of the passport holder
data.ocr_fields[].details.mrz_line_1	String	First line of the Machine Readable Zone
data.ocr_fields[].details.mrz_line_2	String	Second line of the Machine Readable Zone
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Additional information message (null if successful)
message_code	String	Code indicating the status of the request

Example Successful Response

{
    "data": {
        "client_id": "ocr_international_passport_qDCvjhnuqvclDIyLSmHR",
        "ocr_fields": [
            {
                "type": "international_passport",
                "details": {
                    "birth_date": "111111",
                    "birth_date_hash": "2",
                    "country_code": "SVK",
                    "country": "Slovakia",
                    "document_number": "PD000000",
                    "document_number_hash": "5",
                    "document_type": "P",
                    "expiry_date": "150104",
                    "expiry_date_hash": "3",
                    "final_hash": "0",
                    "name": "VZOR",
                    "nationality_code": "5VK",
                    "nationality": null,
                    "optional_data": "",
                    "optional_data_hash": "0",
                    "sex": "M",
                    "surname": "SPECIMEN",
                    "mrz_line_1": "P<SVKSPECIMEN<<VZOR<<<<<<<<<<<<<<<<<<<<<<<<<",
                    "mrz_line_2": "PD000000<55VK1111112M1501043<<<<<<<<<<<<<<00"
                }
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Image

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

Always use HTTPS for all API requests to ensure data encryption in transit

Implement proper token management, including secure storage and regular rotation

Limit access to passport data on a need-to-know basis within your application

Implement data retention policies that comply with relevant privacy regulations

User Experience Guidelines

Provide clear instructions to users on how to capture a high-quality passport image

Implement a preview feature so users can verify the image quality before submission

Display a loading indicator during OCR processing to indicate activity

Implement proper error handling with user-friendly messages for common issues

Code Samples

cURL

Python

Node.js

Related APIs

OCR for National ID Cards: Extract information from national identity cards

OCR for Driver's License: Process and extract data from driver's licenses

Document Verification: Verify the authenticity of uploaded documents

Face Match: Compare a selfie with the photo on an identity document

Compliance and Legal Considerations

When processing passport data, ensure compliance with relevant data protection regulations such as GDPR, CCPA, or other applicable regional privacy laws. Passport information is considered sensitive personal data and should be handled with appropriate security measures. Implement proper data minimization and retention policies, and ensure you have a valid legal basis for processing this information.

{ "data": { "client_id": "ocr_international_passport_qDCvjhnuqvclDIyLSmHR", "ocr_fields": [ { "type": "international_passport", "details": { "birth_date": "111111", "birth_date_hash": "2", "country_code": "SVK", "country": "Slovakia", "document_number": "PD000000", "document_number_hash": "5", "document_type": "P", "expiry_date": "150104", "expiry_date_hash": "3", "final_hash": "0", "name": "VZOR", "nationality_code": "5VK", "nationality": null, "optional_data": "", "optional_data_hash": "0", "sex": "M", "surname": "SPECIMEN", "mrz_line_1": "P<SVKSPECIMEN<<VZOR<<<<<<<<<<<<<<<<<<<<<<<<<", "mrz_line_2": "PD000000<55VK1111112M1501043<<<<<<<<<<<<<<00" } } ] }, "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 ********************

International Passport Upload

International Passport Upload#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

1. For File Upload#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

International Passport Upload

Description

Use Cases

Technical Implementation

Request Headers

Request Body

1. For File Upload

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples