This guide outlines practical applications of the Parcha API, demonstrating how to leverage our endpoints for various compliance and due diligence scenarios. Let’s explore a common use case: document remediation.

​
Document Remediation

Document remediation is a crucial step in many KYB (Know Your Business) processes. It involves verifying the validity and authenticity of documents provided by businesses. Let’s look at how you can use Parcha’s API to streamline this process, focusing on proof of address verification.

​
Approach A: Multi-Step Process

This approach utilizes multiple API endpoints for a granular, step-by-step process.

​
Step 1: Upload the Document

First, use the document upload endpoint to securely store the document in our system. 
curl -X POST 'https://demo.parcha.ai/api/v1/uploadB64Document' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "b64_document": "base64_encoded_document_content",
  "document_name": "proof_of_address.pdf"
}'

​
Step 2: Run the Proof of Address Verification Check

Using the URL returned from the document upload, initiate the verification check. 
curl -X POST 'https://demo.parcha.ai/api/v1/runCheck' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "agent_key": "your-agent-key",
  "check_id": "kyb.proof_of_address_verification",
  "payload": {
    "id": "unique-case-id",
    "self_attested_data": {
      "self_attested_data": {
      "business_name": "Parcha",
      "registered_business_name": "Parcha Labs Incorporated",
      "address_of_operation": {
        "street_1": "755 Sansome St",
        "street_2": "Suite 350",
        "city": "San Francisco",
        "state": "CA",
        "country_code": "US",
        "postal_code": "94111"
      },
      "proof_of_address_documents": [
        {
          "file_url": "DOCUMENT_URL_FROM_STEP_1"
        }
      ]
    }
  },
  "check_args": {
    "validity_period": 90,
    "accepted_document_types": [
      "Bank statement",
      "VAT invoice",
      "Utility bill",
      "Signed tenancy or lease agreement",
      "Tax document",
      "Mortgage statement",
      "Credit card statement",
      "Home or renter's insurance policy"
    ]
  }
}'

​
Step 3: Poll for Job Status

Regularly check the status of the job using the job ID returned from the previous step. 
curl 'https://demo.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'

​
Step 4: Process the Results

Once the job is completed, examine the results to determine if the document is validated or if there’s feedback to provide to the customer.
Python
if job_data['status'] == 'COMPLETED':
    check_result = job_data['check_results'][0]  # Assuming there's only one check
    if check_result['passed']:
        print("Document validated successfully!")
    else:
        follow_up = check_result.get('follow_up', 'Document validation failed.')
        print(f"Document validation failed. Feedback: {follow_up}")

​
Approach B: Streamlined Single-Call Process

This approach utilizes an undocumented feature that allows for a more streamlined process using a single API call. 
curl -X POST 'https://demo.parcha.ai/api/v1/runCheck' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "agent_key": "your-agent-key",
  "kyb_schema": {
    "id": "unique-case-id",
    "self_attested_data": {
    "self_attested_data": {
      "business_name": "Parcha",
      "registered_business_name": "Parcha Labs Incorporated",
      "address_of_operation": {
        "street_1": "755 Sansome St",
        "street_2": "Suite 350",
        "city": "San Francisco",
        "state": "CA",
        "country_code": "US",
        "postal_code": "94111"
      },
      "proof_of_address_documents": [
        {
          "document_type": "proof_of_address",
          "file_name": "proof_of_address.pdf",
          "b64_document": "base64_encoded_document_content"
        }
      ]
    }
  },
  "check_id": "kyb.proof_of_address_verification",
  "check_args": {
    "validity_period": 90,
    "accepted_document_types": [
        "Bank statement",
        "VAT invoice",
        "Utility bill",
        "Signed tenancy or lease agreement",
        "Tax document",
        "Mortgage statement",
        "Credit card statement",
        "Home or renter's insurance policy"
    ]
  }
}'
After initiating the job with this single call, you can proceed to poll for the job status and process the results as described in Steps 3 and 4 of Approach A. Both approaches offer effective ways to handle document remediation:
  • Approach A provides more granular control and is useful when you need to manage documents separately from the verification process.
  • Approach B streamlines the process into a single API call, which can be more efficient for straightforward verifications.
Choose the approach that best fits your workflow and integration needs. Remember to always handle sensitive document data securely and in compliance with relevant data protection regulations.

​
Prevalidate Document prior to running full verification

You can prevalidate a document prior to running the full verification by using the runCheck endpoint but disabling all verification flags and setting the enable_visual_verification and enable_fraud_check options to False. When you do this the document will only be checked to make sure it is a valid document type for that check. 

import requests
import time

API_KEY = 'YOUR_API_KEY'
AGENT_KEY = 'agent-key'
BASE_URL = 'https://demo-ext.parcha.ai'
HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}

# Run initial incorporation document verification
run_check_response = requests.post(
    f'{BASE_URL}/runCheck',
    headers=HEADERS,
    json={
        "agent_key": AGENT_KEY,
        "check_id": "kyb.incorporation_document_verification",
        "case_id": "your_case_id",
        "case_type": "kyb",
        "check_args": {
            "enable_visual_verification": False,
            "enable_fraud_check": False,
            "verify_incorporation_date": False,
            "verify_registration_number": False,
            "verify_address": False,
            "verify_no_high_risk_fraud": False
        }
    }
)

