Execute Processor

Endpoint Overview

POST /api/v1/sureparser/execute-processor

Description

The Execute Processor API endpoint initiates the execution of a specified processor within the Surepass SureParse platform. By providing a valid processor_id, clients can trigger automated document parsing, data extraction, or transformation workflows as defined by the processor’s configuration. This endpoint is essential for integrating SureParse’s document automation capabilities into your business processes, enabling real-time or on-demand execution of complex parsing logic.

Key Benefits

Seamlessly trigger document processing workflows programmatically.

Supports real-time and on-demand automation for document parsing.

Returns immediate status and tracking information for the execution.

Integrates easily with existing business applications and orchestration tools.

Use Cases

Financial Services

Healthcare

Logistics

Automate KYC document parsing for onboarding new customers.

Batch process financial statements for compliance and reporting.

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	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
processor_id	string	Yes	Unique identifier of the processor to execute. This value is obtained from the create-processor API.

Example Request

{
  "processor_id": "studio_processor_blypAacKhRnHxPmZuOXr"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains execution and processor details
├─ client_id	string	Unique identifier for the execution instance
├─ processor_id	string	Identifier of the executed processor
├─ processor_name	string	Name of the processor
├─ file_id	string	Identifier of the associated file
├─ filename	string	Name of the file being processed
├─ categories	object	Categories processed (nullable)
├─ context	object	Context for processing (nullable)
├─ processor_type	string	Type of processor (e.g., splitter)
├─ status	string	Current status of the execution (e.g., "processing")
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": "rahulk",
    "file_id": "studio_file_lyoWkhcQyExjuhhzcqof",
    "filename": "Pan_and_Aadhar_in_Same_PDF.pdf",
    "categories": null,
    "context": null,
    "processor_type": "splitter",
    "status": "processing"
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Processor Not Found

Authentication Error

{
  "data": null,
  "status_code": 404,
  "success": false,
  "message": "Processor not found",
  "message_code": "processor_not_found"
}

The specified processor_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 processor execution permissions to trusted users and monitor API usage.

User Experience Guidelines

Display execution status and tracking information to users after triggering a processor.

Handle and display error messages clearly if execution fails.

Code Samples

cURL

Python

Node.js

Related APIs

Create Processor: Define a new processor for document parsing.

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 processor executions comply with your organization’s data privacy and retention policies. Only authorized users should be allowed to trigger processor executions, and all executions should be logged for audit purposes.

This documentation provides a complete, implementation-focused guide for integrating with the Execute Processor 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 ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/sureparser/execute-processor' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "processor_id": "processor_id" }'

{ "data": { "client_id": "processor_executorABCDEFGHIJKLMNO", "processor_id": "processor_configABCDEFGHIJKLMNOPQ", "processor_name": "Invoice Processor", "file_id": "fileABCDEFGHIJKLMNOPQRSTU", "filename": "sample.pdf", "categories": [ { "type": "invoice", "description": "Invoice documents" } ], "context": "Process financial documents", "processor_type": "splitter", "status": "processing" }, "status_code": 200, "message": "Success", "success": true }

Execute Processor

Execute Processor#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Execute Processor

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples