Create Processor API

Endpoint Overview

POST /api/v1/sureparser/create-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 can be used to execute the processing workflow and retrieve 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 Processing Types: Configure processors for different use cases including document splitting, classification, and extraction

Custom Categories: Define specific document types and categories relevant to your business domain

Contextual Intelligence: Provide business context to enhance AI accuracy and extraction relevance

Reusable Workflows: Create processors once and apply them to multiple documents for consistent processing

Use Cases

Financial Services

Healthcare

Legal & Compliance

Split bundled loan application packages into individual documents (identity proofs, income statements, bank statements)

Classify financial documents by type (invoices, receipts, purchase orders, contracts) for automated routing

Process mixed KYC document bundles containing PAN, Aadhaar, and passport documents

Extract structured data from diverse financial instruments and statements with custom field definitions

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. This should be a descriptive name that helps identify the processor's purpose. Must be a valid name format.
processor_type	String	Yes	Type of processor to create. Defines the processing workflow. Valid values include: `splitter` (for splitting multi-document files into separate documents).
file_id	String	No	File identifier obtained from the File Upload API. Format: `studio_file_<random_string>`. Required when creating a processor for a specific file.
categories	Array	No	Array of category objects defining document types for classification. Each category object contains `type` (category identifier) and `description` (detailed description of the category). Used for intelligent document classification.
context	String	No	Contextual information to guide the processor's AI logic. Provide business-specific instructions, field extraction requirements, or processing guidelines to enhance accuracy.
folder_id	String	No	Folder identifier for organizing processors. Format: `studio_folder_<random_string>`. Use this to group related processors for better organization.

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",
  "folder_id": null
}

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 to execute processing workflows. Format: `studio_processor_<random_string>`
data.processor_name	String	Name of the created processor as provided in the request
data.file_id	String	File identifier associated with this processor
data.filename	String	Original filename of the document associated with this processor
data.processor_type	String	Type of processor created (e.g., "splitter")
data.created_at	String	ISO 8601 timestamp indicating when the processor was created

Example Successful Response

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

Possible Error Responses

Authentication Error

Missing Required Field

Invalid File ID

Invalid Processor Type

{
  "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 processor configurations and sensitive metadata.

Access Control: Implement role-based access controls to restrict processor creation to authorized users and systems.

Processor ID Protection: Treat processor_ids as sensitive identifiers and implement appropriate access controls for processor execution.

Audit Logging: Maintain logs of all processor creation events for security monitoring and compliance audits.

User Experience Guidelines

Descriptive Naming: Use clear, descriptive processor names that indicate the purpose and document type (e.g., "Invoice_Splitter_Finance" instead of "proc1").

Category Definitions: Provide comprehensive category descriptions to improve classification accuracy and make processor behavior transparent.

Contextual Instructions: Include detailed context that explains business rules, required fields, and edge cases to optimize processing quality.

Error Handling: Implement graceful error handling with user-friendly messages when processor creation fails.

Processor Reusability: Design processors to be reusable across similar document types rather than creating new processors for each file.

Code Samples

cURL

Python

Node.js

Related APIs

File Upload API: Upload documents to the Sureparser platform and obtain file_id for processor creation

Execute Processor API: Run the created processor on uploaded documents to perform splitting, classification, or extraction

Get Processor Status API: Check the execution status and progress of a running processor

List Processors API: Retrieve all processors created in your workspace for management and reuse

Get Processor Results API: Fetch the output and extracted data from completed processor executions

Compliance and Legal Considerations

When creating processors that handle sensitive documents, ensure compliance with relevant data protection regulations including GDPR, CCPA, HIPAA, and industry-specific requirements. Processors may be configured to extract personally identifiable information (PII), financial data, or protected health information (PHI) that requires special handling. Implement appropriate data retention policies and ensure that category definitions and context instructions align with your organization's privacy policies. Maintain audit trails of processor configurations and executions for compliance verification. The responsibility for ensuring lawful processing of documents and adherence to consent requirements rests with the implementing organization.

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/create-processor' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "processor_name": "Passport", "processor_type": "splitter", "file_id": "file_id", "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" }'

{ "data": { "processor_id": "processor_configABCDEFGHIJKLMNOPQ", "processor_name": "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 }

Create 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