Execution History

Endpoint Overview

GET /api/v1/sureparser/execution-history

Description

The Execution History API endpoint provides a paginated list of all processor execution records within the Surepass SureParse platform. By querying this endpoint, clients can review historical executions, monitor processing trends, and audit document parsing activities. This is essential for compliance, troubleshooting, and operational analytics, giving organizations full visibility into their document processing workflows.

Key Benefits

Retrieve a comprehensive, paginated history of all processor executions.

Enables auditing and compliance tracking for document processing activities.

Supports operational analytics and trend monitoring.

Facilitates troubleshooting by providing detailed execution metadata.

Use Cases

Financial Services

Healthcare

Logistics

Audit all KYC document parsing activities for compliance.

Analyze trends in document processing volumes over time.

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.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT)
Content-Type	No	Optional for GET requests

Query Parameters

Parameter	Type	Required	Description
page	int	No	Page number for pagination (default: 1)
page_size	int	No	Number of records per page (default: 30)

Example Request

{
  "page": 1,
  "page_size": 2
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains execution history and pagination info
├─ history	array	List of execution records
│ ├─ client_id	string	Unique identifier for the execution instance
│ ├─ processor_id	string	Identifier of the processor used
│ ├─ processor_name	string	Name of the processor
│ ├─ file_id	string	Identifier of the associated file
│ ├─ filename	string	Name of the file processed
│ ├─ processor_type	string	Type of processor (e.g., splitter)
│ ├─ status	string	Status of the execution (e.g., "completed")
│ ├─ total_documents	int	Number of documents processed
│ ├─ total_pages	int	Number of pages processed
│ ├─ created_at	string	ISO timestamp of execution creation
│ ├─ updated_at	string	ISO timestamp of last update
├─ pagination	object	Pagination details
│ ├─ page	int	Current page number
│ ├─ records	int	Number of records returned
│ ├─ has_next	bool	Indicates if more pages are available
status_code	integer	HTTP status code (e.g., 200 for success)
success	boolean	Indicates if the request was successful
message	string	Human-readable status message
message_code	string	Machine-readable status code

Example Successful Response

{
  "data": {
    "history": [
      {
        "client_id": "studio_executor_1234567890",
        "processor_id": "studio_processor_ABCDEF1234",
        "processor_name": "Sample Processor 1",
        "file_id": "studio_file_9876543210",
        "filename": "Document_One.pdf",
        "processor_type": "splitter",
        "status": "completed",
        "total_documents": 2,
        "total_pages": 5,
        "created_at": "2025-12-17T09:00:00.000000",
        "updated_at": "2025-12-17T09:05:00.000000"
      },
      {
        "client_id": "studio_executor_0987654321",
        "processor_id": "studio_processor_XYZ9876543",
        "processor_name": "Sample Processor 2",
        "file_id": "studio_file_1234567890",
        "filename": "Document_Two.pdf",
        "processor_type": "splitter",
        "status": "completed",
        "total_documents": 1,
        "total_pages": 3,
        "created_at": "2025-12-17T10:00:00.000000",
        "updated_at": "2025-12-17T10:03:00.000000"
      }
    ],
    "pagination": {
      "page": 1,
      "records": 2,
      "has_next": true
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid Pagination

Authentication Error

{
  "data": null,
  "status_code": 400,
  "success": false,
  "message": "Invalid pagination parameters",
  "message_code": "invalid_pagination"
}

The provided page or page_size parameters are invalid.

Integration Best Practices

Security Recommendations

Always use HTTPS for all API requests to protect sensitive data in transit.

Store JWT tokens securely and rotate them regularly.

Restrict access to execution history to authorized users only.

User Experience Guidelines

Provide clear pagination controls for navigating large execution histories.

Display execution status and metadata in an easy-to-read format for users.

Code Samples

cURL

Python

Node.js

Related APIs

Fetch Execution Details: Retrieve the status and results of a specific execution.

Processor Status: Get the current status and results of a processor execution.

Execute Processor: Initiate a processor execution and obtain a client_id.

Compliance and Legal Considerations

Ensure that access to execution history complies with your organization’s data privacy and retention policies. Only authorized users should be allowed to view execution logs, and all access should be logged for audit purposes.

This documentation provides a complete, implementation-focused guide for integrating with the Execution History API endpoint. For further support, consult the Surepass developer portal or contact your Surepass technical representative.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": [ { "client_id": "processor_executorABCDEFGHIJKLMNO", "processor_id": "processor_configABCDEFGHIJKLMNOPQ", "processor_name": "Invoice Processor", "file_id": "fileABCDEFGHIJKLMNOPQRSTU", "filename": "sample.pdf", "processor_type": "splitter", "status": "completed", "total_documents": 3, "total_pages": 10, "created_at": "2024-12-13T12:00:00.000000", "updated_at": "2024-12-13T12:01:30.000000" } ], "status_code": 200, "message": "Success", "success": true }

Execution History

Execution History#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Execution History

Description

Use Cases

Technical Implementation

Request Headers

Query Parameters

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples