AML screening - Parcha API Documentation

Overview

AML (Anti-Money Laundering) screening is a critical compliance process that helps identify potential risks associated with individuals and businesses. This guide covers how to integrate and use Parcha’s AML screening capabilities.

Quick Start

POST https://api.parcha.ai/api/v1/startKYCAgentJob

{
  "agent_key": "kyc-standard-check",
  "kyc_schema": {
    "id": "quick-start-example",
    "self_attested_data": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1980-01-01",
      "country_of_residence": "US",
      "address": {
        "street_1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country_code": "US"
      }
    }
  }
}

API Reference

Endpoint Details

URL: https://api.parcha.ai/api/v1/startKYCAgentJob (for individuals) or https://api.parcha.ai/api/v1/startKYBAgentJob (for businesses)
Method: POST
Authentication: API key as Bearer token required
Content-Type: application/json

Response Codes

200 OK: Request successful
400 Bad Request: Invalid input data
401 Unauthorized: Invalid or missing authentication, or insufficient permissions
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server-side error

Response Format

{
  "status": "ok" | "failed",
  "job_id": string,
  "message": string,
  "job": {
    "id": string,
    "status": "PENDING" | "RUNNING" | "COMPLETE",
    "created_at": string,
    "updated_at": string,
    "agent_id": string,
    "input_payload": object
  }
}

Input Requirements

1. Required Fields

Every request must include:

agent_key: The unique identifier for the agent to be used
kyc_schema or kyb_schema: The schema containing the entity information

2. Self-Attested Data

Individual (KYC)

{
  // Required Fields
  first_name: string,                    // First name of individual
  last_name: string,                     // Last name of individual
  
  // Important Optional Fields
  middle_name?: string,                  // Middle name
  date_of_birth?: string,                // YYYY-MM-DD format
  country_of_nationality?: string,        // Country of nationality (e.g., "US")
  country_of_residence?: string,          // Country of residence (e.g., "US")
  place_of_birth?: string,               // Place of birth
  sex?: string,                          // Gender/Sex
  
  // Address Information
  address?: {
    street_1?: string,                   // Street address
    street_2?: string,                   // Additional address info
    city?: string,                       // City
    state?: string,                      // State/Province
    postal_code?: string,                // Postal/ZIP code
    country_code?: string                // ISO country code
  }
}

Business (KYB)

{
  // Required Fields
  business_name: string,                 // Legal business name
  
  // Important Optional Fields
  registered_business_name?: string,     // Registered legal name if different
  incorporation_date?: string,           // YYYY-MM-DD format
  business_registration_number?: string, // Registration/License number
  
  // Address Information
  address_of_incorporation?: {
    street_1?: string,
    street_2?: string,
    city?: string,
    state?: string,
    postal_code?: string,
    country_code?: string
  },
  address_of_operation?: {               // If different from incorporation address
    street_1?: string,
    street_2?: string,
    city?: string,
    state?: string,
    postal_code?: string,
    country_code?: string
  },
  
  // Business Details
  industry?: string,                     // Industry classification
  business_purpose?: string,             // Business description/purpose
  customer_countries?: string[],         // Countries of operation
  tin_number?: string,                   // Tax ID number
  website?: string | string[],           // Business website(s)
  description?: string                   // Business description
}

Screening Types and Vendor Data

1. PEP Screening

Politically Exposed Person (PEP) screening helps identify individuals who hold prominent public functions.

Vendor Data Schema

{
  "vendor_case_id": string,              // Unique ID from vendor's system
  "search_term": string,                 // Search term used for screening
  "potential_pep_hits": [{
    "full_name": string,
    "pep_title": string,
    "pep_type": string,
    "pep_status": "Active" | "Inactive",
    "roles": [{
      "name": string,
      "country": string,
      "start_date": string,              // YYYY-MM-DD
      "end_date": string                // YYYY-MM-DD
    }]
  }]
}

2. Adverse Media Screening

Checks for negative news and adverse media mentions.

Vendor Data Schema

{
  "vendor_case_id": string,
  "search_term": string,
  "vendor_adverse_media_articles": [{
    "adverse_media_article_id": string,
    "article_type": string,
    "source_url": string,
    "source_name": string,
    "text_content": string,
    "publication_date": string,          // YYYY-MM-DD
    "title": string
  }],
  "vendor_adverse_media_profiles": [{
    "reference_id": string,
    "full_name": string,
    "aliases": string[],
    "date_of_birth": string,            // YYYY-MM-DD
    "associated_countries": string[],
    "weblinks": [{
      "url": string,
      "summary": string
    }]
  }]
}

3. Sanctions Screening

Checks individuals and businesses against global sanctions lists.

Vendor Data Schema

