Job Batches

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/api/v1/enqueueFromCSV' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@/path/to/cases.csv' \
-F 'agent_id=your-agent-key'

import requests
import os

def create_batch_from_csv(api_key: str, agent_key: str, csv_path: str):
    url = "https://api.parcha.ai/api/v1/enqueueFromCSV"
    
    with open(csv_path, 'rb') as f:
        files = {'file': f}
        data = {'agent_id': agent_key}
        headers = {'Authorization': f'Bearer {api_key}'}
        
        response = requests.post(url, 
                               headers=headers,
                               data=data, 
                               files=files)
        return response.json()

# Example usage
result = create_batch_from_csv(
    api_key='YOUR_API_KEY',
    agent_key='your-agent-key',
    csv_path='cases.csv'
)
print(f"Batch created with {len(result['jobs'])} jobs")

import axios from 'axios';
import FormData from 'form-data';
import fs from 'fs';

async function createBatchFromCSV(
  apiKey: string, 
  agentKey: string, 
  csvPath: string
) {
  const form = new FormData();
  form.append('file', fs.createReadStream(csvPath));
  form.append('agent_id', agentKey);

  const response = await axios.post(
    'https://api.parcha.ai/api/v1/enqueueFromCSV',
    form,
    {
      headers: {
        ...form.getHeaders(),
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );

  return response.data;
}

// Example usage
createBatchFromCSV(
  'YOUR_API_KEY',
  'your-agent-key',
  'cases.csv'
)
.then(result => {
  console.log(`Batch created with ${result.jobs.length} jobs`);
})
.catch(console.error);

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

first_name,last_name,date_of_birth,country_of_nationality
John,Doe,1980-01-01,US
Jane,Smith,1985-05-15,UK

Listing Batches

To get a list of all batches for an agent:

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

import requests

def get_batches(api_key: str, agent_key: str, include_urls: bool = True):
    url = f"https://api.parcha.ai/api/v1/getJobBatches"
    
    params = {
        'agent_key': agent_key,
        'include_signed_urls': include_urls  # Returns secure URLs for CSV files
    }
    
    headers = {'Authorization': f'Bearer {api_key}'}
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Example usage
batches = get_batches('YOUR_API_KEY', 'your-agent-key')
for batch in batches:
    print(f"Batch: {batch['batch_name']}")
    print(f"Created: {batch['created_at']}")
    print(f"CSV URL: {batch.get('csv_signed_url', 'No URL available')}")

import axios from 'axios';

async function getBatches(
  apiKey: string, 
  agentKey: string, 
  includeUrls: boolean = true  // Returns secure URLs for CSV files
) {
  const response = await axios.get(
    'https://api.parcha.ai/api/v1/getJobBatches',
    {
      params: {
        agent_key: agentKey,
        include_signed_urls: includeUrls
      },
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );
  
  return response.data;
}

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/api/v1/getBatchJobs?batch_id=your-batch-id&fetch_pdf_from_gcs=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

import requests

def get_batch_jobs(
    api_key: str, 
    batch_id: str, 
    fetch_pdf: bool = True  # Include secure PDF URLs in response
):
    url = f"https://api.parcha.ai/api/v1/getBatchJobs"
    
    params = {
        'batch_id': batch_id,
        'fetch_pdf_from_gcs': fetch_pdf
    }
    
    headers = {'Authorization': f'Bearer {api_key}'}
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

import axios from 'axios';

async function getBatchJobs(
  apiKey: string, 
  batchId: string,
  fetchPdf: boolean = true  // Include secure PDF URLs in response
) {
  const response = await axios.get(
    'https://api.parcha.ai/api/v1/getBatchJobs',
    {
      params: {
        batch_id: batchId,
        fetch_pdf_from_gcs: fetchPdf
      },
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );
  
  return response.data;
}

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/api/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"

import requests

def download_report(
    api_key: str, 
    case_id: str,
    agent_key: str,
    force_refresh: bool = False  # Set to True to regenerate PDF
):
    url = "https://api.parcha.ai/api/v1/downloadReport"
    
    data = {
        "case_id": case_id,
        "agent_key": agent_key,
        "force_refresh_report": force_refresh
    }
    
    headers = {'Authorization': f'Bearer {api_key}'}
    
    response = requests.post(
        url, 
        headers=headers,
        json=data
    )
    
    if response.headers['content-type'] == 'application/pdf':
        # Save PDF
        with open(f"{case_id}_report.pdf", 'wb') as f:
            f.write(response.content)
        return f"Report saved as {case_id}_report.pdf"
    else:
        return response.json()

import axios from 'axios';
import fs from 'fs';

async function downloadReport(
  apiKey: string,
  caseId: string,
  agentKey: string,
  forceRefresh: boolean = false  // Set to True to regenerate PDF
) {
  const response = await axios.post(
    'https://api.parcha.ai/api/v1/downloadReport',
    {
      case_id: caseId,
      agent_key: agentKey,
      force_refresh_report: forceRefresh
    },
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      },
      responseType: 'arraybuffer'
    }
  );

  if (response.headers['content-type'] === 'application/pdf') {
    const fileName = `${caseId}_report.pdf`;
    fs.writeFileSync(fileName, response.data);
    return `Report saved as ${fileName}`;
  } else {
    const data = JSON.parse(
      Buffer.from(response.data).toString('utf8')
    );
    return data;
  }
}

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

Create Batch
- Upload CSV file or use API endpoints
- System generates batch ID and processes jobs
Monitor Progress
- Use getJobBatches to list all batches
- Use getBatchJobs to check individual job statuses
Access Reports
- Download PDF reports using provided GCS URLs
- Generate missing reports using downloadReport endpoint
Export Results
- Use CSV export functionality for batch results
- Access individual job results through API

Getting Started

Checks Results

API Reference

What is a Job Batch?

Creating a Batch

Using CSV Upload

Listing Batches

Parameters:

## Getting Batch Jobs

Parameters:

Downloading Reports

Parameters:

Batch Processing Flow

​What is a Job Batch?

​Creating a Batch

​Using CSV Upload

​Listing Batches

​Parameters:

​## Getting Batch Jobs

​Parameters:

​Downloading Reports

​Parameters:

​Batch Processing Flow

What is a Job Batch?

Creating a Batch

Using CSV Upload

Listing Batches

Parameters:

## Getting Batch Jobs

Parameters:

Downloading Reports

Parameters:

Batch Processing Flow