How to Run a KYB Agent

This guide explains how to run a Know Your Business (KYB) agent using Parcha’s API. The KYB agent helps verify business information and perform various compliance checks.

​

Prerequisites

Before you can run a KYB agent, you need:

1. API Key: A unique API key provided by Parcha for authentication
2. Agent Key: A specific agent key (e.g., “public-bdd”) provided by Parcha for running KYB checks

​

Overview

The KYB process involves several steps:

1. Prepare the business schema
2. Start the KYB agent job
3. Monitor job status and results
4. Handle job completion

​

Step-by-Step Guide

​

1. Prepare the Business Schema

First, prepare your business schema following the Business Schema documentation. The schema should include:

• Basic business information
• Required documents
• Associated individuals and entities

​

2. Start the KYB Agent Job

Use the /startKYBAgentJob endpoint to start a new KYB job:

curl -X POST 'https://api.parcha.ai/startKYBAgentJob' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "agent_key": "public-bdd",
  "kyb_schema": {
    "id": "example-business-case",
    "self_attested_data": {
      "business_name": "Example Corp",
      "website": "https://example.com"
    }
  },
  "webhook_url": "https://your-webhook-url.com",
  "check_ids": ["kyb.basic_business_profile_check", "kyb.adverse_media_check"]
}'

The response will include:

• job_id: Unique identifier for the job
• status: Initial job status
• created_at: Timestamp of job creation
• message: Status message

​

3. Monitor Job Status and Results

You can monitor the job status and results in two ways:

​

Option 1: Get Job by ID

Use the /getJobById endpoint to get detailed information about a specific job:

curl -X GET 'https://api.parcha.ai/getJobById?job_id=YOUR_JOB_ID&include_check_results=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

This endpoint provides:

• Job status and progress (Possible statuses include PENDING, RUNNING, COMPLETE, FAILED, RETRIED)
• Check results
• Status messages
• Input payload
• Timestamps

​

Option 2: Get Jobs by Case ID

Use the /getJobsByCaseId endpoint to get all jobs associated with a case:

curl -X GET 'https://api.parcha.ai/getJobsByCaseId?case_id=YOUR_CASE_ID&agent_key=public-bdd&include_check_results=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

This endpoint provides:

• List of all jobs for the case
• Job statuses
• Check results
• Status messages

​

4. Handle Job Completion

When a job completes, you can:

1. Review the check results in the response
2. Process any required follow-up actions
3. Update your application state based on the results

​

Common Check Types

​

Compliance Checks

• Basic Business Profile Check
• Adverse Media Screening
• Web Presence Check
• High Risk Country Check
• Business Reviews Check
• Industry Activity Check

​

Document Verifications

• Business Ownership Document Verification
• Incorporation Document Verification
• Proof of Address Document Verification
• EIN Document Verification
• Source of Funds Document Verification

​

Best Practices

1. Schema Preparation

   • Include all required fields for your checks
   • Validate the schema before submission
   • Ensure document URLs are accessible

2. Error Handling

   • Implement proper error handling for API responses
   • Monitor for validation errors
   • Handle rate limiting appropriately

3. Status Monitoring

   • Use webhooks for real-time updates
   • Regularly check job status
   • Log all check results

4. Security

   • Keep API keys secure
   • Use HTTPS for all requests
   • Follow least privilege principle

​

Example Workflow

Here’s a complete example of running a KYB agent:

import requests
import time

def run_kyb_workflow(api_key, business_schema):
    # 1. Start KYB Job
    response = requests.post(
        'https://api.parcha.ai/startKYBAgentJob',
        headers={'Authorization': f'Bearer {api_key}'},
        json={
            'agent_key': 'public-bdd',
            'kyb_schema': business_schema,
            'webhook_url': 'https://your-webhook-url.com'
        }
    )
    job_id = response.json()['job_id']
    
    # 2. Monitor Job Status
    while True:
        current_job_id = job_id # Initialize current_job_id
        response = requests.get(
            f'https://api.parcha.ai/getJobById?job_id={current_job_id}&include_check_results=true',
            headers={'Authorization': f'Bearer {api_key}'}
        )
        job_data = response.json()
        
        if job_data['status'] == 'complete':
            return job_data
        elif job_data['status'] == 'error':
            raise Exception(f'Job {current_job_id} failed')
        elif job_data['status'] == 'RETRIED':
            new_job_id = job_data.get('new_job_id')
            if not new_job_id:
                raise Exception(f'Job {current_job_id} has status RETRIED but no new_job_id found.')
            print(f"Job {current_job_id} was retried. New job ID: {new_job_id}. Continuing with new job.")
            job_id = new_job_id # Update job_id to the new one for the next loop iteration
            # Continue to the next iteration to fetch the new job status
            continue 
            
        time.sleep(5)  # Wait before next check