List Processors API

Endpoint Overview

POST /api/v1/sureparser/list-processors

Description

The List Processors API enables you to retrieve a paginated list of all document processors configured in your Sureparser account. This endpoint provides comprehensive visibility into your document processing workflows, allowing you to manage, monitor, and track all active processors across your organization.

The API supports flexible filtering by folder organization and offers pagination controls to efficiently handle large processor inventories. Each processor entry includes essential metadata such as processor name, associated file details, processor type, folder assignment, and creation timestamp. This endpoint is crucial for building administrative dashboards, processor management interfaces, and workflow monitoring systems.

Key Benefits

Centralized Management: View all configured processors in one place with detailed metadata for easy tracking and management

Folder-Based Organization: Filter processors by folder to manage processors across different teams, projects, or business units

Efficient Pagination: Handle large processor inventories with customizable page sizes and seamless navigation through result sets

Workflow Visibility: Track processor creation history and associated files to maintain complete audit trails of document processing workflows

Use Cases

Financial Services

Healthcare

Enterprise Operations

Monitor all KYC document processors across different customer onboarding workflows and compliance teams

Track invoice and receipt processing configurations for accounts payable automation systems

Audit document classification processors used for loan application processing and credit underwriting

Manage regulatory document processors across various compliance departments and regional offices

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`

Query Parameters

Parameter	Type	Required	Description
page	Integer	No	Page number for pagination. Valid range: 1-100. Default: 1
page_size	Integer	No	Number of processors to return per page. Valid range: 1-50. Default: 30
folder_id	String	No	Filter processors by specific folder. Format: `studio_folder_<random_string>`. When provided, only processors within the specified folder are returned

Example Request

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.processors	Array	List of processor objects matching the query criteria
data.processors[].processor_id	String	Unique identifier for the processor. Format: `studio_processor_<random_string>`
data.processors[].processor_name	String	Human-readable name assigned to the processor
data.processors[].file_id	String	Unique identifier of the file associated with this processor. Format: `studio_file_<random_string>`
data.processors[].filename	String	Original filename of the document associated with the processor
data.processors[].processor_type	String	Type of processor (e.g., "splitter" for document splitting operations)
data.processors[].folder_id	String/Null	Folder identifier if the processor is organized within a folder, null if not assigned to any folder
data.processors[].created_at	String	ISO 8601 timestamp indicating when the processor was created
data.pagination	Object	Pagination metadata for navigating through result sets
data.pagination.page	Integer	Current page number being returned
data.pagination.records	Integer	Number of processor records in the current page
data.pagination.has_next	Boolean	Indicates whether additional pages of results are available (true) or this is the last page (false)

Example Successful Response

{
  "data": {
    "processors": [
      {
        "processor_id": "studio_processor_ZsyAumAbqPrniLzjjzUP",
        "processor_name": "updateed testing",
        "file_id": "studio_file_lyoWkhcQyExjuhhzcqof",
        "filename": "Pan_and_Aadhar_in_Same_PDF.pdf",
        "processor_type": "splitter",
        "folder_id": null,
        "created_at": "2025-12-18T07:31:16.906000"
      },
      {
        "processor_id": "studio_processor_blypAacKhRnHxPmZuOXr",
        "processor_name": "rahulk",
        "file_id": "studio_file_lyoWkhcQyExjuhhzcqof",
        "filename": "Pan_and_Aadhar_in_Same_PDF.pdf",
        "processor_type": "splitter",
        "folder_id": null,
        "created_at": "2025-12-17T11:12:25.360000"
      },
      {
        "processor_id": "studio_processor_xqpbhbzjOoyzpzJYjidu",
        "processor_name": "Rahul",
        "file_id": "studio_file_lyoWkhcQyExjuhhzcqof",
        "filename": "Pan_and_Aadhar_in_Same_PDF.pdf",
        "processor_type": "splitter",
        "folder_id": null,
        "created_at": "2025-12-17T11:12:01.245000"
      },
      {
        "processor_id": "studio_processor_SmAhoRCmowmmHDrrLcGT",
        "processor_name": "samples",
        "file_id": "studio_file_lyoWkhcQyExjuhhzcqof",
        "filename": "Pan_and_Aadhar_in_Same_PDF.pdf",
        "processor_type": "splitter",
        "folder_id": null,
        "created_at": "2025-12-17T11:11:19.078000"
      },
      {
        "processor_id": "studio_processor_AtIwsWxeOdtEqnUdMmgZ",
        "processor_name": "sample",
        "file_id": "studio_file_lyoWkhcQyExjuhhzcqof",
        "filename": "Pan_and_Aadhar_in_Same_PDF.pdf",
        "processor_type": "splitter",
        "folder_id": null,
        "created_at": "2025-12-17T11:11:08.747000"
      }
    ],
    "pagination": {
      "page": 1,
      "records": 5,
      "has_next": true
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Page Parameter

Invalid Page Size

Invalid Folder 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 expose tokens in client-side code or version control systems.

HTTPS Only: Always use HTTPS endpoints to ensure encrypted transmission of processor data and authentication credentials.

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

Token Rotation: Implement regular token rotation policies to minimize security risks from compromised credentials.

Audit Logging: Maintain logs of all list-processor API calls for security auditing and compliance tracking.

User Experience Guidelines

Pagination Strategy: Use appropriate page sizes based on UI requirements. Smaller page sizes (10-20) work well for mobile interfaces, while larger sizes (30-50) suit desktop dashboards.

Loading States: Display loading indicators while fetching processor lists to provide clear feedback during API calls.

Empty State Handling: Provide helpful guidance when no processors are found, especially for first-time users or when folder filters return no results.

Sort and Filter: Implement client-side sorting by creation date, processor name, or processor type for enhanced user experience.

Cache Strategy: Consider implementing short-term caching (1-5 minutes) for processor lists to reduce API calls and improve performance.

Infinite Scroll: Leverage the has_next pagination flag to implement infinite scroll patterns for seamless browsing experiences.

Code Samples

cURL

Python

Node.js

Related APIs

Create Processor API: Create new document processors with custom configurations and processing rules

Edit Processor API: Update existing processor configurations including name, categories, and context

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

Get Processor Details API: Retrieve detailed configuration and metadata for a specific processor

Execute Processor API: Run a processor on uploaded documents to extract structured data

Upload File API: Upload documents that will be processed by your configured processors

Compliance and Legal Considerations

When using this API to list processors, be aware that the response may contain metadata about documents that include personally identifiable information (PII) or sensitive business data. Ensure that access to this endpoint is properly restricted through authentication and authorization mechanisms. The processor list includes filenames and creation timestamps that may be subject to data retention policies under regulations such as GDPR, CCPA, or industry-specific compliance requirements. Implement appropriate access controls and audit logging to maintain compliance with applicable data protection laws. Consider implementing data masking or redaction for sensitive filenames in user interfaces, especially for multi-tenant environments or applications with varying access levels.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

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

List Processors

List Processors API#

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