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
Contact Parcha support to obtain your API key and agent key. These credentials are required for all API calls.
Never share your API key or agent key. Keep them secure and use environment variables or secure secret management systems to store them.

​
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
Make sure to include all required fields for the checks you plan to run. See the Check Requirements table for details.

​
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
If a job status is RETRIED, the response will include a new_job_id field. You should use this new ID to call /getJobById again to get the status of the current job. The new job will also contain an original_job_id field, pointing back to the job that was retried.

​
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

API Reference

View the complete API documentation for all endpoints and features.