run_check_response.raise_for_status()
job_id = run_check_response.json()['id']

# Poll for the job completion
while True:
    job_response = requests.get(
        f'{BASE_URL}/getJobById',
        headers=HEADERS,
        params={
            'job_id': job_id,
            'include_check_results': 'true'
        }
    )
    job_response.raise_for_status()

    job_data = job_response.json()

    if job_data['status'].lower() == 'complete':
        break

    time.sleep(5)  # poll every 5 seconds

# Extract result
check_results = job_data['check_results']
doc_verification_result = next(
    (result for result in check_results if result['command_id'] == 'kyb.incorporation_document_verification'),
    None
)

is_valid = doc_verification_result['payload']['documents'][0]['is_valid_document']

if not is_valid:
    print("Incorporation document is invalid.")
else:
    print("Incorporation document is valid.")

​
Example: Incorporation Document Verification

Verifying incorporation documents is a crucial step in the KYB process. This example demonstrates how to use the Parcha API to verify incorporation documents using a webhook for efficient result handling.

​
Step 1: Prepare Document Data and Run Verification

Use the runCheck endpoint to initiate the incorporation document verification process. 
curl -X POST 'https://demo.parcha.ai/api/v1/runCheck' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "agent_key": "your-agent-key",
  "kyb_schema": {
    "id": "unique-case-id",
    "self_attested_data": {
      "registered_business_name": "Example Business Inc.",
      "description": "A company specializing in software development",
      "incorporation_date": "2023-01-01",
      "address_of_incorporation": {
        "street_1": "123 Main St",
        "street_2": "",
        "city": "Anytown",
        "state": "AN",
        "country_code": "US",
        "postal_code": "12345"
      },
      "incorporation_documents": [
        {
          "document_type": "certificate_of_incorporation",
          "file_name": "incorporation_certificate.pdf",
          "b64_document": "BASE64_ENCODED_DOCUMENT_CONTENT"
        }
      ]
    }
  },
  "check_id": "kyb.incorporation_document_verification",
  "check_args": {
    "enable_visual_verification": true,
    "enable_fraud_check": true,
    "verify_incorporation_date": true,
    "verify_registration_number": false,
    "verify_address": false,
    "verify_no_high_risk_fraud": false
  },
  "webhook_url": "https://your-webhook-url.com/callback"
}'
Note on Verification Options:
  1. enable_visual_verification (default: True)
    • Uses a vision language model to analyze the document visually.
    • Detects official seals, signatures, and other visual elements.
    • Reference images of seals and signatures can be provided for specific document types.
    • Adds approximately 15-30 seconds of latency to the process.
  2. enable_fraud_check (default: False)
    • Runs sophisticated fraud and tampering analysis on the document metadata.
    • Adds about 1-2 minutes of latency to the process.
  3. verify_incorporation_date (default: True)
    • The check will fail if there are significant discrepancies in the incorporation date.
  4. verify_registration_number (default: False)
    • The check will fail if there are significant discrepancies in the registration number.
  5. verify_address (default: False)
    • The check will fail if there are significant discrepancies in the address.
  6. verify_no_high_risk_fraud (default: False)
    • The check will fail if HIGH_RISK indicators are detected in the document metadata.
Important Notes:
  • By default, without these options enabled, the system performs an OCR-based check using LLMs to extract text from the document and analyze it.
  • Consider the trade-off between thoroughness and speed when deciding which options to enable for your use case.
  • Each verification option adds an additional layer of scrutiny but may increase processing time.

​
Step 2: Set Up Webhook to Receive Results

Create an endpoint on your server to receive the webhook callback. Here’s an example using Express.js. For more detailed information about webhooks, refer to the Webhooks section: 
const express = require('express');
const app = express();
app.use(express.json());

app.post('/callback', (req, res) => {
  const jobData = req.body;
  
  if (jobData.status === 'complete') {
    const incorporationCheck = jobData.check_results.find(
      check => check.command_id === 'kyb.incorporation_document_verification'
    );
    
    if (incorporationCheck) {
      console.log('Incorporation Document Verification Result:', check);
      
      // Process the result as needed
      if (check.passed) {
        console.log('Document is valid');
        // Perform actions for valid document
      } else {
        console.log('Document is invalid');
        // Handle invalid document case
      }
    }
  }
  
  res.sendStatus(200);
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

​
Step 3: Process the Results

In your webhook handler, process the results of the incorporation document verification: 
if (incorporationCheck) {
  const result = incorporationCheck.command_result.output.payload;
  
  console.log('Document Validity:', result.is_valid);
  console.log('Visual Verification Result:', result.visual_verification_result);
  console.log('Fraud Check Result:', result.fraud_check_result);
  
  if (result.is_valid) {
    console.log('Incorporation Date:', result.incorporation_date);
    console.log('Company Name:', result.company_name);
    console.log('Registration Number:', result.registration_number);
  } else {
    console.log('Verification Failed. Reason:', result.failure_reason);
  }
  
  // Take appropriate action based on the results
}