Fetch Execution Details

Endpoint Overview

GET /api/v1/sureparser/fetch-execution

Description

The Fetch Execution Details API endpoint retrieves the status and results of a specific processor execution within the Surepass SureParse platform. By providing a valid client_id (obtained from the execute-processor API), clients can monitor the progress, completion status, and output data of document parsing or transformation jobs. This endpoint is essential for tracking asynchronous processing, accessing extracted data, and integrating SureParse results into downstream business workflows.

Key Benefits

Enables real-time tracking of processor execution status and results.

Provides detailed output data for processed documents, including extracted fields.

Supports robust integration with business automation and reporting systems.

Facilitates error handling and troubleshooting by exposing execution metadata and error messages.

Use Cases

Financial Services

Healthcare

Logistics

Monitor the completion and results of KYC document parsing jobs.

Retrieve extracted data from processed financial statements for compliance checks.

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
client_id	string	Yes	Unique identifier of the execution to fetch. This value is obtained from the execute-processor API.

Example Request

{
  "client_id": "studio_executor_orZubjXLHSOxtcQczLpl"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains execution and result details
├─ 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	Current status of the execution (e.g., "completed")
├─ created_at	string	ISO timestamp of execution creation
├─ updated_at	string	ISO timestamp of last update
├─ total_documents	integer	Number of documents processed
├─ total_pages	integer	Number of pages processed
├─ result_data	object	Parsed results, including extracted fields
├─ error_message	string	Error message if execution failed (nullable)
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": {
    "client_id": "studio_executor_orZubjXLHSOxtcQczLpl",
    "processor_id": "studio_processor_blypAacKhRnHxPmZuOXr",
    "processor_name": "demo",
    "file_id": "studio_file_lyoWkhcQyExjuhhzcqow",
    "filename": "sample.pdf",
    "processor_type": "splitter",
    "status": "completed",
    "created_at": "2025-12-17T11:19:17.218000",
    "updated_at": "2025-12-17T11:19:40.949000",
    "total_documents": 1,
    "total_pages": 1,
    "result_data": {
      "documents": [
        {
          "start_page": 1,
          "end_page": 1,
          "identifier": "other",
          "category": "other",
          "fields": {
          }
        }
      ]
    },
    "error_message": null
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Execution Not Found

Authentication Error

{
  "data": null,
  "status_code": 404,
  "success": false,
  "message": "Execution not found",
  "message_code": "execution_not_found"
}

The specified client_id does not exist or is 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 results to authorized users only.

User Experience Guidelines

Display execution status and parsed results clearly to users.

Handle and display error messages if execution details cannot be fetched.

Code Samples

cURL

Python

Node.js

Related APIs

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

Get Processor Details: Retrieve configuration and status for a specific processor.

Delete Processor: Remove a processor from the SureParse platform.

Compliance and Legal Considerations

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

This documentation provides a complete, implementation-focused guide for integrating with the Fetch Execution Details 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", "created_at": "2024-12-13T12:00:00.000000", "updated_at": "2024-12-13T12:01:30.000000", "total_documents": 3, "total_pages": 10, "result_data": { "documents": [ { "start_page": 1, "end_page": 3, "identifier": "INV-2024-001", "category": "invoice", "fields": { "invoice_number": "INV-2024-001", "amount": "$1,500.00", "date": "2024-12-01", "vendor": "Acme Corp" } }, { "start_page": 4, "end_page": 6, "identifier": "INV-2024-002", "category": "invoice", "fields": { "invoice_number": "INV-2024-002", "amount": "$2,300.00", "date": "2024-12-05", "vendor": "Tech Solutions" } } ] }, "error_message": null }, "status_code": 200, "message": "Success", "success": true }

Fetch Execution Result

Fetch Execution Details#

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