Get eSign Report

Endpoint Overview

POST /api/v1/esign/report/{client_id}

Description

This API endpoint retrieves detailed eSign verification reports for a specific client. It allows you to request specific categories of verification data, such as name matching between the signer's information and their digital certificate details. This endpoint is particularly useful for validating the authenticity of electronically signed documents and verifying the identity of signatories.

Key Benefits

Verify the authenticity of digital signatures with detailed match reports

Access certificate details including name, location, and identification information

Customize reports by requesting only the specific verification categories you need

Integrate signature verification seamlessly into your document workflow

Use Cases

Financial Services

Legal

Real Estate

Verify customer identity during digital loan agreement signing

Validate electronic signatures on account opening documents

Confirm authenticity of signed investment agreements

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	Application/json

Path Parameters

Parameter	Required	Description
client_id	Yes	Unique identifier for the client whose eSign report is being requested

Request Body

Parameter	Type	Required	Description
categories	Array	Yes	List of report categories to retrieve (e.g., "name_match")

Example Request

{
    "categories": ["name_match"]
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for the client
data.reports	Object	Container for requested report categories
data.reports.name_match	Object	Name matching report data
data.reports.name_match.name	String	Name provided for verification
data.reports.name_match.name_matched	Boolean	Whether the name matches the certificate
data.reports.name_match.name_match_score	String	Confidence score of the name match (0-100)
data.reports.name_match.certificate_details	Object	Details from the signer's certificate
data.reports.name_match.certificate_details.name	String	Full name on the certificate
data.reports.name_match.certificate_details.country	String	Country code from the certificate
data.reports.name_match.certificate_details.state	String	State from the certificate
data.reports.name_match.certificate_details.pin_code	String	Postal code from the certificate
data.reports.name_match.certificate_details.aaadhar_last_four_digits	String	Last four digits of Aadhaar number
status_code	Integer	HTTP status code of the response
success	Boolean	Whether the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "esign_HwEwRYRYjexlRMwvolkS",
        "reports": {
            "name_match": {
                "name": "Harish",
                "name_matched": true,
                "name_match_score": "64",
                "certificate_details": {
                    "name": "Harish Singh",
                    "country": "IN",
                    "state": "Delhi",
                    "pin_code": "110088",
                    "aaadhar_last_four_digits": "1857"
                }
            }
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Client ID

Invalid Category

{
    "status_code": 401,
    "success": false,
    "message": "Invalid or expired token",
    "message_code": "unauthorized"
}

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

User Experience Guidelines

Request only the specific categories needed to minimize response time

Implement appropriate loading indicators during API calls

Display match scores with visual indicators (green for high match, yellow for partial, red for low)

Provide clear explanations to end-users about what the verification results mean

Code Samples

cURL

Python

Node.js

Related APIs

eSign Document API: Create and manage electronic signature requests

eSign Status API: Check the status of pending signature requests

eSign Verification API: Verify the authenticity of signed documents

Compliance and Legal Considerations

When using this API for electronic signature verification, ensure compliance with local electronic signature laws such as the Information Technology Act in India or eIDAS in Europe. The verification data provided by this API may be used as supporting evidence for signature authenticity but should be implemented as part of a comprehensive electronic signature solution that meets all legal requirements in your jurisdiction.

{ "data": { "client_id": "esign_HwEwRYRYjexlRMwvolkS", "reports": { "name_match": { "name": "Harish", "name_matched": true, "name_match_score": "64", "certificate_details": { "name": "Harish Singh", "country": "IN", "state": "Delhi", "pin_code": "110088", "aaadhar_last_four_digits": "1857" } } } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Get Report

Get eSign Report#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses