List Folders

Endpoint Overview

GET /api/v1/sureparser/list-folders

Description

The List Folders API endpoint retrieves a paginated list of all folders created within the Surepass SureParse platform. Each folder groups related processor executions, helping you organize, manage, and quickly access execution history. This endpoint is essential for maintaining a scalable and structured document processing environment, supporting both operational efficiency and compliance needs.

Key Benefits

Quickly retrieve all folders for streamlined navigation and management.

Supports pagination for efficient handling of large folder sets.

Enables organized grouping of execution histories and processors.

Facilitates compliance, audit, and operational reporting.

Use Cases

Financial Services

Healthcare

Logistics

List folders by fiscal year or compliance category for audit readiness.

Retrieve all folders to manage KYC or loan document processing.

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
page	int	No	Page number for pagination (default: 1)
page_size	int	No	Number of records per page (default: 10)

Example Request

{
  "page": 1,
  "page_size": 2
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains folders and pagination info
├─ folders	array	List of folder objects
│ ├─ folder_id	string	Unique identifier for the folder
│ ├─ name	string	Name of the folder
│ ├─ processor_count	int	Number of processors in the folder
│ ├─ created_at	string	ISO timestamp of folder creation
├─ pagination	object	Pagination details
│ ├─ page	int	Current page number
│ ├─ records	int	Number of records returned
│ ├─ has_next	bool	Indicates if more pages are available
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": {
    "folders": [
      {
        "folder_id": "studio_folder_ABC123XYZ",
        "name": "Financial Documents",
        "processor_count": 2,
        "created_at": "2025-12-18T10:28:54.816000"
      },
      {
        "folder_id": "studio_folder_DEF456UVW",
        "name": "Healthcare Records",
        "processor_count": 3,
        "created_at": "2025-12-18T10:28:53.686000"
      }
    ],
    "pagination": {
      "page": 1,
      "records": 2,
      "has_next": true
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid Pagination

Authentication Error

{
  "data": null,
  "status_code": 400,
  "success": false,
  "message": "Invalid pagination parameters",
  "message_code": "invalid_pagination"
}

The provided page or page_size parameters are 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 folder listings to authorized users only.

User Experience Guidelines

Provide clear pagination controls for navigating large folder lists.

Display folder names and metadata in an easy-to-read format for users.

Code Samples

cURL

Python

Node.js

Related APIs

Create Execution History Folder: Create a new folder for organizing execution history.

Rename Folder: Update the name of an existing folder.

Execution History (GET): Retrieve a paginated list of all processor execution records.

Compliance and Legal Considerations

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

This documentation provides a complete, implementation-focused guide for integrating with the List Folders 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": [ { "folder_id": "processor_folderABCDEFGHIJKLMNOP", "name": "Financial Documents", "created_at": "2024-12-13T12:00:00.000000" } ], "status_code": 200, "message": "Success", "success": true }

List Folders

List Folders#

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

List Folders

Description

Use Cases

Technical Implementation

Request Headers

Query Parameters

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples