Create Processor API

Endpoint Overview

POST /api/v1/sureparser/edit-processor

Description

The Create Processor API enables you to configure and initialize intelligent document processing workflows on the Sureparser platform. This endpoint allows you to create customized processors that can split, classify, extract, and analyze documents based on your specific business requirements.

A processor acts as a configurable engine that applies AI-powered document intelligence to uploaded files. You can define processor types (such as splitters for multi-document files), specify document categories for classification, and provide contextual instructions to guide the extraction logic. The API returns a unique processor_id that serves as a reference for executing the processing workflow and retrieving results.

This endpoint is essential for organizations looking to automate document-heavy processes, enabling intelligent routing, data extraction, and document categorization at scale.

Key Benefits

Flexible Configuration: Customize processors with specific categories, context, and processing types tailored to your business needs

Intelligent Document Splitting: Automatically separate multi-document files into individual documents based on AI-powered classification

Contextual Processing: Provide business-specific context to improve accuracy of data extraction and document understanding

Reusable Workflows: Create processor templates that can be applied across multiple documents and workflows

Use Cases

Financial Services

Healthcare

Logistics & E-commerce

Create processors to split combined PDF files containing multiple financial documents (invoices, receipts, statements) into separate categorized documents

Configure processors to extract key financial data like amounts, dates, vendor information, and transaction details from mixed document types

Set up automated workflows for loan application processing where a single upload may contain multiple document types (income proof, bank statements, ID documents)

Build processors for insurance claim documents that automatically categorize and route different document types to appropriate departments

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 JWT token for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
processor_name	String	Yes	Name of the processor. Used to identify and manage the processor in your workflows. Must be a valid name type.
processor_type	String	Yes	Type of processor to create. Currently supported value: `splitter` - Used to split multi-document files into individual categorized documents.
file_id	String	No	Unique identifier of the file to process. Obtained from the File Upload API. Format: `studio_file_<random_string>`. Required if you want to process a specific file immediately.
categories	Array	No	Array of category objects defining document types for classification. Each category object must contain `type` (string) and `description` (string) fields. Used to train the processor on expected document types.
categories[].type	String	No	The document type identifier (e.g., "invoice", "receipt", "statement"). Used as the classification label.
categories[].description	String	No	Detailed description of the document type to help the AI understand classification criteria.
context	String	No	Additional contextual information to guide the processing logic. Describe what data should be extracted, specific business rules, or domain-specific knowledge to improve accuracy.

Example Request

{
  "processor_name": "sample",
  "processor_type": "splitter",
  "file_id": "studio_file_lyoWkhcQyExjuhhzcqof",
  "categories": [
    {
      "type": "invoice",
      "description": "Invoice documents with billing details"
    },
    {
      "type": "receipt",
      "description": "Payment receipts and acknowledgments"
    }
  ],
  "context": "Process financial documents and extract key fields like amount, date, vendor name"
}

Process Response

Response Parameters

Parameter	Type	Description
success	Boolean	Indicates whether the API request was successful (true) or failed (false)
status_code	Integer	HTTP status code of the response (200 for success)
message	String	Human-readable message describing the result of the operation
message_code	String	Machine-readable code for the operation result (e.g., "success")
data	Object	Container object holding the response payload
data.processor_id	String	Unique identifier for the created processor. Use this ID for processor execution and management operations. Format: `studio_processor_<random_string>`
data.processor_name	String	Name of the created processor as provided in the request
data.file_id	String	File ID associated with the processor (if provided in request)
data.filename	String	Original filename of the associated document
data.processor_type	String	Type of the created processor (e.g., "splitter")
data.created_at	String	Timestamp of processor creation in ISO 8601 format

Example Successful Response

{
  "data": {
    "processor_id": "studio_processor_ZsyAumAbqPrniLzjjzUP",
    "processor_name": "updated testing",
    "file_id": "studio_file_lyoWkhcQyExjuhhzcqof",
    "filename": "Pan_and_Aadhar_in_Same_PDF.pdf",
    "processor_type": "splitter",
    "created_at": "2025-12-18T07:31:16.906000"
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Authentication Error

Missing Required Field

Invalid Processor Type

Invalid File ID

{
  "success": false,
  "status_code": 401,
  "message": "Unauthorized access. Invalid or expired token.",
  "message_code": "unauthorized"
}

This error occurs when the JWT token is missing, invalid, or expired. Verify that you're using the correct token for the environment (sandbox/production) and that it hasn't expired.

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely using environment variables or secure vaults. Never hardcode tokens in your application code or commit them to version control.

HTTPS Only: Always use HTTPS endpoints to ensure encrypted transmission of sensitive processor configurations and document metadata.

Processor ID Storage: Securely store returned processor_id values in your database with appropriate access controls for future reference and execution.

Input Validation: Validate all input parameters on the client side before making API calls to reduce errors and improve user experience.

Access Control: Implement role-based access control (RBAC) to restrict which users can create, modify, or execute processors in your organization.

User Experience Guidelines

Descriptive Naming: Use clear, descriptive processor names that indicate their purpose (e.g., "Invoice_Splitter_Q4_2024" instead of "processor_1").

Category Definitions: Provide detailed category descriptions to improve classification accuracy. Include examples of what documents fall into each category.

Context Optimization: Write comprehensive context strings that describe your business requirements, expected data formats, and any domain-specific terminology.

Error Handling: Implement robust error handling with user-friendly messages that guide users to resolve issues quickly.

Processor Reusability: Design processors to be reusable across multiple files and workflows to maximize efficiency and consistency.

Testing: Use the sandbox environment to thoroughly test processor configurations before deploying to production.

Code Samples

cURL

Python

Node.js

Related APIs

File Upload API: Upload documents to obtain the file_id required for processor creation

Execute Processor API: Run the created processor on uploaded files to perform document splitting and classification

Get Processor Status API: Check the processing status and retrieve results after processor execution

Update Processor API: Modify processor configurations including categories, context, and associated files

List Processors API: Retrieve all processors created in your account for management and monitoring

Delete Processor API: Remove processors that are no longer needed from your account

Compliance and Legal Considerations

When creating processors for document processing, ensure compliance with relevant data protection regulations such as GDPR, CCPA, and local privacy laws. Processors may handle documents containing personally identifiable information (PII) and sensitive data that require appropriate security measures. Implement data retention policies aligned with regulatory requirements and obtain necessary user consents for document processing. The processor configuration, including categories and context, should be designed to extract only necessary data for your business purposes. Maintain audit logs of processor creation, modification, and execution for compliance traceability. Organizations in regulated industries (finance, healthcare, legal) should ensure processor configurations align with industry-specific compliance requirements such as HIPAA, PCI-DSS, or SOC 2.

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/edit-processor' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "processor_id": "processor_id", "processor_name": "Updated Passport processor", "file_id" : "file_id", "categories": [ { "type": "passport", "description": "" } ], "context": "Updated context for processing" }'

{ "data": { "processor_id": "processor_configABCDEFGHIJKLMNOPQ", "processor_name": "Updated Invoice Processor", "file_id": "fileABCDEFGHIJKLMNOPQRSTU", "filename": "sample.pdf", "processor_type": "splitter", "created_at": "2024-12-13T12:00:00.000000" }, "status_code": 200, "message": "Success", "success": true }

Edit Processor

Create Processor API#

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