{
  "names": string[],                    // Associated names
  "address": string,                    // Associated address
  "source_id": string,                  // ID from sanctions list
  "list_date": string,                  // YYYY-MM-DD
  "urls": string[],                     // Related URLs
  "jurisdiction": string[],             // Jurisdictions
  "sanction_details": string            // Details about the sanction
}

Complete Request Examples

Individual Screening Request

{
  "agent_key": "kyc-standard-check",
  "kyc_schema": {
    "id": "parcha-kyc-test-2",
    "self_attested_data": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1980-01-01",
      "country_of_residence": "US",
      "address": {
        "street_1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country_code": "US"
      }
    },
    "adverse_media_event_check": {
      "vendor_data": {
        "vendor_case_id": "abc123",
        "search_term": "John Doe",
        "vendor_adverse_media_articles": [
          {
            "adverse_media_article_id": "article123",
            "article_type": "News",
            "source_url": "https://example.com/article1",
            "source_name": "Example News",
            "text_content": "Article content...",
            "publication_date": "2023-01-15",
            "title": "Example Article"
          }
        ]
      }
    },
    "pep_screening_check_v2": {
      "vendor_data": {
        "vendor_case_id": "pep123",
        "search_term": "John Doe",
        "potential_pep_hits": [
          {
            "full_name": "John G. Doe",
            "pep_title": "State Senator",
            "pep_type": "Politician",
            "pep_status": "Active",
            "roles": [
              {
                "name": "Senator",
                "country": "US",
                "start_date": "2020-01-01",
                "end_date": "2024-01-01"
              }
            ]
          }
        ]
      }
    }
  }
}

Business Screening Request

{
  "agent_key": "kyb-standard-check",
  "kyb_schema": {
    "id": "parcha-kyb-test-1",
    "self_attested_data": {
      "business_name": "Acme Corp",
      "registered_business_name": "Acme Corporation Inc.",
      "incorporation_date": "2010-01-01",
      "address_of_incorporation": {
        "street_1": "456 Business Ave",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country_code": "US"
      },
      "industry": "Technology",
      "business_purpose": "Software Development",
      "website": "https://www.acmecorp.com"
    }
  }
}

Business Screening Request with Vendor Data

{
  "agent_key": "kyb-standard-check",
  "kyb_schema": {
    "id": "parcha-kyb-test-1",
    "self_attested_data": {
      "business_name": "Lukoil",
      "registered_business_name": "PJSC Lukoil Oil Company",
      "address_of_incorporation": {
        "street_1": "Sretensky Boulevard, 11",
        "city": "Moscow",
        "state": null,
        "country_code": "RU",
        "postal_code": "101000"
      },
      "address_of_operation": {
        "street_1": "Sretensky Boulevard, 11",
        "city": "Moscow",
        "state": null,
        "country_code": "RU",
        "postal_code": "101000"
      },
      "website": "https://www.lukoil.com/",
      "business_purpose": "Oil and Gas Production",
      "description": "LUKOIL is one of the largest publicly traded, vertically integrated oil and gas companies",
      "industry": "Oil and Gas",
      "tin_number": "123456789"
    },
    "sanctions_watchlist_check": {
      "vendor_data": {
        "vendor_case_id": "sanctions123",
        "search_term": "PJSC Lukoil Oil Company",
        "sanctions_data": [
          {
            "names": ["PJSC Lukoil Oil Company", "Lukoil", "LUKOIL"],
            "address": "Sretensky Boulevard, 11, Moscow, Russia, 101000",
            "source_id": "OFAC-12345",
            "list_date": "2022-03-15",
            "urls": [
              "https://sanctionslist.example.com/lukoil"
            ],
            "jurisdiction": ["US", "EU"],
            "sanction_details": "Sanctioned under Executive Order 14024 for operating in the energy sector of the Russian Federation economy"
          }
        ]
      }
    },
    "adverse_media_check": {
      "vendor_data": {
        "vendor_case_id": "media123",
        "search_term": "Lukoil",
        "vendor_adverse_media_articles": [
          {
            "adverse_media_article_id": "article123",
            "article_type": "News",
            "source_url": "https://example.com/news/lukoil-sanctions",
            "source_name": "Example News",
            "text_content": "Lukoil faces international sanctions...",
            "publication_date": "2022-03-16",
            "title": "Lukoil Added to International Sanctions List"
          }
        ]
      }
    }
  }
}

Business Screening Request with Associated Individuals

