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
  • 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:
        response = requests.get(
            f'https://api.parcha.ai/getJobById?job_id={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('Job failed')
            
        time.sleep(5)  # Wait before next check

API Reference

View the complete API documentation for all endpoints and features.