Create Execution History Folder

Endpoint Overview

POST /api/v1/sureparser/create-folder

Description

The Create Execution History Folder API endpoint allows you to create a new folder for organizing and managing execution history records within the Surepass SureParse platform. By specifying a folder name, you can group related processor executions, making it easier to manage, audit, and retrieve historical processing data. This endpoint is essential for maintaining a structured and scalable document processing environment.

Key Benefits

Organize execution history into logical folders for better management.

Simplifies retrieval and auditing of historical processing records.

Supports scalable document processing workflows.

Enhances collaboration by allowing teams to categorize execution data.

Use Cases

Financial Services

Healthcare

Logistics

Create folders for different financial years to organize KYC processing history.

Group execution records by product line or compliance requirement.

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
name	string	Yes	Name of the folder to be created

Example Request

{
  "name": "Financial Documents"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains folder details
├─ folder_id	string	Unique identifier for the created folder
├─ name	string	Name of the created folder
├─ processor_count	int	Number of processors in the folder (default 0)
├─ created_at	string	ISO timestamp of folder creation
status_code	int	HTTP status code (e.g., 200 for success)
success	bool	Indicates if the request was successful
message	string	Human-readable status message
message_code	string	Machine-readable status code

Example Successful Response

{
  "data": {
    "folder_id": "studio_folder_ABC123XYZ",
    "name": "Financial Documents",
    "processor_count": 0,
    "created_at": "2025-12-18T10:19:56.872503"
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Folder Already Exists

Authentication Error

{
  "data": null,
  "status_code": 409,
  "success": false,
  "message": "Folder already exists",
  "message_code": "folder_exists"
}

A folder with the specified name already exists.

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 folder creation permissions to authorized users only.

User Experience Guidelines

Validate folder names to prevent duplicates and ensure clarity.

Display clear success or error messages to users after folder creation.

Code Samples

cURL

Python

Node.js

Related APIs

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

Fetch Execution Details: Retrieve the status and results of a specific execution.

Processor Status: Get the current status and results of a processor execution.

Compliance and Legal Considerations

Ensure that folder creation and management comply with your organization’s data retention and privacy policies. Only authorized users should be allowed to create or modify execution history folders, and all actions should be logged for audit purposes.

This documentation provides a complete, implementation-focused guide for integrating with the Create Execution History Folder 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/create-folder' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Financial Documents" }'

{ "data": { "folder_id": "processor_folderABCDEFGHIJKLMNOP", "name": "Financial Documents", "created_at": "2024-12-13T12:00:00.000000" }, "status_code": 200, "message": "Success", "success": true }

Create Folder

Create Execution History Folder#

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