{
  "agent_key": "kyb-standard-check",
  "kyb_schema": {
    "id": "brex-agent-group-test",
    "self_attested_data": {
      "business_name": "Brex",
      "registered_business_name": "Brex Inc.",
      "address_of_operation": {
        "street_1": "405 Howard St",
        "street_2": "Suite 100",
        "city": "San Francisco",
        "state": "CA",
        "country_code": "US",
        "postal_code": "94105"
      },
      "address_of_incorporation": {
        "street_1": "251 Little Falls Drive",
        "city": "Wilmington",
        "state": "DE",
        "country_code": "US",
        "postal_code": "19808"
      },
      "website": [
        "https://www.brex.com",
        "https://x.com/brexHQ",
        "https://www.crunchbase.com/organization/brex"
      ],
      "business_purpose": "Financial Services",
      "description": "Brex offers business credit cards and cash management accounts for startups.",
      "industry": "Financial Services",
      "tin_number": "81-3954667",
      "partners": ["Y Combinator"],
      "customers": ["Airbnb", "Carta", "DoorDash"],
      "source_of_funds": ["Investment", "Revenue"]
    },
    "associated_individuals": [
      {
        "id": "brex-kyc-test-1",
        "self_attested_data": {
          "first_name": "Pedro",
          "last_name": "Franceschi",
          "date_of_birth": "1997-06-15",
          "address": {
            "street_1": "5678 Broadway",
            "city": "San Francisco",
            "state": "CA",
            "country_code": "US",
            "postal_code": "94133"
          },
          "country_of_nationality": "BR",
          "country_of_residence": "US",
          "title": "Co-CEO",
          "is_business_owner": true,
          "business_ownership_percentage": 0.50
        }
      }
    ],
    "sanctions_watchlist_check": {
      "vendor_data": {
        "vendor_case_id": "sanctions456",
        "search_term": "Brex Inc.",
        "sanctions_data": []  // No sanctions found
      }
    },
    "adverse_media_check": {
      "vendor_data": {
        "vendor_case_id": "media456",
        "search_term": "Brex Inc.",
        "vendor_adverse_media_articles": [
          {
            "adverse_media_article_id": "article789",
            "article_type": "News",
            "source_url": "https://example.com/news/brex-layoffs",
            "source_name": "Tech News",
            "text_content": "Brex conducts layoffs amid market downturn...",
            "publication_date": "2023-03-15",
            "title": "Brex Announces Workforce Reduction"
          }
        ]
      }
    }
  }
}

Authentication and Security

Authentication

All requests must include your API key in the Authorization header as a Bearer token:

Authorization: Bearer <your_api_key>

To obtain an API key, log into your Parcha account and navigate to the API Keys section in your account settings. The API uses role-based access control. Users must have appropriate permissions to access specific agents and endpoints.

Rate Limits

PEP screening has a concurrent request limit
Extraction operations have separate rate limits
Rate limits are enforced per agent and per operation type

Webhooks

Parcha uses signed webhooks for secure delivery of screening results. Webhook payloads are signed using your API secret key. To verify webhook signatures:

Extract the signature from the X-Parcha-Signature header
Use your API secret key to verify the signature against the payload

Best Practices

Data Quality
- Provide as much information as possible for better matching
- Use standardized formats for dates (YYYY-MM-DD) and country codes
- Include all known aliases and alternative names
Performance
- Use the run_in_parallel flag for parallel processing
- Implement appropriate retry logic with exponential backoff
- Monitor webhook deliveries and implement proper error handling
Security
- Keep API keys and webhook signing secrets secure
- Implement proper access controls
- Validate webhook signatures
- Follow data retention policies

Error Handling

Common Errors
- Invalid input data: Check required fields and data formats
- Authentication errors: Verify API key and permissions
- Rate limit exceeded: Implement appropriate backoff strategy
Best Practices
- Implement retry logic for transient failures
- Log detailed error information for debugging
- Monitor webhook delivery failures

Support

For additional support:

Technical Documentation: docs.parcha.ai
API Status: status.parcha.ai
Email Support: support@parcha.ai

​Overview

​Quick Start

​API Reference

​Endpoint Details

​Response Codes

​Response Format

​Input Requirements

​1. Required Fields

​2. Self-Attested Data

​Individual (KYC)

​Business (KYB)

​Screening Types and Vendor Data

​1. PEP Screening

​Vendor Data Schema

​2. Adverse Media Screening

​Vendor Data Schema

​3. Sanctions Screening

​Vendor Data Schema

​Complete Request Examples

​Individual Screening Request

​Business Screening Request

​Business Screening Request with Vendor Data

​Business Screening Request with Associated Individuals

​Authentication and Security

​Authentication

​Rate Limits

​Webhooks

​Best Practices

​Error Handling

​Support

Overview

Quick Start

API Reference

Endpoint Details

Response Codes

Response Format

Input Requirements

1. Required Fields

2. Self-Attested Data

Individual (KYC)

Business (KYB)

Screening Types and Vendor Data

1. PEP Screening

Vendor Data Schema

2. Adverse Media Screening

Vendor Data Schema

3. Sanctions Screening

Vendor Data Schema

Complete Request Examples

Individual Screening Request

Business Screening Request

Business Screening Request with Vendor Data

Business Screening Request with Associated Individuals

Authentication and Security

Authentication

Rate Limits

Webhooks

Best Practices

Error Handling

Support