Get E-Sign Status

Endpoint Overview

GET /api/v1/esign/status/{client_id}

Description

This API endpoint allows you to retrieve the current status of an electronic signature (e-sign) process for a specific client. It provides real-time visibility into where a client stands in the e-signing workflow, from initiation through completion or failure. This endpoint is essential for applications that need to track the progress of document signing processes and take appropriate actions based on the current status.

Key Benefits

Real-time status tracking of e-sign processes

Simplified workflow management for document signing

Ability to trigger appropriate follow-up actions based on current status

Seamless integration with existing document management systems

Use Cases

Financial Services

Real Estate

Human Resources

Track loan agreement signing status to proceed with fund disbursement

Monitor insurance policy document signing to activate coverage

Verify completion of account opening documents for new customers

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
Content-Type	Yes	Application/json

Path Parameters

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier for the e-sign process (e.g., "esign_HwEwRYRYjexlRMwvolkS")

Request Body

No request body is required for this endpoint.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the status information
data.client_id	String	Unique identifier for the e-sign process
data.status	String	Current status of the e-sign process
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable message describing the result
message_code	String	Machine-readable code for the message

Status Values

The status field can have the following values:

Status	Description
client_intiated	E-sign process has been initiated for the client
otp_sent	One-time password has been sent to the client for verification
otp_verified	Client has successfully verified the OTP
esign_started	E-sign process has begun after OTP verification
esign_completed	E-sign process has been successfully completed
esign_failed	E-sign process has failed

Example Successful Response

{
    "data": {
        "client_id": "esign_HwEwRYRYjexlRMwvolkS",
        "status": "esign_completed"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "status_code": 404,
    "success": false,
    "message": "Client ID not found",
    "message_code": "client_id_not_found"
}

This error occurs when the provided client_id does not exist in the system.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

Set up appropriate access controls to limit who can check e-sign statuses

Regularly rotate JWT tokens to minimize security risks

User Experience Guidelines

Poll this endpoint at reasonable intervals to provide real-time updates without overloading the API

Display user-friendly status messages based on the returned status value

Implement appropriate UI indicators (progress bars, status icons) to visualize the e-sign process

Provide clear next steps for users based on the current status

Code Samples

cURL

Python

Node.js

Related APIs

E-Sign Initiate API: Initiates the e-sign process for a client

E-Sign Verify OTP API: Verifies the OTP sent to the client during e-sign process

E-Sign Document Retrieval API: Retrieves the signed document after completion

Compliance and Legal Considerations

Electronic signatures collected through this API may be subject to various regulations such as eIDAS in Europe, ESIGN Act in the US, or IT Act in India. Ensure your implementation complies with the relevant regulations in your jurisdiction. Proper consent and authentication mechanisms should be in place before initiating the e-sign process.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "esign_HwEwRYRYjexlRMwvolkS", "status": "esign_completed" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Get Status

Get E-Sign Status#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Request Body#

Response Parameters#

Status Values#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Get E-Sign Status

Description

Use Cases

Technical Implementation

Request Headers

Path Parameters

Request Body

Response Parameters

Status Values

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples