Get Audit Trail

Endpoint Overview

GET /api/v1/esign/audit-trail/{client_id}

Description

This API endpoint retrieves the audit trail for a specific e-signature document identified by the client ID. The audit trail provides a comprehensive record of all actions taken on the document, including when it was created, viewed, and signed by each party. This serves as a legally verifiable record of the document's history and can be used for compliance and verification purposes.

Key Benefits

Provides legal proof of document authenticity and signing process

Enables compliance with electronic signature regulations

Offers transparent visibility into the complete document lifecycle

Simplifies record-keeping and audit processes

Use Cases

Financial Services

Legal

Human Resources

Retrieve audit trails for loan agreements to ensure regulatory compliance

Maintain verifiable records of customer consent for financial products

Document the approval chain for high-value transactions

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. Format: `Bearer {your_jwt_token}`
Content-Type	Yes	Application/json

Path Parameters

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier for the e-signature document for which the audit trail is requested

Request Body

This endpoint does not require a request body.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.url	String	Secure URL to access the audit trail document (typically a PDF)
status_code	Integer	HTTP status code indicating the result of the request
message_code	String	Short code indicating the outcome of the request
message	String	Human-readable description of the request outcome
success	Boolean	Indicates whether the request was successful

Example Successful Response

{
    "data": {
        "url": "https://esign.s3.amazonaws.com/adsadbfdanafdbfdbfdsbfdsbsfdb"
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Not Found

Authentication Error

{
    "status_code": 404,
    "message_code": "not_found",
    "message": "Audit trail not found for the specified client ID",
    "success": false
}

The client ID provided does not correspond to any existing e-signature document in the system.

Integration Best Practices

Security Recommendations

Store the JWT token securely and never expose it in client-side code

Implement proper token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data security

Implement proper access controls to restrict who can retrieve audit trails

User Experience Guidelines

Cache audit trail URLs temporarily to improve performance for repeated access

Provide clear download options for users accessing the audit trail

Implement proper error handling to guide users when issues occur

Consider implementing a viewer for the audit trail PDF within your application

Code Samples

cURL

Python

Node.js

Related APIs

Create E-Signature Request: Initiates a new e-signature document for signing

Get E-Signature Status: Retrieves the current status of an e-signature document

Download Signed Document: Retrieves the final signed document

Compliance and Legal Considerations

The audit trail document provided by this API is designed to comply with electronic signature regulations such as eIDAS (EU), ESIGN Act (US), and IT Act (India). The audit trail contains cryptographically verifiable information that can be presented in legal proceedings as evidence of the signing process. Ensure you store these audit trails securely for the duration required by applicable regulations in your jurisdiction.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "url": "https://esign.s3.amazonaws.com/adsadbfdanafdbfdbfdsbfdsbsfdb" }, "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Get Audit Trail

Get Audit Trail#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Get Audit Trail

Description

Use Cases

Technical Implementation

Request Headers

Path Parameters

Request Body

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples