​
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/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/startKYCAgentJob (for individuals) or https://api.parcha.ai/startKYBAgentJob (for businesses)
  • Method: POST
  • Authentication: JWT 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 a valid JWT token in the Authorization header: 
Authorization: Bearer <your_jwt_token>
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:
  1. Extract the signature from the X-Parcha-Signature header
  2. Use your API secret key to verify the signature against the payload

​
Best Practices

  1. 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
  2. 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
  3. Security
    • Keep API keys and webhook signing secrets secure
    • Implement proper access controls
    • Validate webhook signatures
    • Follow data retention policies

​
Error Handling

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

​
Support

For additional support: