The Job Batch feature allows you to process multiple KYB or KYC cases simultaneously by uploading a CSV file or using our standard API endpoints. This guide covers how to create, monitor, and manage job batches.

​
What is a Job Batch?

A job batch is a collection of related jobs that are processed together. Each batch has:

  • A unique batch ID
  • A batch name (typically derived from the uploaded CSV filename)
  • An agent key it’s associated with
  • Creation timestamp

​
Creating a Batch

​
Using CSV Upload

The simplest way to create a batch is by uploading a CSV file containing multiple cases.

curl -X POST 'https://api.parcha.ai/v1/enqueueFromCSV' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@/path/to/cases.csv' \
-F 'agent_id=your-agent-key'

Example Response:

{
 "status": "ok",
 "jobs": [
   {
     "id": "f4cba9af-d976-414e-ad2f-c585696840bd", 
     "status": "QUEUED",
     "agent_id": "your-agent-key"
   },
   {
     "case_id": "john-doe-123",
     "job_id": "a1b2c3d4e5f6414ead2fc585696840bd",
     "started_at": "2024-12-10 17:40:30", 
     "status": "complete",
     "recommendation": "Review",
     "checks": {
       "Source of Wealth Check": "Failed",
       "Adverse Media and OSInt Check": "Failed"
     },
     "pdf_url": "https://storage.example.com/reports/a1b2c3d4e5f6414ead2fc585696840bd.pdf?signed=abc123"
   }
 ]
}

The CSV format should match your agent type:

business_name,website,industry,description
Acme Corp,www.acme.com,Technology,Leading provider of cloud solutions
Beta Inc,www.beta.com,Finance,Investment management firm

​
Listing Batches

To get a list of all batches for an agent:

curl 'https://api.parcha.ai/v1/getJobBatches?agent_key=your-agent-key&include_signed_urls=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

​
Parameters:

  • include_signed_urls: When set to true, returns secure signed URLs for accessing the original CSV files. These URLs are valid for 1 hour.

Example Response:

[
    {
        "updated_at": "2024-01-10T17:40:29.883017",
        "agent_key": "your-agent-key",
        "created_at": "2024-01-10T17:40:29.883011",
        "id": "7fe54d2f-cd87-4d52-9734-d97e893d554a",
        "batch_name": "example_batch.csv [2024-01-10 17:40 UTC]",
        "csv_signed_url": "https://storage.example.com/signed-url-to-csv"
    },
    {
        "updated_at": "2024-01-10T16:53:54.888520",
        "agent_key": "your-agent-key",
        "created_at": "2024-01-10T16:53:54.888513",
        "id": "1a967c94-ddcf-4a23-9953-a3f13ab6af69",
        "batch_name": "another_batch.csv [2024-01-10 16:53 UTC]",
        "csv_signed_url": "https://storage.example.com/signed-url-to-csv"
    }
]

​
## Getting Batch Jobs

To retrieve all jobs in a specific batch:

curl 'https://api.parcha.ai/v1/getBatchJobs?batch_id=your-batch-id&fetch_pdf_from_gcs=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

​
Parameters:

  • fetch_pdf_from_gcs: When set to true, includes secure signed URLs for accessing the PDF reports. These URLs are valid for 1 hour.

Example Response:

[
    {
        "case_id": "CASE-001",
        "job_id": "f4cba9afd976414ead2fc585696840bd",
        "started_at": "2024-01-10 17:40:30",
        "status": "complete",
        "recommendation": "Review",
        "checks": {
            "Source of Wealth Check": "Failed",
            "Adverse Media Check": "Failed"
        },
        "pdf_url": "https://storage.example.com/signed-url-to-pdf"
    },
    {
        "case_id": "CASE-002",
        "job_id": "a1b2c3d4e5f6414ead2fc585696840bd",
        "started_at": "2024-01-10 17:41:30",
        "status": "complete",
        "recommendation": "Approve",
        "checks": {
            "Source of Wealth Check": "Passed",
            "Adverse Media Check": "Passed"
        },
        "pdf_url": "https://storage.example.com/signed-url-to-pdf"
    }
]

​
Downloading Reports

If a job doesn’t have a PDF report URL or you need to regenerate it:

curl -X POST 'https://api.parcha.ai/v1/downloadReport' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "case_id": "your-case-id",
  "agent_key": "your-agent-key",
  "force_refresh_report": false
}' \
--output "case_report.pdf"

​
Parameters:

  • force_refresh_report: When set to true, forces regeneration of the PDF report. This is useful if:
    • The downloaded PDF is blank or corrupted
    • The job was previously in a queued or in-progress state
    • You need a fresh copy of the report
  • Note: Generated PDF URLs expire after 1 hour

Example Request Body:

{
    "agent_key": "your-agent-key",
    "case_id": "CASE-001"
}

Response: Returns a PDF file with the report content.

​
Batch Processing Flow

  1. Create Batch

    • Upload CSV file or use API endpoints
    • System generates batch ID and processes jobs

  2. Monitor Progress

    • Use getJobBatches to list all batches
    • Use getBatchJobs to check individual job statuses

  3. Access Reports

    • Download PDF reports using provided GCS URLs
    • Generate missing reports using downloadReport endpoint

  4. Export Results

    • Use CSV export functionality for batch results
    • Access individual job results through API