# Check Result Object Source: https://docs.parcha.ai/api-reference/check-result Response schema for check results When you fetch the results of a Job using the `/getJobById` or `/getJobByCaseId` endpoint, the response will contain a check result object with metadata about the check execution and a check-specific payloads for each check that was run. You can find the results of a specific check by filtering the `command_name` in the response. The unique identifier of the agent. The unique identifier for this instance of the agent. The unique identifier of the command. The name of the command. A description of what the command does. The unique identifier for this instance of the command. The identifier of the data loader used, if any. The identifier of the job this check result belongs to. The timestamp when the check result was created. The timestamp when the check result was last updated. The timestamp when the data loader started, if applicable. The timestamp when the data loader finished, if applicable. The timestamp when the check started. The timestamp when the check finished. The type of result, typically "CommandResult". The current status of the check result (e.g., "pending", "complete", "failed"). The step number in the workflow, if applicable. The input data used for the check. The verification data used for the check. Input data will be compared against this data. Whether the check passed. A human-readable summary of the check result. A detailed explanation of what was checked and how the result was determined. Check-specific result data. The structure of this object varies depending on the type of check that was run. See the individual check result documentation for details: * [EIN Document Verification Result](/api-reference/check-results/ein-document-verification) * [Incorporation Document Verification Result](/api-reference/check-results/incorporation-document-verification) * [Proof of Address Document Verification Result](/api-reference/check-results/proof-of-address-document-verification) * [Business Ownership Document Verification Result](/api-reference/check-results/business-ownership-document-verification) An object containing any alerts or warnings generated during the check. A recommended action based on the check result. Any instructions related to the check. Any follow-up actions that should be taken. Any evidence collected during the check. Any error that occurred during the check. An array of status messages emitted during the execution of the check. ### Example Response ```json theme={null} { "jobs": [ { "id": "539108a4-3a19-4ecf-88d0-a6468194cedc", ... "check_results": [ /* list of check_result objects */ { /* general info */ "agent_key": "agent-kyb-v1", "agent_instance_id": "9db890b9-2d9d-4e4f-a802-18ecef5d72b3", "command_id": "kyb.incorporation_document_verification", "command_name": "Incorporation Document Check", "command_desc": "A tool to verify a business registration/formation documents provided by applicant and extracting relevant data", "command_instance_id": "b3a753c2-500f-4043-93e4-802554635213", "data_loader_id": null, "job_id": "539108a4-3a19-4ecf-88d0-a6468194cedc", "created_at": "2024-11-08T20:19:47.959210", "updated_at": "2024-11-08T20:21:40.430984", "data_loader_start_time": "2024-11-08T20:19:49.046128", "data_loader_end_time": "2024-11-08T20:21:02.267585", "check_start_time": "2024-11-08T20:21:02.299008", "check_end_time": "2024-11-08T20:21:40.372310", "result_type": "CommandResult", "status": "complete", "step_number": null, /* check result specific info */ "input_data": { input data }, "verification_data": { verification data }, "passed": false, "answer": "The business registration verification has failed due to critical discrepancies in the registration number, high-risk fraud indicators, and failed visual inspection of the provided document.", "explanation": "This task involves verifying the business registration information provided by the applicant against the documented incorporation information extracted from the submitted documents.", "payload": { check output }, "alerts": { "registration_number": "The self-attested registration number does not match the documented number.", }, "recommendation": "Failed", "instructions": null, "follow_up": "", "evidence": null, "error": null, /* status messages emitted during the execution of the check */ "status_messages": [ { status message }, ... ] }, ... ] }, ... ], "count": 4 } ``` # Adverse Media Screening Check Source: https://docs.parcha.ai/api-reference/check-results/adverse-media-screening-check Identify potential risks by analyzing news articles, media coverage, and customer reviews related to a business The adverse media screening check analyzes news articles, media coverage, and other public sources to identify potential risks or concerns associated with a business. The check searches multiple data sources including Refinitiv World Check, ComplyAdvantage, and Google News to build comprehensive adverse media profiles. ## Check ID `kyb.adverse_media_screening_check_v2` ## Response Structure The check result contains a list of verified adverse media hits, where each hit represents a business profile found in adverse media sources along with detailed article information and metadata. ```typescript theme={null} { type: "KYBAdverseMediaScreeningCheckResultV2"; verified_adverse_media_hits: Array; } ``` ### BusinessAdverseMediaProfile Structure Each adverse media profile contains comprehensive information about a business found in adverse media sources: ```typescript theme={null} { // Identification id: string; // Short unique identifier (8 characters) reference_id: string | null; // External reference ID from data source business_name: string | null; // Name of the business in the profile // Geographic Information associated_countries: Array; associated_addresses: Array
; location: string | null; // e.g., "Houston, TX" // Weblinks and Articles weblinks: Array; // Detailed article references with metadata // Classification is_perpetrator: boolean | null; // Whether business is perpetrator of the event topics: Array; // Event topics (e.g., "Regulatory Violations", "Legal Disputes") title: string | null; // Brief title summarizing the event summary: string | null; // Summary of the adverse media event when: string | null; // When the event occurred // Matching and Review profile_review: BusinessProfileReview; // Match analysis and ratings escalate_for_review: boolean; // Whether to escalate for manual review vendor: string | null; // Data source vendor (e.g., "refinitiv_world_check") } ``` ### Weblink Structure Each weblink represents a specific article or source with full metadata: ```typescript theme={null} { // Identification id: string; // Unique ID (6 characters) url: string | null; // Article URL title: string | null; // Article title // Temporal and Geographic Data date: string | null; // Date from the weblink when: string | null; // When the event occurred (e.g., "2025") where_countries: Array; // Countries mentioned in article where_cities: Array; // Cities mentioned in article // Content summary: string | null; // Summary of the article scanned_website: ScannedWebsite; // Full scraped webpage content metadata: BusinessArticleMetadataV1; // Structured article metadata // Source Information article_source: ArticleSource; // Source type (e.g., "serp_google_search", "refinitiv_world_check") // Status has_photo: boolean | null; is_dead_url: boolean | null; } ``` ### BusinessArticleMetadataV1 Structure Detailed metadata extracted from each article using LLM analysis: ```typescript theme={null} { type: "BusinessArticleMetadataV1"; id: string; // Article Classification adverse_media_article_title: string | null; is_adverse_media_article: boolean; // Whether this is adverse media topics: Array | null; // Topics like "Regulatory Violations", "Legal Disputes" // Business Involvement is_perpetrator: boolean; // Whether business is the perpetrator is_hit_business_name_found: boolean; // Whether business name was found in article hit_business_name_value_found: string | null; // Exact business name found // Geographic Context associated_addresses: Array
; associated_countries: Array; // Temporal Context year_of_the_crime: number | null; // Year the event occurred year_of_article_publication: number | null; // Year article was published // Event Details summary_of_event: string | null; // Summary of the main event summary_of_relation_to_crime: string | null; // How business relates to the event quote_from_article: string | null; // Direct quote from the article source_url: string | null; // Article URL } ``` ### ScannedWebsite Structure Raw scraped content from the webpage: ```typescript theme={null} { type: "ScannedWebsite"; source_id: string; // Unique source ID (6 characters) source_name: string | null; // Name of the source webpage_url: string | null; // URL of the webpage webpage_title: string | null; // Page title webpage_text: string | null; // Full text content screenshot_url: string | null; // Screenshot URL pdf_snapshot_url: string | null; // PDF snapshot URL response_code: number; // HTTP response code is_valid_url: boolean | null; // Whether URL is accessible language: string | null; // Language of the content publication_date: string | null; // Publication date scrape_type: ScrapeType; // Type of scrape ("generic", etc.) error: string | null; // Error message if scraping failed cloudflare_encountered: boolean; // Whether Cloudflare protection was encountered } ``` ### BusinessProfileReview Structure Match analysis and confidence scoring: ```typescript theme={null} { id: string; // Review ID (8 characters) business_name_match: BusinessNameMatch | null; // Business name match result address_matches: Array | null; // Address match results best_address_match: AddressMatch | null; // Best matching address match_rating: HitMatch | null; // Overall match confidence } ``` ### Match Rating System The `match_rating` field uses the following enum values: * **`strong_match`**: High confidence that the adverse media refers to the screened business * Business name matches closely * Location matches * Other identifying details align * **`partial_match`**: Moderate confidence in the match * Business name is similar but not exact * Some geographic or contextual alignment * May require manual review * **`weak_match`**: Low confidence in the match * Name similarity is limited * Location may not match * Likely a different business with a similar name * **`no_match`**: Clear mismatch * Business name is significantly different * Location doesn't match * Context clearly indicates a different entity * **`unknown`**: Unable to determine match confidence * Insufficient information available * Ambiguous details ## Example Response ```json theme={null} { "type": "KYBAdverseMediaScreeningCheckResultV2", "verified_adverse_media_hits": [ { "id": "tm2m3kdz", "reference_id": null, "business_name": "Empower Pharmacy", "associated_countries": [ { "original_country_input": "United States", "country_name": "United States of America", "alpha_2_country_code": "US", "alpha_3_country_code": "USA", "numeric_country_code": "840" } ], "associated_addresses": [ { "type": "Address", "street_1": null, "street_2": null, "city": "Houston", "state": null, "country_code": "US", "postal_code": null } ], "weblinks": [ { "id": "ijbjo6cc", "url": "https://lawgaze.com/empower-pharmacy-lawsuit/", "date": null, "has_photo": null, "is_dead_url": null, "summary": "Empower Pharmacy is the defendant in regulatory disputes with the FDA over alleged sterility concerns, labeling violations, and compliance failures.", "when": "2025", "where_countries": ["United States"], "where_cities": ["Houston"], "scanned_website": { "type": "ScannedWebsite", "source_id": "nbxery", "webpage_url": null, "webpage_title": "Empower Pharmacy Lawsuit: FDA Disputes and Legal Battles", "response_code": 200, "scrape_type": "generic", "cloudflare_encountered": false, "error": null }, "metadata": { "type": "BusinessArticleMetadataV1", "id": "ijbjo6cc", "topics": ["Regulatory Violations", "Legal Disputes", "Compliance Issues"], "adverse_media_article_title": "Empower Pharmacy Lawsuit: FDA Disputes and Legal Battles", "is_adverse_media_article": true, "is_perpetrator": false, "is_hit_business_name_found": true, "hit_business_name_value_found": "Empower Pharmacy", "associated_addresses": [ { "type": "Address", "street_1": null, "street_2": null, "city": "Houston", "state": "Texas", "country_code": "US", "postal_code": null } ], "associated_countries": ["United States"], "year_of_the_crime": 2025, "year_of_article_publication": 2025, "summary_of_relation_to_crime": "Empower Pharmacy is the defendant in regulatory disputes with the FDA over alleged sterility concerns, labeling violations, and compliance failures.", "summary_of_event": "The FDA has alleged that Empower Pharmacy, one of the largest compounding pharmacies in the US, has violated regulations regarding sterility standards, labeling compliance, and drug manufacturing practices.", "source_url": "https://lawgaze.com/empower-pharmacy-lawsuit/", "quote_from_article": "Empower Pharmacy, one of the largest compounding pharmacies in the United States, has found itself at the center of a legal storm." }, "title": "Empower Pharmacy Lawsuit: FDA Disputes and Legal Battles", "article_source": "serp_google_search" } ], "is_perpetrator": null, "topics": [], "title": null, "summary": null, "when": null, "profile_review": { "id": "abc123de", "business_name_match": null, "address_matches": null, "best_address_match": null, "match_rating": { "match": "partial_match", "reason": "Business name matches, location matches, but needs manual review" } }, "escalate_for_review": true, "vendor": null } ] } ``` ## Response Fields Always `"KYBAdverseMediaScreeningCheckResultV2"`. List of verified adverse media profiles for the business. Each profile represents a business found in adverse media sources. Short unique identifier (8 characters) for this profile. External reference ID from the data source (e.g., Refinitiv World Check ID). Name of the business in the adverse media profile. Countries associated with the business in the adverse media. Full country name (e.g., "United States of America"). ISO 3166-1 alpha-2 code (e.g., "US"). ISO 3166-1 alpha-3 code (e.g., "USA"). Addresses associated with the business in the adverse media. City name. State or province. ISO 3166-1 alpha-2 country code. Array of article references with detailed metadata. See [Weblink Structure](#weblink-structure) above. URL of the article or source. Title of the article. Summary of the article content. When the event occurred (e.g., "2025", "2024-2025"). Countries mentioned in the article. Cities mentioned in the article. Structured metadata extracted from the article using LLM analysis. Event topics (e.g., "Regulatory Violations", "Legal Disputes", "Compliance Issues"). Whether this is classified as adverse media. Whether the business is the perpetrator of the event described. Year when the event occurred. Year when the article was published. Summary of the main event described in the article. Summary of how the business relates to the event. Direct quote from the article about the business. Source of the article. Possible values: * `serp_google_search` - Google Search results * `serp_google_news` - Google News * `refinitiv_world_check` - Refinitiv World-Check * `comply_advantage` - ComplyAdvantage * Other source identifiers Whether the business is the perpetrator of the adverse event. Match analysis and confidence scoring for this profile. Overall match confidence rating. Match strength: `strong_match`, `partial_match`, `weak_match`, `no_match`, or `unknown`. Explanation for the match rating. Whether this profile should be escalated for manual review based on match ratings and risk thresholds. ## Article Sources The check aggregates adverse media from multiple sources: ### Primary Data Sources * **Refinitiv World-Check** (`refinitiv_world_check`) * Global risk intelligence database * PEPs, sanctions, and adverse media * **ComplyAdvantage** (`comply_advantage`) * Real-time risk database * Comprehensive adverse media coverage ### Search Engine Sources * **Google Search** (`serp_google_search`) * Web search results for adverse media * Broad coverage of online content * **Google News** (`serp_google_news`) * News-specific search results * Recent and archived news articles * **Brave Search** (`serp_brave_search`, `serp_brave_news`) * Privacy-focused search engine results ### Other Sources * **Opoint** (`opoint`) * Specialized adverse media intelligence * **Other** (`other`) * Miscellaneous or unclassified sources ## Key Components ### Article Metadata Extraction Each article undergoes LLM-powered analysis to extract: 1. **Event Classification**: Topics and categories (regulatory, legal, financial, etc.) 2. **Business Involvement**: Whether business is perpetrator, victim, or mentioned 3. **Geographic Context**: Countries and cities mentioned 4. **Temporal Context**: When the event occurred and when it was published 5. **Relationship Analysis**: How the business relates to the adverse event 6. **Evidence Extraction**: Direct quotes and summaries ### Match Confidence Scoring The system evaluates multiple factors to determine match confidence: * Business name similarity and exact matches * Geographic alignment (addresses, cities, countries) * Contextual relevance * Article quality and recency * Source reliability ### Escalation Logic Profiles are escalated for manual review based on: 1. **Match Rating**: Strong and partial matches typically escalated 2. **Event Severity**: Regulatory violations, criminal activity, major fraud 3. **Recency**: Recent events (within last 2-5 years) 4. **Volume**: Multiple articles about the same event 5. **Source Quality**: Articles from reputable sources ## Common Topics Articles are categorized into topics such as: * **Regulatory Violations**: FDA warnings, compliance failures, regulatory actions * **Legal Disputes**: Lawsuits, legal battles, civil litigation * **Compliance Issues**: Failure to meet standards, policy violations * **Safety Issues**: Product safety, public health concerns * **Financial Misconduct**: Fraud, embezzlement, financial crimes * **Criminal Activity**: Criminal charges, investigations * **Operational Problems**: Business failures, bankruptcy * **Reputational Concerns**: Scandals, negative publicity ## Implementation Details ### Pydantic Schema Location * **Main Schema**: `ai/data_loaders/schema/kyb_schema.py` * **Base Classes**: `ai/data_loaders/schema/base.py` * **Models**: `ai/tools/bdd/bdd_models.py` ### Data Loader `ai/data_loaders/kyb_adverse_media_profile_loader_v2.py` ### Tool Implementation `ai/tools/kyb/kyb_adverse_media_screening_check_v2.py` ## Filtering Examples Use JSONPath queries to extract specific fields from the check results: ```bash theme={null} # Get only articles from Google Search ?jsonpath_query=$.check_results[?(@.command_id=='kyb.adverse_media_screening_check_v2')].payload.verified_adverse_media_hits[*].weblinks[?(@.article_source=='serp_google_search')] # Get only articles where business is the perpetrator ?jsonpath_query=$.check_results[?(@.command_id=='kyb.adverse_media_screening_check_v2')].payload.verified_adverse_media_hits[*].weblinks[?(@.metadata.is_perpetrator==true)] # Extract all article titles ?jsonpath_query=$.check_results[?(@.command_id=='kyb.adverse_media_screening_check_v2')].payload.verified_adverse_media_hits[*].weblinks[*].title # Get articles about regulatory violations ?jsonpath_query=$.check_results[?(@.command_id=='kyb.adverse_media_screening_check_v2')].payload.verified_adverse_media_hits[*].weblinks[?(@.metadata.topics[*]=='Regulatory Violations')] ``` See [getJobById filtering documentation](/api-reference/getJobById#filtering-check-results) for more JSONPath query examples. # Basic Business Profile Check Source: https://docs.parcha.ai/api-reference/check-results/basic-business-profile-check Verify and validate basic business information from web data against self-attested data The basic business profile check response payload contains a detailed analysis of a business's online presence and profile information. The check compares self-attested business data against information found through web research and public sources. ## Check ID `kyb.basic_business_profile_check` ## Response Structure ```typescript theme={null} { type: "BasicBusinessProfileCheckResult"; business_name_match: BusinessNameDocMatch | null; business_description_match: BusinessDescriptionDocMatch | null; business_industry_match: BusinessIndustryDocMatch | null; passed: boolean; } ``` ## Example Response ```json theme={null} { "type": "BasicBusinessProfileCheckResult", "business_name_match": { "text": "Parcha Labs, Inc.", "source_id": "company_website", "analysis": "Exact match with registered business name found on official website" }, "business_description_match": { "text": "Provider of AI-powered compliance and risk management solutions", "source_id": "linkedin_profile", "analysis": "Business description consistent with self-attested information" }, "business_industry_match": { "text": "RegTech / Compliance Software", "source_id": "company_website", "analysis": "Industry classification matches self-attested information" }, "passed": true, "verification_data": { "web_presence": { "source_1": { "text": "Parcha Labs is a leading provider of AI-powered compliance solutions", "source_id": "company_website", "url": "https://parcha.ai/about", "analysis": "Company website confirms business name and description" }, "source_2": { "text": "Parcha Labs, Inc. - AI-driven compliance and risk management platform", "source_id": "linkedin_profile", "url": "https://www.linkedin.com/company/parcha-ai", "analysis": "LinkedIn profile validates business name and description" } } } } ``` ## Response Fields The type identifier for the response. Will be "BasicBusinessProfileCheckResult". Match information for the business name verification. The matched business name text found in the source. Identifier for the source where the name was found. Analysis of the business name match. Match information for the business description verification. The matched business description text found in the source. Identifier for the source where the description was found. Analysis of the business description match. Match information for the business industry verification. The matched industry classification text found in the source. Identifier for the source where the industry was found. Analysis of the industry classification match. Indicates whether the business profile information was successfully verified. Detailed findings from the profile verification process. Information found through web research. Identifier for the source of the information. Relevant text excerpt about the business. URL where the information was found. Analysis of the findings from this source. ## Key Components ### Profile Analysis The check evaluates business information across multiple dimensions: 1. **Business Identity**: * Legal name verification * Name variations and aliases * Brand consistency 2. **Business Description**: * Products and services * Value proposition * Target market * Business model 3. **Industry Classification**: * Primary industry * Sub-industries * Business activities ### Verification Process The check performs the following verifications: 1. Validates business name across multiple sources 2. Cross-references business descriptions 3. Verifies industry classifications 4. Analyzes consistency between sources 5. Evaluates data reliability and freshness ### Data Sources Information is gathered and verified through: 1. **Official Sources**: * Company website * Business registrations * Professional networks 2. **Third-Party Sources**: * Business directories * News articles * Industry databases * Social media platforms # Business Ownership Document Verification Result Source: https://docs.parcha.ai/api-reference/check-results/business-ownership-document-verification Response schema for business ownership document verification checks The Business Ownership Document Verification check returns a detailed analysis of the provided ownership documents and verification results. The check result will be returned in the `payload` field of the check result object. ## Response Schema Type identifier "KYBBusinessOwnershipVerificationResult" List of business owners that were successfully verified Full name of the business owner Ownership percentage (0-100) Number of shares owned Type of owner ("individual" or "entity") Business name if owner\_type is "entity" List of business owners that could not be verified Same structure as verified\_business\_owners List of valid ownership documents that were successfully verified Whether the document is a valid ownership document Detailed analysis of why the document is valid or invalid Summary of the document's contents and purpose Document date in YYYY-MM-DD format Any alerts or warnings about the document List of business owners found in this document Full name of the business owner Ownership percentage (0-100) Number of shares owned Type of owner ("individual" or "entity") Business name if owner\_type is "entity" Total number of shares in the company The original document metadata Type identifier "Document" URL of the document Name of the document file Source type of the document (e.g., "file\_url") List of invalid ownership documents that failed verification Same structure as valid\_documents ### Example Response ```json theme={null} { "type": "KYBBusinessOwnershipVerificationResult", "verified_business_owners": [ { "full_name": "Ajmal Asver", "percentage": 49.0, "shares": 4500000, "owner_type": "individual", "business_name": null }, { "full_name": "Miguel Rios", "percentage": 49.0, "shares": 4500000, "owner_type": "individual", "business_name": null } ], "unverified_business_owners": [], "valid_documents": [ { "is_valid_document": true, "analysis": "This document is a valid stakeholder ledger dated June 17, 2024. It provides detailed information on various stakeholders, including individuals and entities, their outstanding shares, ownership percentages, and fully diluted ownership. The document appears to be comprehensive and official, listing multiple investors and their respective stakes in the company.", "summary": "This document is an All Stakeholder Ledger dated June 17, 2024. It provides a detailed breakdown of ownership for multiple stakeholders in a company. The ledger includes information such as outstanding shares, ownership percentages, fully diluted shares, and cash raised for each stakeholder. It lists both individual and entity owners, providing a comprehensive overview of the company's ownership structure.", "date": "2024-06-17", "alerts": null, "documented_business_owners": [ { "full_name": "Miguel Rios", "percentage": 49.0, "shares": 4500000, "owner_type": "individual", "business_name": null }, { "full_name": "Ajmal Asver", "percentage": 49.0, "shares": 4500000, "owner_type": "individual", "business_name": null }, { "full_name": "GTM Flow", "percentage": 0.0, "shares": 7000, "owner_type": "entity", "business_name": null } ], "total_shares": 9007000, "document": { "type": "Document", "url": "https://storage.googleapis.com/parcha-ai-public-assets/All%20Stakeholders%20Ledger%20June%2017%202024.pdf", "file_name": "Parcha_cap_table.pdf", "source_type": "file_url" } } ], "invalid_documents": [] } ``` # EIN Document Verification Result Source: https://docs.parcha.ai/api-reference/check-results/ein-document-verification Response schema for EIN document verification checks The EIN Document Verification check returns a detailed analysis of the provided EIN documents and verification results. The check result will be returned in the `payload` field of the check result object. ## Check ID `kyb.ein_document_verification` ## Response Schema Type identifier "KYBEINDocumentVerificationResult" The verified EIN number extracted from the document The verified business name extracted from the document The verified business address extracted from the document Type identifier "Address" First line of street address Second line of street address (optional) City name State or province Postal or ZIP code Country code (optional) The date on the document in YYYY-MM-DD format List of valid EIN documents that were successfully verified Type identifier "EINDocumentExtractionResult" Whether the document is a valid EIN document The EIN number extracted from the document The business name extracted from the document The business address extracted from the document Type identifier "Address" First line of street address Second line of street address (optional) City name State or province Postal or ZIP code Country code (optional) The date on the document in YYYY-MM-DD format The type of IRS document (e.g., "IRS Notice CP575A") Whether the IRS logo is present and valid Whether the document layout matches official IRS forms Whether the document appears to be authentic and unaltered Detailed visual inspection results of the document Detailed analysis of why the document is valid or invalid Summary of the document's contents and purpose The original document metadata Type identifier "Document" URL of the document Name of the document file Source type of the document (e.g., "file\_url") Description of the document (optional) Number of pages in the document (optional) List of invalid EIN documents that failed verification Same structure as valid\_documents ### Example Response ```json theme={null} { "type": "KYBEINDocumentVerificationResult", "valid_documents": [ { "type": "EINDocumentExtractionResult", "irs_logo_valid": true, "form_layout_valid": true, "is_authentic_document": true, "inspection": "The input document is a CP575A notice. The IRS logo in the top left corner is identical to the example. The overall layout of the form, including the placement of sections and information, matches the example CP575. The content is consistent with an IRS EIN notice, including the EIN, business name, and address. No obvious signs of alteration or forgery were detected.", "is_valid_document": true, "analysis": "This document is a valid CP575A notice issued by the IRS. It contains all the required elements including the EIN, business name, address, and document date. The format and content are consistent with authentic IRS EIN assignment notices.", "summary": "This document is an official IRS CP575A notice assigning an Employer Identification Number (EIN) to Parcha Labs Inc. It provides the EIN, business details, and important tax filing information.", "ein": "92-3265708", "business_name": "PARCHA LABS INC", "address": { "type": "Address", "street_1": "746 4TH AVE", "street_2": null, "city": "SAN FRANCISCO", "state": "CA", "country_code": null, "postal_code": "94118" }, "document_date": "2023-03-31", "document_type": "IRS Notice CP575A", "document": { "type": "Document", "url": "https://storage.googleapis.com/parcha-ai-public-assets/CP575Notice_Parcha.pdf", "file_name": "Parcha_EIN.pdf", "source_type": "file_url" } } ], "invalid_documents": [], "verified_ein": "92-3265708", "verified_business_name": "PARCHA LABS INC", "verified_address": { "type": "Address", "street_1": "746 4TH AVE", "street_2": null, "city": "SAN FRANCISCO", "state": "CA", "country_code": null, "postal_code": "94118" }, "document_date": "2023-03-31" } ``` # High Risk Country Check Source: https://docs.parcha.ai/api-reference/check-results/high-risk-country-check Verify that a business does not operate in prohibited or high risk countries The high risk country check response payload contains a detailed analysis of a business's operating locations and customer countries. The check evaluates whether the business operates in or has significant connections to countries that are considered high risk or prohibited. ## Check ID `kyb.high_risk_country_tool` ## Response Structure ```typescript theme={null} { type: "HighRiskCountryCheckResult"; verified_country: string | null; verified_customer_countries: Array | null; passed: boolean; } ``` ## Example Response ```json theme={null} { "type": "HighRiskCountryCheckResult", "verified_country": "US", "verified_customer_countries": ["US", "CA", "GB"], "passed": true, "verification_data": { "business_countries": { "source_1": { "text": "Headquartered in San Francisco, California with offices in Toronto and London", "source_id": "company_website", "countries": ["US", "CA", "GB"], "analysis": "The business has confirmed operations in the United States, Canada, and United Kingdom, none of which are high risk or prohibited jurisdictions." } }, "customer_countries": { "source_1": { "text": "We serve customers primarily in North America and Western Europe", "source_id": "terms_of_service", "countries": ["US", "CA", "GB", "FR", "DE"], "analysis": "The business serves customers in low-risk jurisdictions across North America and Western Europe." } } } } ``` ## Response Fields The type identifier for the response. Will be "HighRiskCountryCheckResult". The primary country of operation for the business, verified through documentation and web research. List of countries where the business has confirmed customer operations. Indicates whether the business passed the high risk country check. False if operations are found in prohibited or high risk countries. Detailed findings from the country verification process. Information about countries where the business has physical operations. Identifier for the source of the country information. Relevant text excerpt mentioning the country connection. List of country codes found in the source. Analysis of the country findings from this source. Information about countries where the business serves customers. Identifier for the source of the customer country information. Relevant text excerpt mentioning customer locations. List of country codes where customers are served. Analysis of the customer country findings from this source. ## Key Components ### Country Analysis The check evaluates countries in two main categories: 1. **Business Operations**: Physical presence, incorporation, and primary business activities 2. **Customer Base**: Countries where the business actively serves customers ### Risk Categories Countries are classified into three risk levels: 1. **Prohibited Countries**: Jurisdictions where business operations are not allowed 2. **High Risk Countries**: Jurisdictions requiring enhanced due diligence 3. **Acceptable Countries**: Jurisdictions with standard risk levels ### Verification Process The check performs the following verifications: 1. Analyzes business registration and incorporation documents 2. Reviews website and online presence for operational locations 3. Examines terms of service and customer agreements 4. Verifies against lists of prohibited and high-risk jurisdictions 5. Considers both direct operations and indirect business relationships # High Risk Industry Check Source: https://docs.parcha.ai/api-reference/check-results/high-risk-industry-check Verify that a business does not operate in prohibited or high-risk industries The high risk industry check response payload contains a detailed analysis of a business's industry classification and activities. The response includes verified industry information and overall validation results. ## Check ID `kyb.high_risk_industry_tool_v2` ## Response Structure ```typescript theme={null} { type: "IndustryActivityCheckResult"; verified_industry?: string; verified_business_activity?: string; passed: boolean; } ``` ## Example Response ```json theme={null} { "type": "IndustryActivityCheckResult", "verified_industry": "Financial Technology Services", "verified_business_activity": "Development and provision of business verification and compliance software solutions", "passed": true } ``` ## Response Fields The type identifier for the response. Will be "IndustryActivityCheckResult". The verified industry classification of the business. The verified description of the business's activities and operations. Whether the check passed (business is not in a prohibited or high-risk industry) or failed (business is in a prohibited or high-risk industry). ## Key Components ### Industry Analysis The check evaluates business activities in several dimensions: 1. **Primary Business Activity**: Main industry classification and activities 2. **Secondary Activities**: Additional business lines or services 3. **Industry Relationships**: Connections to regulated or restricted industries ### Risk Categories Industries are classified into three risk levels: 1. **Prohibited Industries**: Sectors where business operations are not allowed, such as: * Adult Entertainment * Illegal Substances * Weapons and Arms * Gambling * Other restricted activities 2. **High Risk Industries**: Sectors requiring enhanced due diligence, such as: * Cryptocurrency * Money Services * Precious Metals * Real Estate * Other regulated industries 3. **Standard Risk Industries**: Sectors with normal risk levels ### Verification Process The check performs the following verifications: 1. Analyzes business registration and licensing documents 2. Reviews website and marketing materials 3. Examines product and service descriptions 4. Verifies against industry classification standards 5. Screens for connections to prohibited or high-risk activities # Incorporation Document Verification Result Source: https://docs.parcha.ai/api-reference/check-results/incorporation-document-verification Response schema for incorporation document verification checks The Incorporation Document Verification check returns a detailed analysis of the provided incorporation documents and verification results. The check result will be returned in the `payload` field of the check result object. ## Check ID `kyb.incorporation_document_verification` ## Response Schema Type identifier "KYBIncorporationDocumentVerificationResult" The verified business name extracted from the document The verified incorporation date in YYYY-MM-DD format The verified business address extracted from the document Type identifier "Address" First line of street address Second line of street address (optional) City name State or province Postal or ZIP code Country code (optional) The verified business activity or purpose extracted from the document The jurisdiction where the business is incorporated The verified business registration number List of valid incorporation documents that were successfully verified Data extracted from the document Whether the document is a valid incorporation document Detailed analysis of why the document is valid or invalid Summary of the document's contents and purpose Document date in YYYY-MM-DD format Business name from the document All business names found in the document Incorporation date in YYYY-MM-DD format Primary business address from the document Same structure as verified\_business\_address All addresses found in the document Address of the registered agent Same structure as verified\_business\_address Address of the incorporator Same structure as verified\_business\_address Business activity or purpose from the document Jurisdiction from the document All registration numbers found in the document The original document metadata Type identifier "Document" URL of the document Name of the document file Source type of the document (e.g., "file\_url") List of invalid incorporation documents that failed verification Same structure as valid\_documents ### Example Response ```json theme={null} { "type": "KYBIncorporationDocumentVerificationResult", "verified_business_name": "Parcha Labs, Inc.", "verified_incorporation_date": "2023-03-29", "verified_business_address": { "type": "Address", "street_1": "251 Little Falls Drive", "street_2": null, "city": "Wilmington", "state": "Delaware", "country_code": "US", "postal_code": "19808" }, "verified_business_activity": "Any lawful act or activity for which corporations may be organized under the Delaware General Corporation Law", "verified_jurisdiction": "Delaware", "verified_registration_number": "7379553", "valid_documents": [ { "extraction_data": { "is_valid_document": true, "analysis": "This is a valid Certificate of Incorporation filed with the Delaware Secretary of State. The document contains all required elements including business name, incorporation date, registered agent address, and filing number. The document was properly filed and authenticated by the Secretary of State.", "summary": "This is a Certificate of Incorporation for Parcha Labs, Inc. filed in Delaware on March 29, 2023. The document establishes the corporation's basic structure, including authorized shares, registered agent, and corporate purpose. It also contains provisions for director liability, indemnification, and forum selection.", "date": "2023-03-29", "business_name": "Parcha Labs, Inc.", "all_business_names": [ "Parcha Labs, Inc." ], "incorporation_date": "2023-03-29", "business_address": { "type": "Address", "street_1": "251 Little Falls Drive", "street_2": null, "city": "Wilmington", "state": "Delaware", "country_code": "US", "postal_code": "19808" }, "all_extracted_addresses": { "registered_agent_address": { "type": "Address", "street_1": "251 Little Falls Drive", "street_2": null, "city": "Wilmington", "state": "Delaware", "country_code": "US", "postal_code": "19808" }, "incorporator_address": { "type": "Address", "street_1": "746 4th Avenue", "street_2": null, "city": "San Francisco", "state": "CA", "country_code": "US", "postal_code": "94118" } }, "business_activity": "Any lawful act or activity for which corporations may be organized under the Delaware General Corporation Law", "jurisdiction": "Delaware", "business_registration_number": [ "7379553", "SR 20231206456" ] }, "document": { "type": "Document", "url": "https://storage.googleapis.com/parcha-ai-public-assets/Parcha_incorporation_doc.pdf", "file_name": "Parcha_incorporation_doc.pdf", "source_type": "file_url" } } ], "invalid_documents": [] } ``` ## Response Fields The type identifier for the response. Will be "KYBIncorporationDocumentVerificationResult". Array of documents that passed all verification checks. Array of documents that failed one or more verification checks. The confirmed business name after verification checks. The confirmed incorporation date after verification checks. The confirmed business address after verification checks. The confirmed business activity type after verification checks. The confirmed legal jurisdiction after verification checks. The confirmed business registration number after verification checks. ## Alerts The check result may include alerts that indicate potential issues or concerns with the submitted documents. Alerts are returned as a dictionary where the key is the alert name and the value is a description explaining why the alert was raised. ### Supported Alerts Raised when a document is marked as invalid in valid\_documents. The alert message specifies what fields are required based on the configuration (business name, incorporation date, incorporation address, registration number). Raised when required fields are missing from the document based on the configuration. The alert message lists the specific missing fields. Raised when fraud\_verification\_data indicates document tampering. The alert message includes the specific type of tampering detected. Raised when there are discrepancies between the provided information and document contents. The alert message specifies which fields have mismatches (e.g. business name, registration number, address) and instructs the user to either update their information or provide matching documents. ## Key Components ### Document Analysis Each document in `valid_documents` or `invalid_documents` contains the following components: #### Extraction Data Indicates whether the document structure and content are valid. Detailed analysis of the document content and its validity. Brief overview of the document's key information. The document's date in ISO format. Any alerts or warnings associated with the document validation. Primary business name extracted from the document. Array of all business names found in the document. Date of incorporation in ISO format. Primary business address found in the document. Object containing all addresses found in the document. Type of business activity mentioned in the document. Legal jurisdiction under which the business is registered. Array of registration numbers found in the document. #### Document Metadata Metadata about the document being verified. The type identifier for the document object. Will be "Document". The URL where the document can be accessed. The name of the document file. Optional description of the document. The type of source for the document (e.g., "file\_url"). The number of pages in the document, if available. #### Fraud Verification Data Indicates if the document passed all fraud verification checks. Overall risk assessment result (e.g., "HIGH\_RISK", "LOW\_RISK"). Array of specific fraud indicators found in the document. Unique identifier for the fraud indicator. Category of the finding (e.g., "RISK"). Specific category of the indicator (e.g., "modifications"). Short description of the finding. Detailed explanation of the fraud indicator. Additional data associated with the indicator. Additional attributes of the indicator. Source of the fraud detection (e.g., "fraud"). Detailed description of the fraud verification results. #### Visual Inspection Results Type identifier for the visual inspection results. Comparative analysis with other reviewed documents. Detailed reasoning behind the visual inspection conclusions. Detailed results of various visual inspection aspects. Analysis of document type and classification. Whether the document passed classification checks. Analysis of document seals and stamps. Whether the seal verification passed. Whether a seal is present on the document. Analysis of document signatures. Whether the signature verification passed. Whether signatures are present on the document. Analysis of document layout and content structure. Whether the layout verification passed. Whether the document passed overall visual inspection. Overview of all visual inspection findings. ### Address Object Structure ```typescript theme={null} { type: "Address"; street_1: string; street_2: string | null; city: string; state: string; country_code: string; postal_code: string; } ``` # Individual (KYC) Proof of Address Document Verification Source: https://docs.parcha.ai/api-reference/check-results/kyc-proof-of-address-document-verification Verify individual proof of address documents and validate address information The individual proof of address document verification check response payload contains a detailed analysis of submitted address documents. The response includes extracted information, fraud detection findings, visual inspection, and overall validation results. ## Check ID `kyc.proof_of_address_verification` ## Response Structure ```typescript theme={null} { type: "KYCProofOfAddressCheckResult"; valid_documents: Array; invalid_documents: Array; verified_name: string; verified_address: Address; document_type: string; valid_document: boolean; } ``` ## Example Response ```json theme={null} { "type": "KYCProofOfAddressCheckResult", "valid_documents": [ { "extraction_data": { "is_valid_document": true, "analysis": "This is a valid utility bill showing the individual's address. The document contains all required elements including full name, current address, and recent date. The document appears to be authentic and unmodified.", "summary": "This is a utility bill for John Doe dated June 1, 2024, showing the residential address in San Francisco.", "date": "2024-06-01", "alerts": null, "name": "John Doe", "address": { "type": "Address", "street_1": "746 4th Avenue", "street_2": null, "city": "San Francisco", "state": "CA", "country_code": "US", "postal_code": "94118" } }, "fraud_verification_data": null, "visual_inspection": null, "document": { "type": "Document", "url": "https://storage.googleapis.com/parcha-ai-public-assets/John_proof_of_address.pdf", "file_name": "John_proof_of_address.pdf", "description": null, "source_type": "file_url", "num_pages": null } } ], "invalid_documents": [], "verified_name": "John Doe", "verified_address": { "type": "Address", "street_1": "746 4th Avenue", "street_2": null, "city": "San Francisco", "state": "CA", "country_code": "US", "postal_code": "94118" }, "document_type": "utility_bill", "valid_document": true } ``` ## Response Fields The type identifier for the response. Will be "KYCProofOfAddressCheckResult". Array of documents that passed all verification checks. Array of documents that failed one or more verification checks. The verified name of the individual that matches the self-attested name. The confirmed address after verification checks. The type of document used for address verification (e.g., "utility\_bill", "bank\_statement"). Whether the document is valid and meets all verification requirements. ## Key Components ### Document Analysis Each document in `valid_documents` or `invalid_documents` contains the following components: #### Extraction Data Indicates whether the document structure and content are valid. Detailed analysis of the document content and its validity. Brief overview of the document's key information. The document's date in ISO format. Any alerts or warnings associated with the document validation. Individual's name extracted from the document. Address found in the document. #### Document Metadata Metadata about the document being verified. The type identifier for the document object. Will be "Document". The URL where the document can be accessed. The name of the document file. Optional description of the document. The type of source for the document (e.g., "file\_url"). The number of pages in the document, if available. ### Address Object Structure ```typescript theme={null} { type: "Address"; street_1: string; street_2: string | null; city: string; state: string; country_code: string; postal_code: string; } ``` # PEP Screening Check Source: https://docs.parcha.ai/api-reference/check-results/pep-screening-check Verify that a business's key personnel are not politically exposed persons (PEPs) The PEP screening check response payload contains a detailed analysis of potential matches between a business's key personnel and politically exposed persons (PEPs). The check evaluates whether any individuals associated with the business hold or have held prominent public functions. ## Check ID `kyc.pep_screening_check_v2` ## Response Structure ```typescript theme={null} { type: "PEPScreeningCheckResult"; verified_pep_hits: Array | null; passed: boolean; } type VerifiedHit = { full_name: string | null; pep_title: string | null; pep_type: string | null; pep_status: "Active" | "Inactive" | null; roles: Array<{ name: string | null; country: string | null; start_date: string | null; // YYYY-MM-DD end_date: string | null; // YYYY-MM-DD }> | null; profile_review: { match_rating: { match: "STRONG_MATCH" | "PARTIAL_MATCH" | "WEAK_MATCH" | "NO_MATCH" | "UNKNOWN"; explanation: string | null; } | null; } | null; } ``` ## Example Response ```json theme={null} { "type": "PEPScreeningCheckResult", "verified_pep_hits": [ { "full_name": "John G. Smith", "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" } ], "profile_review": { "match_rating": { "match": "STRONG_MATCH", "explanation": "Name, location, and role details match the individual's profile" } } } ], "passed": false } ``` ## Response Fields The type identifier for the response. Will be "PEPScreeningCheckResult". List of verified PEP matches found during screening. Full name of the PEP. Official title or position of the PEP. Category or type of PEP (e.g., Politician, Judge). Current status of the PEP role (Active or Inactive). List of positions or roles held by the PEP. Name of the role or position. Country where the role is/was held. Start date of the role (YYYY-MM-DD). End date of the role (YYYY-MM-DD). Analysis of the match quality. Assessment of the match strength. Match rating category (STRONG\_MATCH, PARTIAL\_MATCH, WEAK\_MATCH, NO\_MATCH, UNKNOWN). Explanation of the match rating. Indicates whether the business passed the PEP screening. False if strong PEP matches are found. ## Key Components ### PEP Categories The check evaluates different types of politically exposed persons: 1. **Government Officials**: * Heads of state * Ministers * Parliamentarians * Senior civil servants 2. **Judicial Officials**: * Judges * Prosecutors * High-ranking court officials 3. **Military Officials**: * Senior military officers * Defense officials * Intelligence leaders 4. **State Enterprise Leaders**: * Directors of state companies * Senior managers * Board members ### Match Analysis The check evaluates matches based on multiple criteria: 1. **Identity Matching**: * Name comparison * Date of birth * Nationality * Location 2. **Role Verification**: * Position details * Jurisdiction * Time period * Authority level 3. **Risk Assessment**: * Current vs. historical roles * Level of authority * Geographic risk * Associated entities ### Verification Process The check performs the following verifications: 1. Screens individual names against PEP databases 2. Verifies biographical information 3. Analyzes role and position details 4. Evaluates temporal relevance 5. Assesses relationship strength ### Match Ratings The check categorizes matches into different levels: 1. **Strong Match**: * Multiple matching identifiers * Current role confirmation * Clear temporal overlap * Geographic consistency 2. **Partial Match**: * Some matching identifiers * Possible role connection * Partial temporal overlap * Related jurisdiction 3. **Weak Match**: * Limited matching data * Historical role only * Unclear temporal connection * Different jurisdiction # Proof of Address Document Verification Result Source: https://docs.parcha.ai/api-reference/check-results/proof-of-address-document-verification Response schema for proof of address document verification checks The Proof of Address Document Verification check returns a detailed analysis of the provided address documents and verification results. The check result will be returned in the `payload` field of the check result object. ## Check ID `kyb.proof_of_address_verification` ## Response Schema Type identifier "ProofOfAddressCheckResult" The verified business name extracted from the document The verified address extracted from the document Type identifier "Address" First line of street address Second line of street address (optional) City name State or province Postal or ZIP code Country code Type of document used for verification (e.g., "government\_letter", "utility\_bill") Whether the document is valid for proof of address verification List of valid proof of address documents Type identifier "ProofOfAddressExtractionResults" Whether the document is a valid proof of address Detailed analysis of why the document is valid or invalid Summary of the document's contents and purpose Document date in YYYY-MM-DD format Any alerts or warnings about the document Business name from the document Address from the document Same structure as verified\_address Type of document (e.g., "government\_letter", "utility\_bill") The original document metadata Type identifier "Document" URL of the document Name of the document file Source type of the document (e.g., "file\_url") List of invalid proof of address documents Same structure as valid\_documents List of all documents analyzed Same structure as valid\_documents ### Example Response ```json theme={null} { "type": "ProofOfAddressCheckResult", "verified_name": "PARCHA LABS INC", "verified_address": { "type": "Address", "street_1": "1160 BATTERY ST STE 100 PMB 1014", "street_2": null, "city": "SAN FRANCISCO", "state": "CA", "country_code": "US", "postal_code": "94111-1233" }, "document_type": "government_letter", "valid_document": false, "valid_documents": [], "invalid_documents": [], "documents": [ { "type": "ProofOfAddressExtractionResults", "is_valid_document": true, "analysis": "The document is a valid proof of address because it's an IRS notice containing the business's name and physical address. The address is confirmed to be a physical address, not a PO Box.", "summary": "This document is an IRS notice (CP148A) dated October 2, 2023, informing Parcha Labs Inc. of an address change in their records. The notice confirms their address as 1160 Battery St Ste 100 PMB 1014, San Francisco, CA 94111-1233.", "date": "2023-10-02", "alerts": {}, "name": "PARCHA LABS INC", "address": { "type": "Address", "street_1": "1160 BATTERY ST STE 100 PMB 1014", "street_2": null, "city": "SAN FRANCISCO", "state": "CA", "country_code": "US", "postal_code": "94111-1233" }, "document_type": "government_letter", "document": { "type": "Document", "url": "https://storage.googleapis.com/parcha-ai-public-assets/Parcha_proof_of_address.pdf", "file_name": "Parcha_proof_of_address.pdf", "source_type": "file_url" } } ] } ``` # Source of Funds Document Verification Source: https://docs.parcha.ai/api-reference/check-results/source-of-funds-document-verification Verify business source of funds documents and validate funding information The source of funds document verification check response payload contains a detailed analysis of submitted business funding documents. The response includes extracted information, fraud detection findings, visual inspection, and overall validation results. ## Check ID `kyb.source_of_funds_document_check` ## Response Structure ```typescript theme={null} { type: "KYBSourceOfFundsDocumentVerificationResult"; valid_documents: Array; invalid_documents: Array; verified_business_name: string; verified_source_of_funds: string; verified_amount: number; verified_date: string; } ``` ## Example Response ```json theme={null} { "type": "KYBSourceOfFundsDocumentVerificationResult", "valid_documents": [ { "extraction_data": { "is_valid_document": true, "analysis": "This is a valid fundraising announcement document showing the business's source of funds. The document contains all required elements including business name, funding amount, date, and source details. The document appears to be authentic and unmodified.", "summary": "This is a fundraising announcement for Parcha Labs, Inc. dated June 17, 2024, detailing a Series A funding round.", "date": "2024-06-17", "alerts": null, "business_name": "Parcha Labs, Inc.", "document_type": "fundraising_announcement", "source_of_funds": "Series A venture capital funding from institutional investors", "amount": 5000000.00 }, "fraud_verification_data": null, "visual_inspection": null, "document": { "type": "Document", "url": "https://storage.googleapis.com/parcha-ai-public-assets/Parcha_fundraising_announcement.pdf", "file_name": "Parcha_funding_round.pdf", "description": null, "source_type": "file_url", "num_pages": null } } ], "invalid_documents": [], "verified_business_name": "Parcha Labs, Inc.", "verified_source_of_funds": "Series A venture capital funding", "verified_amount": 5000000.00, "verified_date": "2024-06-17" } ``` ## Response Fields The type identifier for the response. Will be "KYBSourceOfFundsDocumentVerificationResult". Array of documents that passed all verification checks. Array of documents that failed one or more verification checks. The confirmed business name after verification checks. The confirmed source of funds after verification checks. The confirmed funding amount after verification checks. The confirmed document date after verification checks. ## Key Components ### Document Analysis Each document in `valid_documents` or `invalid_documents` contains the following components: #### Extraction Data Indicates whether the document structure and content are valid. Detailed analysis of the document content and its validity. Brief overview of the document's key information. The document's date in ISO format. Any alerts or warnings associated with the document validation. Business name extracted from the document. Type of source of funds document (e.g., "bank\_statement", "fundraising\_announcement"). Detailed description of the source of funds with explanation of how they were acquired. The amount of funds in dollars. #### Document Metadata Metadata about the document being verified. The type identifier for the document object. Will be "Document". The URL where the document can be accessed. The name of the document file. Optional description of the document. The type of source for the document (e.g., "file\_url"). The number of pages in the document, if available. #### Fraud Verification Data Indicates if the document passed all fraud verification checks. Overall risk assessment result (e.g., "HIGH\_RISK", "LOW\_RISK"). Array of specific fraud indicators found in the document. Unique identifier for the fraud indicator. Category of the finding (e.g., "RISK"). Specific category of the indicator (e.g., "modifications"). Short description of the finding. Detailed explanation of the fraud indicator. Additional data associated with the indicator. Additional attributes of the indicator. Source of the fraud detection (e.g., "fraud"). Detailed description of the fraud verification results. #### Visual Inspection Results Type identifier for the visual inspection results. Comparative analysis with other reviewed documents. Detailed reasoning behind the visual inspection conclusions. Detailed results of various visual inspection aspects. Analysis of document type and classification. Whether the document passed classification checks. Analysis of document layout and content structure. Whether the layout verification passed. Whether the document passed overall visual inspection. Overview of all visual inspection findings. # Web Presence Check Source: https://docs.parcha.ai/api-reference/check-results/web-presence-check Verify and analyze a business's online presence and digital footprint The web presence check response payload contains a comprehensive analysis of a business's online presence, including website verification and digital footprint. The check evaluates the authenticity and activity level of the business's web presence. ## Check ID `kyb.web_presence_check` ## Response Structure ```typescript theme={null} { type: "WebPresenceCheckResult"; official_website_match: OfficialWebsiteMatch | null; other_webpages_matches: Array | null; passed: boolean; } type OfficialWebsiteMatch = { type: "OfficialWebsiteMatch"; url: string | null; screenshot_url: string | null; title: string | null; visual_summary: string | null; } ``` ## Example Response ```json theme={null} { "type": "WebPresenceCheckResult", "official_website_match": { "type": "OfficialWebsiteMatch", "url": "https://parcha.ai", "title": "Parcha Labs - AI-Powered Compliance Solutions", "visual_summary": "Professional business website with modern design, featuring product information, company details, and customer resources", "screenshot_url": "https://storage.googleapis.com/screenshots/parcha.ai.png" }, "other_webpages_matches": [ { "type": "OfficialWebsiteMatch", "url": "https://www.linkedin.com/company/parcha-ai", "title": "Parcha Labs | LinkedIn", "visual_summary": "Active corporate LinkedIn profile with regular company updates and industry insights", "screenshot_url": null }, { "type": "OfficialWebsiteMatch", "url": "https://twitter.com/parchaHQ", "title": "Parcha (@parchaHQ) | Twitter", "visual_summary": "Verified business Twitter account with product announcements and industry news", "screenshot_url": null } ], "passed": true, "verification_data": { "website_analysis": { "source_1": { "text": "Official business website with comprehensive product information and regular updates", "source_id": "website_monitor", "analysis": "Website shows professional maintenance and active business operations" } }, "web_presence": { "source_1": { "text": "Active presence across major business platforms with consistent branding", "source_id": "web_monitor", "analysis": "Digital footprint indicates legitimate and active business operations" } } } } ``` ## Response Fields The type identifier for the response. Will be "WebPresenceCheckResult". Information about the business's official website. The type identifier for the match. Will be "OfficialWebsiteMatch". The URL of the official website. The title of the website. A description of the website's visual appearance and content. URL of a screenshot of the website, if available. List of other web pages associated with the business. The type identifier for the match. Will be "OfficialWebsiteMatch". The URL of the web page. The title of the web page. A description of the page's visual appearance and content. URL of a screenshot of the web page, if available. Indicates whether the business has a legitimate and active web presence. Detailed findings from the web presence verification. Analysis of the business website. Identifier for the website analysis source. Description of website activity and status. Analysis of the website findings. Analysis of overall web presence. Identifier for the web presence analysis source. Description of web presence findings. Analysis of web presence findings. ## Key Components ### Web Presence Analysis The check evaluates online presence across multiple dimensions: 1. **Official Website**: * Domain verification * Content analysis * Visual assessment * Technical review 2. **Additional Web Pages**: * Business profiles * Directory listings * News coverage * Industry mentions 3. **Digital Footprint**: * Brand consistency * Content quality * Professional presence * Market visibility ### Verification Process The check performs the following verifications: 1. Validates official website authenticity 2. Analyzes website content and structure 3. Reviews additional web presence 4. Assesses content consistency 5. Evaluates overall digital footprint ### Risk Indicators The check evaluates potential red flags such as: 1. **Website Issues**: * Missing or inactive website * Unprofessional content * Technical problems * Inconsistent branding 2. **Web Presence Concerns**: * Limited digital footprint * Inconsistent information * Negative mentions * Suspicious patterns 3. **Content Risks**: * Outdated information * Missing key details * Poor quality content * Misleading claims # Download report Source: https://docs.parcha.ai/api-reference/download-report api-reference/openapi.yaml post /downloadReport # Enqueue jobs from CSV Source: https://docs.parcha.ai/api-reference/enqueue-jobs-from-csv api-reference/openapi.yaml post /enqueueFromCSV # Enqueue jobs from various sources Source: https://docs.parcha.ai/api-reference/enqueue-jobs-from-various-sources api-reference/openapi.yaml post /enqueueFromSource Process URL, PDF, CSV, or text to extract companies and enqueue as KYB jobs # Enqueue KYB schemas as jobs Source: https://docs.parcha.ai/api-reference/enqueue-kyb-schemas-as-jobs api-reference/openapi.yaml post /enqueueKybSchemas Enqueue a list of pre-extracted KYB schemas as jobs concurrently # Enrich company data Source: https://docs.parcha.ai/api-reference/enrich-company-data api-reference/openapi.yaml post /enrichCompany Enrich company data using People Data Labs API # Enrich person data Source: https://docs.parcha.ai/api-reference/enrich-person-data api-reference/openapi.yaml post /enrichPerson Enrich person data using People Data Labs API # Export CSV batch Source: https://docs.parcha.ai/api-reference/export-csv-batch api-reference/openapi.yaml get /exportCSVBatch # Extract KYB schemas from source Source: https://docs.parcha.ai/api-reference/extract-kyb-schemas-from-source api-reference/openapi.yaml post /getKybSchemasFromSource Process various sources and extract companies as KYB schemas without enqueueing jobs # Generate bulk case reports Source: https://docs.parcha.ai/api-reference/generate-bulk-case-reports api-reference/openapi.yaml post /generateBulkCaseReports # Generate report to Google Drive Source: https://docs.parcha.ai/api-reference/generate-report-to-google-drive api-reference/openapi.yaml post /generateReportToGDrive # Get a specific check result from job Source: https://docs.parcha.ai/api-reference/get-a-specific-check-result-from-job api-reference/openapi.yaml get /getCheckResultFromJob Retrieve the result of a specific check from a job # Get agent configuration Source: https://docs.parcha.ai/api-reference/get-agent-configuration api-reference/openapi.yaml get /agent/config Get the complete agent information including config by its key with visibility metadata # Get agent configuration cost estimate Source: https://docs.parcha.ai/api-reference/get-agent-configuration-cost-estimate api-reference/openapi.yaml post /getAgentConfigCostEstimate Calculate estimated cost for an agent configuration object (useful for unsaved drafts) # Get agent cost estimate Source: https://docs.parcha.ai/api-reference/get-agent-cost-estimate api-reference/openapi.yaml get /getAgentCostEstimate Calculate the estimated cost in credits for running all checks in an agent # Get agent schemas Source: https://docs.parcha.ai/api-reference/get-agent-schemas api-reference/openapi.yaml get /agent-schemas/{agent_key} Get the schema information for all checks in an agent # Get all sources for an agent instance Source: https://docs.parcha.ai/api-reference/get-all-sources-for-an-agent-instance api-reference/openapi.yaml get /getAllSources Retrieve all sources (scanned websites) for a given agent instance # Get available checks Source: https://docs.parcha.ai/api-reference/get-available-checks api-reference/openapi.yaml get /getAvailableChecks Retrieve list of all available checks # Get available checks with filtering Source: https://docs.parcha.ai/api-reference/get-available-checks-with-filtering api-reference/openapi.yaml get /checks Get available checks with flexible filtering options # Get batch jobs Source: https://docs.parcha.ai/api-reference/get-batch-jobs api-reference/openapi.yaml get /getBatchJobs # Get check all results for a job Source: https://docs.parcha.ai/api-reference/get-check-all-results-for-a-job api-reference/openapi.yaml get /getCheckResults Retrieve all check results for a specific job # Get check information Source: https://docs.parcha.ai/api-reference/get-check-information api-reference/openapi.yaml get /getCheckInfo Retrieve detailed information about a specific check # Get checks overview data Source: https://docs.parcha.ai/api-reference/get-checks-overview-data api-reference/openapi.yaml get /getChecksOverviewData # Get feedback inputs by key Source: https://docs.parcha.ai/api-reference/get-feedback-inputs-by-key api-reference/openapi.yaml get /getFeedbackInputsByKey # Get job batches Source: https://docs.parcha.ai/api-reference/get-job-batches api-reference/openapi.yaml get /getJobBatches # Get job by ID Source: https://docs.parcha.ai/api-reference/get-job-by-id api-reference/openapi.yaml get /getJobById # Get job metadata Source: https://docs.parcha.ai/api-reference/get-job-metadata api-reference/openapi.yaml get /getJobMetadata Retrieve comprehensive metadata for a job # Get job metadata by case ID Source: https://docs.parcha.ai/api-reference/get-job-metadata-by-case-id api-reference/openapi.yaml get /getJobMetadataByCaseId Retrieve metadata for the latest job associated with a case ID # Get job metadata by job ID Source: https://docs.parcha.ai/api-reference/get-job-metadata-by-job-id api-reference/openapi.yaml get /getJobMetadataByJobId Retrieve comprehensive metadata for a job by its ID # Get job status summary Source: https://docs.parcha.ai/api-reference/get-job-status-summary api-reference/openapi.yaml get /getJobStatusSummary Get a job's status and a summarized description of its progress # Get jobs by case ID Source: https://docs.parcha.ai/api-reference/get-jobs-by-case-id api-reference/openapi.yaml get /getJobsByCaseId # Get latest application state Source: https://docs.parcha.ai/api-reference/get-latest-application-state api-reference/openapi.yaml get /getLatestApplicationState Retrieve the latest application state for a specific application # Get source contents Source: https://docs.parcha.ai/api-reference/get-source-contents api-reference/openapi.yaml get /getSourceContents Retrieve content for specific source IDs # Get thinking for a command instance Source: https://docs.parcha.ai/api-reference/get-thinking-for-a-command-instance api-reference/openapi.yaml get /getThinking Retrieve the thinking/reasoning for a specific command instance # Get Specific Check Result Source: https://docs.parcha.ai/api-reference/getCheckResultFromJob GET /getCheckResultFromJob Retrieve the result of a specific check from a job This endpoint retrieves the full result of a specific check from a completed job, including all evidence and detailed findings. ## Endpoint `GET /getCheckResultFromJob` ## When to Use This Endpoint Use this endpoint when you need to: * Fetch the complete result for a specific check (e.g., sanctions screening, PEP check) * Get evidence and detailed findings that may not be included in the standard job response * Retrieve results for a specific entity in a multi-entity job (like KYB jobs with associated individuals) For the overall job status and all check results, use [`getJobById`](/api-reference/getJobById) with `include_check_results=true` instead. ## Parameters The unique identifier of the job. You receive this when you start a job or from a webhook notification. The check type identifier (also called `command_id`). This identifies **which type of check** to retrieve. Examples: * `kyb.sanctions_screening_check_v2` * `kyb.adverse_media_screening_check_v2` * `kyc.pep_screening_check_v2` * `kyb.incorporation_document_verification` This is the stable check identifier, not `command_instance_id` which changes with each job run. Identifies **which entity** the check was run against. This is especially important for jobs that process multiple entities (e.g., a business with associated individuals). You can find this value in the check results from `getJobById` response as `agent_instance_id`. For single-entity jobs, all checks will have the same `agent_instance_id`. For multi-entity jobs (like KYB with associated individuals), each entity will have its own `agent_instance_id`. The type of the case. Use `"kyb"` for business checks or `"kyc"` for individual checks. Whether to include status messages showing the check's progress history in the response. ## Response An array of source identifiers used in the check. The full check result object. Structure may vary based on the type of check. ## Error Responses A description of the error that occurred. | Status Code | Description | | ----------- | ----------------------------- | | 404 | Job or check result not found | | 403 | Unauthorized access to agent | | 500 | Internal server error | ## Example Request ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getCheckResultFromJob?job_id=e85e0cc4-b1e8-40b0-9a3d-83c328eee0f4&check_id=kyb.sanctions_screening_check_v2&agent_instance_id=09e3133959c447b493313b1b3360cc05&case_type=kyb' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ## Example Response ```json theme={null} { "command_id": "kyb.sanctions_screening_check_v2", "command_name": "KYB Sanctions Screening Check", "command_desc": "Tool used to screen a business against sanctions watchlists", "command_instance_id": "a5494583409b41d587cd753b686bcf43", "agent_instance_id": "09e3133959c447b493313b1b3360cc05", "status": "complete", "output": { "explanation": "The business was screened against multiple sanctions databases and no matches were found.", "payload": { "type": "SanctionsWatchlistScreeningCheckResult", "verified_sanctions_hits": [], "passed": true }, "passed": true, "answer": "No sanctions matches found for this business.", "recommendation": null, "alerts": {} }, "evidence": [ { "source": "OFAC SDN List", "searched_name": "Parcha Labs Inc", "match_count": 0 } ], "sources": ["OFAC SDN", "UN Sanctions", "EU Consolidated List"], "created_at": "2023-06-15T10:30:00Z", "updated_at": "2023-06-15T10:35:00Z" } ``` # Get All Check Results Source: https://docs.parcha.ai/api-reference/getCheckResults GET /getCheckResults Retrieve all check results for a specific job This endpoint retrieves all check results associated with a specific job. ## Endpoint `GET /getCheckResults` ## Parameters The unique identifier of the job. ## Response Returns an array of check result objects. An array of check result objects for the job. The unique identifier of the check result The ID of the check that was run The status of the check (e.g., "completed", "in\_progress", "failed") The detailed result data from the check An array of status message objects tracking the check's progress ISO 8601 timestamp of when the check result was created ISO 8601 timestamp of when the check result was last updated ## Error Responses A description of the error that occurred. | Status Code | Description | | ----------- | --------------------- | | 404 | Job not found | | 401 | Unauthorized access | | 500 | Internal server error | ## Example Request ```bash theme={null} curl -X GET 'https://api.parcha.ai/getCheckResults?job_id=123456' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ## Example Response ```json theme={null} [ { "id": "check_result_1", "check_id": "business_profile_check", "status": "completed", "result": { "business_name": "Acme Corp", "industry": "Technology", "risk_score": 15 }, "status_messages": [ { "message": "Check started", "timestamp": "2023-06-15T10:30:00Z" }, { "message": "Data retrieved", "timestamp": "2023-06-15T10:31:00Z" }, { "message": "Check completed", "timestamp": "2023-06-15T10:32:00Z" } ], "created_at": "2023-06-15T10:30:00Z", "updated_at": "2023-06-15T10:32:00Z" }, { "id": "check_result_2", "check_id": "adverse_media_screening", "status": "completed", "result": { "findings": [], "risk_level": "low" }, "status_messages": [ { "message": "Check started", "timestamp": "2023-06-15T10:30:00Z" }, { "message": "Media search completed", "timestamp": "2023-06-15T10:33:00Z" } ], "created_at": "2023-06-15T10:30:00Z", "updated_at": "2023-06-15T10:33:00Z" } ] ``` ## Use Cases This endpoint is useful for: * Retrieving all check results after a job completes * Monitoring the status of multiple checks in a single job * Building dashboards that display comprehensive job results * Accessing detailed findings from all checks performed # Get Job by ID Source: https://docs.parcha.ai/api-reference/getJobById GET /getJobById Retrieve detailed information about a specific job This endpoint retrieves detailed information about a job by its ID, including its status, progress, and associated check results. ## API Endpoint ``` GET https://api.parcha.ai/api/v1/getJobById ``` ## Query Parameters The unique identifier of the job to retrieve. If true, includes only the IDs of check results. Cannot be used with `include_check_results`. If true, includes full check result objects. Cannot be used with `include_check_result_ids`. If true, includes status messages associated with the job. Optional JSONPath query to filter and extract specific fields from the response. Useful for reducing payload size when `include_check_results=true` returns large amounts of data. See [Filtering Check Results](#filtering-check-results) below for examples. ## Filtering Check Results When using `include_check_results=true`, the response can contain large amounts of data. Use the `jsonpath_query` parameter to filter and extract only the data you need. ### JSONPath Syntax The API uses [JSONPath](https://goessner.net/articles/JsonPath/) syntax for filtering. Here are common patterns: * **Filter by field value**: `$.check_results[?(@.field=='value')]` * **Get all items**: `$.check_results[*]` * **Extract specific field**: `$.check_results[*].field_name` * **Nested field access**: `$.check_results[*].payload.nested_field` ### Common Use Cases Get only the results for a specific check type: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.web_presence_check")]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array containing only the web presence check result Filter to see only checks that didn't pass: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.passed==false)]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of failed check results Get just the payload type from all check results: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[*].payload.type' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of payload type strings (e.g., `["WebPresenceCheckResult", "PolicyCheckResult"]`) Extract specific nested fields from check result payloads: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.web_presence_check")].payload.verified_hits[*].hit_name' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of hit names from the verified\_hits array (e.g., `["LinkedIn", "Crunchbase"]`) Get all completed checks: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.status=="complete")]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of completed check results ### Adverse Media Filtering Examples For detailed adverse media structure, see the [Adverse Media Screening Check documentation](/api-reference/check-results/adverse-media-screening-check). Retrieve all verified adverse media hits for a job: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of all adverse media profiles found Filter for articles where the business is identified as the perpetrator: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.metadata.is_perpetrator==true)]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of weblinks where `is_perpetrator` is `true` Filter for articles from Google Search only: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.article_source=="serp_google_search")]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of weblinks from Google Search **Other sources**: `refinitiv_world_check`, `comply_advantage`, `serp_google_news`, `serp_brave_search` Filter for articles about regulatory violations: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?("Regulatory Violations" in @.metadata.topics)]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of weblinks with "Regulatory Violations" in topics **Common topics**: "Legal Disputes", "Compliance Issues", "Safety Issues", "Financial Misconduct", "Criminal Activity" Extract just the article titles and URLs: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[*][title,url]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of objects with only `title` and `url` fields Filter for articles published in 2024 or later: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.metadata.year_of_article_publication>=2024)]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of weblinks published in 2024 or later Get summaries for articles from a specific country: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?("United States" in @.where_countries)].metadata.summary_of_event' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of event summaries for articles from the United States Extract all direct quotes about the business: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[*].metadata.quote_from_article' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Returns**: Array of direct quotes from adverse media articles ### Python Example ```python theme={null} import requests from urllib.parse import quote api_key = 'YOUR_API_KEY' job_id = '123e4567-e89b-12d3-a456-426614174000' # Filter for failed checks jsonpath_query = '$.check_results[?(@.passed==false)]' url = f'https://api.parcha.ai/api/v1/getJobById?job_id={job_id}&include_check_results=true&jsonpath_query={quote(jsonpath_query)}' headers = {'Authorization': f'Bearer {api_key}'} response = requests.get(url, headers=headers) # Response contains only failed checks failed_checks = response.json() print(f"Found {len(failed_checks)} failed checks") ``` ### Error Handling Returned when the JSONPath query has invalid syntax. ```json theme={null} { "error": "Invalid JSONPath query: Error on line 1, col 16: Unexpected character: ?" } ``` Returned when the JSONPath query returns no results. ```json theme={null} { "error": "JSONPath query returned no results" } ``` **JSONPath Resources**: * [JSONPath Online Evaluator](https://jsonpath.com/) - Test your queries * [JSONPath Documentation](https://goessner.net/articles/JsonPath/) - Full syntax reference * The API uses the [jsonpath-ng](https://github.com/h2non/jsonpath-ng) library with extended filter support ## Response The unique identifier for the job. The ID of the agent that executed the job. The email address of the job owner. The current status of the job (e.g., PENDING, RUNNING, COMPLETED, FAILED, RETRIED). If the status is `RETRIED`, it means this job instance was superseded by a new job. You should use the `new_job_id` to fetch the latest job information. The timestamp when the job started. The timestamp when the job completed. The recommendation based on the job results. The input data provided for the job. An array of status messages associated with the job. The unique identifier of the new job that was created as a retry of this job. This field is present only if the `status` is `RETRIED`. The unique identifier of the original job that this job is a retry of. This field is present if this job was created as a retry of a previous job. An array of check results from the job execution. ```json theme={null} { "step_description": "Tool used to determine if the business profile provided by the business matches the verified business profile", "name": "KYB Basic Business Profile Check", "instruction": "Generate and validate a basic business profile from web data and check against self attested data.", "command_result": { "agent_key": "your-kyb-agent-key", "command_id": "kyb.basic_business_profile_check", "command_name": "KYB Basic Business Profile Check", "command_desc": "Tool used to determine if the business profile provided by the business matches the verified business profile", "command_instance_id": "a5494583409b41d587cd753b686bcf43", "output": { "explanation": "This task involves verifying the accuracy of self-reported business information against verified data sources. The goal is to ensure that the self-reported business profile aligns with the information verified from reliable sources.", "payload": { "type": "BasicBusinessProfileCheckResult", "business_name_match": { "exact_match": true, "partial_match": false, "source_ids": [ "fxvqri" ], "explanation": "The business name 'Parcha' exactly matches the name found in the verified data.", "name": "Parcha" }, "business_description_match": null, "business_industry_match": null }, "answer": "The basic business profile check passed. The self-reported business name 'Parcha' matches the verified data, and no discrepancies were found as other fields were not provided in the self-reported data.", "passed": true, "recommendation": null, "alerts": {} }, "agent_instance_id": "09e3133959c447b493313b1b3360cc05" }, "on_check_failure": null } ``` ## Usage Examples ```bash cURL theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=123e4567-e89b-12d3-a456-426614174000&include_check_results=true' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' job_id = '123e4567-e89b-12d3-a456-426614174000' url = f'https://api.parcha.ai/api/v1/getJobById?job_id={job_id}&include_check_results=true' headers = { 'Authorization': f'Bearer {api_key}' } response = requests.get(url, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const jobId = '123e4567-e89b-12d3-a456-426614174000'; const url = `https://api.parcha.ai/api/v1/getJobById?job_id=${jobId}&include_check_results=true`; axios.get(url, { headers: { 'Authorization': `Bearer ${apiKey}` } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ## Example Response ```json theme={null} { "created_at": "2024-09-06T03:06:57.213129", "id": "50432480-5ab8-433c-b7be-a0e40408029a", "agent_id": "your-agent-key", "descope_user_id": "U2U2iomFdkpU6FcNgU8wmEtkvnde", "started_at": "2024-09-06T03:06:57.645676", "progress": null, "queued_at": null, "tenant_id": "T2QyrSQP8m6UOfLLqTux2q0Gj5AW", "updated_at": "2024-09-06T03:06:57.213133", "celery_task_id": null, "owner_id": "miguel@parcha.ai", "status": "RETRIED", "new_job_id": "60532481-6bc9-444d-c8cf-b1f50509030b", "original_job_id": null, "completed_at": "2024-09-06T03:13:07.371114", "recommendation": "Review", "input_payload": { "id": "parcha-5f7008a3", "self_attested_data": { "type": "SelfAttestedData", "website": "https://parcha.ai" }, "research_data": { "type": "WebResearchDataCheck", "data": { "type": "WebResearchData", "is_valid_url": false, "is_filtered": false } }, "self_attested_address_check": { "type": "SelfAttestedAddressCheck", "result": { "type": "SelfAttestedAddressCheckResult", "operating_address_verified": false, "operating_address_is_business": false, "operating_address_is_pobox": false, "operating_address_is_residential": false } }, "web_presence_check": { "type": "WebPresenceCheck", "data": { "type": "WebPresenceCheckData", "only_used_search_results": false, "only_used_self_attested_websites": false, "only_used_extended_search_results": false } }, "mcc_code_check": { "type": "MCCCodeCheck", "result": { "type": "MCCCodeCheckResult", "mcc_code_description": "No description found." } } }, "status_messages": [], "check_results": [ { "job_id": "50432480-5ab8-433c-b7be-a0e40408029a", "command_desc": "Tool to determine if the web presence data loader succeeded.", "step_number": null, "updated_at": "2024-09-06T03:08:57.865904", "result_type": "CommandResult", "status": "complete", "created_at": "2024-09-06T03:06:58.149768", "input_data": { "business_name": "Parcha", "business_description": null }, "verification_data": { "type": "WebPresenceCheckData", "self_attested_webpages": [ // ... (webpage data omitted for brevity) ] }, // ... (other check results omitted for brevity) } ] } ``` ## Notes The `include_check_result_ids` and `include_check_results` parameters are mutually exclusive. Using both will result in a 400 Bad Request error. Access to job details is restricted. The API will return a 401 Unauthorized error if the user doesn't have access to the specified agent. If the job is not found, a 404 Not Found error will be returned. This endpoint provides a comprehensive view of a job's status and results, allowing for detailed tracking and analysis of the KYB/KYC process. ## Error Responses "Cannot include both check result ids and check results in the response" "Unauthorized" "Job not found" # Get Jobs by Case ID Source: https://docs.parcha.ai/api-reference/getJobsByCaseId GET /getJobsByCaseId Retrieve all jobs associated with a specific case ID for a given agent This endpoint retrieves all jobs associated with a specific case ID for a given agent. ## Endpoint `GET /getJobsByCaseId` ## Parameters The unique identifier of the case. The key of the agent associated with the jobs. Whether to include detailed check results in the response. Whether to include status messages in the response. ## Response The response follows the `JobsResponse` model, which typically includes: An array of job objects associated with the case ID. The total number of jobs associated with the case ID. Each job object may include: The unique identifier of the job. The current status of the job (e.g., "pending", "completed", "failed"). The timestamp when the job was created. The timestamp when the job was last updated. The input payload used for the job. An array of check results, if `include_check_results` is true. Deprecation Note: The `status_messages` field will be deprecated in future versions. An array of status messages, if `include_status_messages` is true. ## Error Responses A description of the error that occurred. | Status Code | Description | | ----------- | ---------------------------- | | 404 | Case or jobs not found | | 403 | Unauthorized access to agent | | 500 | Internal server error | ## Example Request ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobsByCaseId?case_id=123456&agent_key=your_agent_key&include_check_results=true&include_status_messages=true' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ## Example Response ```json theme={null} { "jobs": [ { "id": "job_789012", "status": "completed", "created_at": "2023-06-15T10:00:00Z", "updated_at": "2023-06-15T10:05:00Z", "check_results": [ { "id": "check_345678", "type": "business_verification", "status": "completed", "result": { "verified": true, "risk_score": 25 } } ], "status_messages": [ { "timestamp": "2023-06-15T10:01:00Z", "message": "Business verification check started" }, { "timestamp": "2023-06-15T10:05:00Z", "message": "Business verification check completed" } ] } ] } ``` ## Notes * This endpoint requires authentication. Make sure to include your API key in the request headers. * The user must have access to the specified agent to retrieve the jobs. * The `include_check_results` and `include_status_messages` parameters allow you to control the level of detail in the response. Setting these to `true` may increase the response size and processing time. * The structure of check results may vary depending on the type of checks performed in the jobs. # Introduction to Parcha API Source: https://docs.parcha.ai/api-reference/introduction An introduction to Parcha's AI-powered compliance review API Hero Light Hero Dark ## Welcome to Parcha API Parcha's API empowers you to seamlessly integrate AI-driven compliance reviews into your existing onboarding workflows. Whether you need to perform comprehensive Know Your Business (KYB) or Know Your Customer (KYC) reviews, or run individual compliance checks, our API provides the flexibility and intelligence you need. ## Key Features Conduct full KYB or KYC reviews with a single API call Execute specific compliance checks as needed Utilize our data sources or apply our AI to your existing data Track the progress and results of your compliance jobs in real-time ## Getting Started To begin leveraging the power of Parcha API, follow these steps: 1. [Sign up for a Parcha account](https://app.parcha.ai/signup) 2. [Obtain your API credentials](/api-reference/authentication) 3. Choose your integration method: * [Start a KYB review](/api-reference/startKYBAgentJob) * [Start a KYC review](/api-reference/startKYCAgentJob) * [Run an individual check](/api-reference/runCheck) 4. [Monitor your job progress](/api-reference/getJobById) ## API Overview Our API is designed to be intuitive and powerful. Here are the main endpoints you'll be working with: * [Authentication](/api-reference/authentication): Secure your API requests * [Start KYB Agent Job](/api-reference/startKYBAgentJob): Initiate a Know Your Business review * [Start KYC Agent Job](/api-reference/startKYCAgentJob): Initiate a Know Your Customer review * [Run Check](/api-reference/runCheck): Execute a specific compliance check * [Get Job by ID](/api-reference/getJobById): Retrieve detailed information about a job Each of these endpoints is thoroughly documented with request parameters, response fields, and usage examples to help you integrate Parcha into your workflow quickly and efficiently. ## Next Steps Ready to dive in? Start by [setting up your authentication](/api-reference/authentication), then explore our API endpoints to see how Parcha can enhance your compliance processes. If you have any questions along the way, our [support team](https://parcha.ai/support) is always here to help. Welcome aboard, and happy integrating! # Job Batches Source: https://docs.parcha.ai/api-reference/job-batches Process multiple KYB/KYC cases in batches The Job Batch feature allows you to process multiple KYB or KYC cases simultaneously by uploading a CSV file or using our standard API endpoints. This guide covers how to create, monitor, and manage job batches. ## What is a Job Batch? A job batch is a collection of related jobs that are processed together. Each batch has: * A unique batch ID * A batch name (typically derived from the uploaded CSV filename) * An agent key it's associated with * Creation timestamp ```mermaid theme={null} graph TD A[Upload CSV] --> B[Create Batch] B --> C[Process Jobs] C --> D[Monitor Progress] D --> E[Download Reports] E --> F[Export Results] style A fill:#f9d71c,stroke:#333,stroke-width:2px style B fill:#91c2e8,stroke:#333,stroke-width:2px style C fill:#91c2e8,stroke:#333,stroke-width:2px style D fill:#91c2e8,stroke:#333,stroke-width:2px style E fill:#91c2e8,stroke:#333,stroke-width:2px style F fill:#f9d71c,stroke:#333,stroke-width:2px ``` ## Creating a Batch ### Using CSV Upload The simplest way to create a batch is by uploading a CSV file containing multiple cases. ```bash theme={null} curl -X POST 'https://api.parcha.ai/api/v1/enqueueFromCSV' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'file=@/path/to/cases.csv' \ -F 'agent_id=your-agent-key' ``` ```python theme={null} import requests import os def create_batch_from_csv(api_key: str, agent_key: str, csv_path: str): url = "https://api.parcha.ai/api/v1/enqueueFromCSV" with open(csv_path, 'rb') as f: files = {'file': f} data = {'agent_id': agent_key} headers = {'Authorization': f'Bearer {api_key}'} response = requests.post(url, headers=headers, data=data, files=files) return response.json() # Example usage result = create_batch_from_csv( api_key='YOUR_API_KEY', agent_key='your-agent-key', csv_path='cases.csv' ) print(f"Batch created with {len(result['jobs'])} jobs") ``` ```typescript theme={null} import axios from 'axios'; import FormData from 'form-data'; import fs from 'fs'; async function createBatchFromCSV( apiKey: string, agentKey: string, csvPath: string ) { const form = new FormData(); form.append('file', fs.createReadStream(csvPath)); form.append('agent_id', agentKey); const response = await axios.post( 'https://api.parcha.ai/api/v1/enqueueFromCSV', form, { headers: { ...form.getHeaders(), 'Authorization': `Bearer ${apiKey}` } } ); return response.data; } // Example usage createBatchFromCSV( 'YOUR_API_KEY', 'your-agent-key', 'cases.csv' ) .then(result => { console.log(`Batch created with ${result.jobs.length} jobs`); }) .catch(console.error); ``` Example Response: ```json theme={null} { "status": "ok", "jobs": [ { "id": "f4cba9af-d976-414e-ad2f-c585696840bd", "status": "QUEUED", "agent_id": "your-agent-key" }, { "case_id": "john-doe-123", "job_id": "a1b2c3d4e5f6414ead2fc585696840bd", "started_at": "2024-12-10 17:40:30", "status": "complete", "recommendation": "Review", "checks": { "Source of Wealth Check": "Failed", "Adverse Media and OSInt Check": "Failed" }, "pdf_url": "https://storage.example.com/reports/a1b2c3d4e5f6414ead2fc585696840bd.pdf?signed=abc123" } ] } ``` The CSV format should match your agent type: ```csv KYB Example theme={null} business_name,website,industry,description Acme Corp,www.acme.com,Technology,Leading provider of cloud solutions Beta Inc,www.beta.com,Finance,Investment management firm ``` ```csv KYC Example theme={null} first_name,last_name,date_of_birth,country_of_nationality John,Doe,1980-01-01,US Jane,Smith,1985-05-15,UK ``` ## Listing Batches To get a list of all batches for an agent: ```bash cURL theme={null} curl 'https://api.parcha.ai/api/v1/getJobBatches?agent_key=your-agent-key&include_signed_urls=true' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```python Python theme={null} import requests def get_batches(api_key: str, agent_key: str, include_urls: bool = True): url = f"https://api.parcha.ai/api/v1/getJobBatches" params = { 'agent_key': agent_key, 'include_signed_urls': include_urls # Returns secure URLs for CSV files } headers = {'Authorization': f'Bearer {api_key}'} response = requests.get(url, headers=headers, params=params) return response.json() # Example usage batches = get_batches('YOUR_API_KEY', 'your-agent-key') for batch in batches: print(f"Batch: {batch['batch_name']}") print(f"Created: {batch['created_at']}") print(f"CSV URL: {batch.get('csv_signed_url', 'No URL available')}") ``` ```typescript TypeScript theme={null} import axios from 'axios'; async function getBatches( apiKey: string, agentKey: string, includeUrls: boolean = true // Returns secure URLs for CSV files ) { const response = await axios.get( 'https://api.parcha.ai/api/v1/getJobBatches', { params: { agent_key: agentKey, include_signed_urls: includeUrls }, headers: { 'Authorization': `Bearer ${apiKey}` } } ); return response.data; } ``` ### Parameters: * `include_signed_urls`: When set to true, returns secure signed URLs for accessing the original CSV files. These URLs are valid for 1 hour. Example Response: ```json theme={null} [ { "updated_at": "2024-01-10T17:40:29.883017", "agent_key": "your-agent-key", "created_at": "2024-01-10T17:40:29.883011", "id": "7fe54d2f-cd87-4d52-9734-d97e893d554a", "batch_name": "example_batch.csv [2024-01-10 17:40 UTC]", "csv_signed_url": "https://storage.example.com/signed-url-to-csv" }, { "updated_at": "2024-01-10T16:53:54.888520", "agent_key": "your-agent-key", "created_at": "2024-01-10T16:53:54.888513", "id": "1a967c94-ddcf-4a23-9953-a3f13ab6af69", "batch_name": "another_batch.csv [2024-01-10 16:53 UTC]", "csv_signed_url": "https://storage.example.com/signed-url-to-csv" } ] ``` ## ## Getting Batch Jobs To retrieve all jobs in a specific batch: ```bash cURL theme={null} curl 'https://api.parcha.ai/api/v1/getBatchJobs?batch_id=your-batch-id&fetch_pdf_from_gcs=true' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```python Python theme={null} import requests def get_batch_jobs( api_key: str, batch_id: str, fetch_pdf: bool = True # Include secure PDF URLs in response ): url = f"https://api.parcha.ai/api/v1/getBatchJobs" params = { 'batch_id': batch_id, 'fetch_pdf_from_gcs': fetch_pdf } headers = {'Authorization': f'Bearer {api_key}'} response = requests.get(url, headers=headers, params=params) return response.json() ``` ```typescript TypeScript theme={null} import axios from 'axios'; async function getBatchJobs( apiKey: string, batchId: string, fetchPdf: boolean = true // Include secure PDF URLs in response ) { const response = await axios.get( 'https://api.parcha.ai/api/v1/getBatchJobs', { params: { batch_id: batchId, fetch_pdf_from_gcs: fetchPdf }, headers: { 'Authorization': `Bearer ${apiKey}` } } ); return response.data; } ``` ### Parameters: * `fetch_pdf_from_gcs`: When set to true, includes secure signed URLs for accessing the PDF reports. These URLs are valid for 1 hour. Example Response: ```json theme={null} [ { "case_id": "CASE-001", "job_id": "f4cba9afd976414ead2fc585696840bd", "started_at": "2024-01-10 17:40:30", "status": "complete", "recommendation": "Review", "checks": { "Source of Wealth Check": "Failed", "Adverse Media Check": "Failed" }, "pdf_url": "https://storage.example.com/signed-url-to-pdf" }, { "case_id": "CASE-002", "job_id": "a1b2c3d4e5f6414ead2fc585696840bd", "started_at": "2024-01-10 17:41:30", "status": "complete", "recommendation": "Approve", "checks": { "Source of Wealth Check": "Passed", "Adverse Media Check": "Passed" }, "pdf_url": "https://storage.example.com/signed-url-to-pdf" } ] ``` ## Downloading Reports If a job doesn't have a PDF report URL or you need to regenerate it: ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/downloadReport' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "case_id": "your-case-id", "agent_key": "your-agent-key", "force_refresh_report": false }' \ --output "case_report.pdf" ``` ```python Python theme={null} import requests def download_report( api_key: str, case_id: str, agent_key: str, force_refresh: bool = False # Set to True to regenerate PDF ): url = "https://api.parcha.ai/api/v1/downloadReport" data = { "case_id": case_id, "agent_key": agent_key, "force_refresh_report": force_refresh } headers = {'Authorization': f'Bearer {api_key}'} response = requests.post( url, headers=headers, json=data ) if response.headers['content-type'] == 'application/pdf': # Save PDF with open(f"{case_id}_report.pdf", 'wb') as f: f.write(response.content) return f"Report saved as {case_id}_report.pdf" else: return response.json() ``` ```typescript TypeScript theme={null} import axios from 'axios'; import fs from 'fs'; async function downloadReport( apiKey: string, caseId: string, agentKey: string, forceRefresh: boolean = false // Set to True to regenerate PDF ) { const response = await axios.post( 'https://api.parcha.ai/api/v1/downloadReport', { case_id: caseId, agent_key: agentKey, force_refresh_report: forceRefresh }, { headers: { 'Authorization': `Bearer ${apiKey}` }, responseType: 'arraybuffer' } ); if (response.headers['content-type'] === 'application/pdf') { const fileName = `${caseId}_report.pdf`; fs.writeFileSync(fileName, response.data); return `Report saved as ${fileName}`; } else { const data = JSON.parse( Buffer.from(response.data).toString('utf8') ); return data; } } ``` ### Parameters: * `force_refresh_report`: When set to true, forces regeneration of the PDF report. This is useful if: * The downloaded PDF is blank or corrupted * The job was previously in a queued or in-progress state * You need a fresh copy of the report * Note: Generated PDF URLs expire after 1 hour Example Request Body: ```json theme={null} { "agent_key": "your-agent-key", "case_id": "CASE-001" } ``` Response: Returns a PDF file with the report content. ## Batch Processing Flow 1. **Create Batch** * Upload CSV file or use API endpoints * System generates batch ID and processes jobs 2. **Monitor Progress** * Use `getJobBatches` to list all batches * Use `getBatchJobs` to check individual job statuses 3. **Access Reports** * Download PDF reports using provided GCS URLs * Generate missing reports using `downloadReport` endpoint 4. **Export Results** * Use CSV export functionality for batch results * Access individual job results through API # Map CSV columns to schema fields Source: https://docs.parcha.ai/api-reference/map-csv-columns-to-schema-fields api-reference/openapi.yaml post /mapCsvColumns Use AI to intelligently map CSV column names to supported KYC/KYB schema fields # Run a check Source: https://docs.parcha.ai/api-reference/run-a-check api-reference/openapi.yaml post /runCheck # Run flash check Source: https://docs.parcha.ai/api-reference/run-flash-check api-reference/openapi.yaml post /runFlashCheck # Scrape using specialized scrapers Source: https://docs.parcha.ai/api-reference/scrape-using-specialized-scrapers api-reference/openapi.yaml post /specializedScraper Scrape websites using specialized scrapers for LinkedIn, Facebook, Instagram, TikTok, YouTube, Twitter, Reddit # Send feedback Source: https://docs.parcha.ai/api-reference/send-feedback api-reference/openapi.yaml post /sendFeedback # Start a KYB agent job Source: https://docs.parcha.ai/api-reference/start-a-kyb-agent-job api-reference/openapi.yaml post /startKYBAgentJob # Start a KYC agent job Source: https://docs.parcha.ai/api-reference/start-a-kyc-agent-job api-reference/openapi.yaml post /startKYCAgentJob # Start a Persona KYB job Source: https://docs.parcha.ai/api-reference/start-a-persona-kyb-job api-reference/openapi.yaml post /startPersonaKYBJob # Start a Persona KYC job Source: https://docs.parcha.ai/api-reference/start-a-persona-kyc-job api-reference/openapi.yaml post /startPersonaKYCJob # Start KYB Agent Job Source: https://docs.parcha.ai/api-reference/startKYBAgentJob POST /startKYBAgentJob Initiate a Know Your Business (KYB) agent job This endpoint starts a KYB (Know Your Business) agent job with the specified parameters. ## API Endpoint ``` POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ## Request Body Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. The KYB schema containing the business information. A unique identifier for this KYB case. Self-attested information about the business. Standard address format used throughout the schema. Primary street address line Secondary street address line (optional) City name State/province code Two-letter ISO country code (e.g., "US", "GB") Postal/ZIP code Standard document format used throughout the schema. URL to access the document. Required if b64\_document is not provided. Name of the file including extension Type of document source. Currently supported: "file\_url" Base64 encoded document content. Required if url is not provided. The name of the business. Required if website is not provided. The registered name of the business. Required if website is not provided and business\_name is not set. The business's operational address. Uses the Address Object format defined above. The business's incorporation address. Uses the Address Object format defined above. The website of the business. Required if business\_name or registered\_business\_name is not provided. The primary purpose or activity of the business. A brief description of the business. Maximum 512 characters. The industry sector the business operates in. Tax Identification Number or Employer Identification Number (EIN). Date of incorporation in YYYY-MM-DD format. Array of business partner names. Array of customer names. Array of funding sources (e.g., \["Investment", "Revenue"]). Array of incorporation document objects. Each item uses the Document Object format defined above. Array of ownership document objects. Each item uses the Document Object format defined above. Array of promotional/marketing document objects. Each item uses the Document Object format defined above. Array of address proof document objects. Each item uses the Document Object format defined above. Array of EIN document objects. Each item uses the Document Object format defined above. Array of funding source document objects. Each item uses the Document Object format defined above. Array of individuals associated with the business. Unique identifier for the individual. Individual's first name Individual's middle name Individual's last name Date of birth in YYYY-MM-DD format Individual's address. Uses the Address Object format defined above. Two-letter ISO country code of nationality Two-letter ISO country code of residence Place of birth (city, country) Individual's sex Email address Phone number Job title or position Whether this individual is the applicant Whether this individual is a business owner Percentage of business ownership Array of address proof document objects. Each item uses the Document Object format defined above. Array of entities associated with the business. Unique identifier for the entity Name of the associated business Whether the entity is a trust Entity's address. Uses the Address Object format defined above. Industry sector Tax Identification Number Percentage of business ownership Two-letter ISO country code Entity's website Description of the entity Optional. A unique identifier (UUID) that you can provide for this job. If provided, this ID will be used as an idempotency key. If a job with this ID already exists, the API will return a `409 Conflict` error, and you can then use this `job_id` to retrieve the existing job's status and results using `/getJobById`. If not provided, a new unique ID will be automatically generated for the job. An optional URL to receive webhook notifications about the job status. An optional Slack webhook URL to receive notifications about the job status. An optional array of specific check IDs to run. If not provided, all checks will be run. ## Response The status of the job creation request. Will be "ok" if successful. The unique identifier for the created job. A message indicating the result of the job creation request. Details about the created job. The unique identifier of the job. The current status of the job (e.g., "PENDING", "RUNNING", "COMPLETE", "FAILED", "RETRIED"). The timestamp when the job was created. The timestamp when the job was last updated. The ID of the agent used for this job. The input payload provided for the job. ## Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "job_id": "your-custom-job-id-123e4567-e89b-12d3-a456-426614174001", "kyb_schema": { "id": "parcha-demo-case-001", "self_attested_data": { "business_name": "Acme Corp", "website": "https://www.acmecorp.com" } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'job_id': 'your-custom-job-id-123e4567-e89b-12d3-a456-426614174001', 'kyb_schema': { 'id': 'parcha-demo-case-001', 'self_attested_data': { 'business_name': 'Acme Corp', 'website': 'https://www.acmecorp.com' } } } response = requests.post(url, json=data, headers=headers) if response.status_code == 409: print(f"Job with ID {data.get('job_id')} already exists. Fetching existing job details...") # existing_job_response = requests.get(f'https://api.parcha.ai/api/v1/getJobById?job_id={data.get("job_id")}', headers=headers) # print(existing_job_response.json()) elif response.status_code == 200: print(response.json()) else: print(f"Error: {response.status_code} - {response.text}") ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key job_id: 'your-custom-job-id-123e4567-e89b-12d3-a456-426614174001', kyb_schema: { id: 'parcha-demo-case-001', self_attested_data: { business_name: 'Acme Corp', website: 'https://www.acmecorp.com' } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => { if (error.response && error.response.status === 409) { console.log(`Job with ID ${data.job_id} already exists. Fetching existing job details...`); // axios.get(`https://api.parcha.ai/api/v1/getJobById?job_id=${data.job_id}`, { headers: { 'Authorization': `Bearer ${apiKey}` } }) // .then(existingJobResponse => console.log(existingJobResponse.data)) // .catch(getJobError => console.error('Error fetching existing job:', getJobError)); } else { console.error('Error starting job:', error.response ? error.response.data : error.message); } }); ``` ## Example Response Successful creation (200 OK): ```json theme={null} { "status": "ok", "job_id": "job-12345-abcde", "message": "The job was successfully added to the queue.", "job": { "id": "job-12345-abcde", "status": "PENDING", "created_at": "2023-06-15T10:30:00Z", "updated_at": "2023-06-15T10:30:00Z", "agent_id": "your-kyb-agent-key", "input_payload": { "agent_key": "your-kyb-agent-key", "kyb_schema": { "id": "parcha-demo-case-001", "self_attested_data": { "business_name": "Acme Corp", "website": "https://www.acmecorp.com" } } } } } ``` Conflict (409 Conflict) if `job_id` already exists: ```json theme={null} { "error": "Job with the provided ID already exists.", "job_id": "your-custom-job-id-123e4567-e89b-12d3-a456-426614174001" } ``` This endpoint initiates a KYB agent job with the provided parameters. The response includes a job ID that can be used to track the progress and retrieve results of the KYB process. # Start KYC Agent Job Source: https://docs.parcha.ai/api-reference/startKYCAgentJob POST /startKYCAgentJob Initiate a Know Your Customer (KYC) agent job This endpoint starts a KYC (Know Your Customer) agent job with the specified parameters. ## API Endpoint ``` POST https://api.parcha.ai/api/v1/startKYCAgentJob ``` ## Request Body Your KYC agent key from the Parcha dashboard. This is unique to your organization and agent configuration. **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. The KYC schema containing the individual's information. A unique identifier for this KYC case. Self-attested information about the individual. Standard address format used throughout the schema. Primary street address line Secondary street address line (optional) City name State/province code Two-letter ISO country code (e.g., "US", "GB") Postal/ZIP code Standard document format used throughout the schema. URL to access the document. Required if b64\_document is not provided. Name of the file including extension Type of document source. Currently supported: "file\_url" Base64 encoded document content. Required if url is not provided. The individual's first name The individual's middle name The individual's last name The individual's date of birth in YYYY-MM-DD format The individual's address. Uses the Address Object format defined above. Array of associated addresses for the individual. Each item uses the Address Object format defined above. Two-letter ISO country code of nationality Two-letter ISO country code of residence Place of birth (city, country) Individual's sex Email address Phone number Array of address proof document objects. Each item uses the Document Object format defined above. Government ID verification data. First name as shown on ID Last name as shown on ID Middle names as shown on ID Date of birth in YYYY-MM-DD format Type of ID document (e.g., "Driver's License", "Passport") ID document number Address shown on ID. Uses the Address Object format defined above. Country that issued the ID Phone number on ID URL to front image of ID URL to back image of ID URL to face match image URL to face match video Name of ID verification vendor URL to vendor's verification page Whether vendor validated the document Vendor-specific verification data Sanctions and watchlist screening results. Array of sanctions matches Politically Exposed Person (PEP) screening results. Array of PEP matches An optional URL to receive webhook notifications about the job status. An optional Slack webhook URL to receive notifications about the job status. An optional array of specific check IDs to run. If not provided, all checks will be run. Optional. A unique identifier (UUID) that you can provide for this job. If provided, this ID will be used as an idempotency key. If a job with this ID already exists, the API will return a `409 Conflict` error, and you can then use this `job_id` to retrieve the existing job's status and results using `/getJobById`. If not provided, a new unique ID will be automatically generated for the job. ## Response The status of the job creation request. Will be "ok" if successful. The unique identifier for the created job. A message indicating the result of the job creation request. Details about the created job. The unique identifier of the job. The current status of the job (e.g., "PENDING", "RUNNING", "COMPLETE", "FAILED", "RETRIED"). The timestamp when the job was created. The timestamp when the job was last updated. The ID of the agent used for this job. The input payload provided for the job. ## Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYCAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "kyc-standard-check", "job_id": "your-custom-job-id-123e4567-e89b-12d3-a456-426614174002", "kyc_schema": { "id": "parcha-kyc-demo-001", "self_attested_data": { "first_name": "Jane", "last_name": "Doe" } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYCAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'kyc-standard-check', 'job_id': 'your-custom-job-id-123e4567-e89b-12d3-a456-426614174002', 'kyc_schema': { 'id': 'parcha-kyc-demo-001', 'self_attested_data': { 'first_name': 'Jane', 'last_name': 'Doe' } } } response = requests.post(url, json=data, headers=headers) if response.status_code == 409: print(f"Job with ID {data.get('job_id')} already exists. Fetching existing job details...") # existing_job_response = requests.get(f'https://api.parcha.ai/api/v1/getJobById?job_id={data.get("job_id")}', headers=headers) # print(existing_job_response.json()) elif response.status_code == 200: print(response.json()) else: print(f"Error: {response.status_code} - {response.text}") ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYCAgentJob'; const data = { agent_key: 'kyc-standard-check', job_id: 'your-custom-job-id-123e4567-e89b-12d3-a456-426614174002', kyc_schema: { id: 'parcha-kyc-demo-001', self_attested_data: { first_name: 'Jane', last_name: 'Doe' } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => { if (error.response && error.response.status === 409) { console.log(`Job with ID ${data.job_id} already exists. Fetching existing job details...`); // axios.get(`https://api.parcha.ai/api/v1/getJobById?job_id=${data.job_id}`, { headers: { 'Authorization': `Bearer ${apiKey}` } }) // .then(existingJobResponse => console.log(existingJobResponse.data)) // .catch(getJobError => console.error('Error fetching existing job:', getJobError)); } else { console.error('Error starting job:', error.response ? error.response.data : error.message); } }); ``` ## Example Response Successful creation (200 OK): ```json theme={null} { "status": "ok", "job_id": "job-67890-fghij", "message": "The job was successfully added to the queue.", "job": { "id": "job-67890-fghij", "status": "PENDING", "created_at": "2023-06-15T14:30:00Z", "updated_at": "2023-06-15T14:30:00Z", "agent_id": "kyc-standard-check", "input_payload": { "agent_key": "kyc-standard-check", "kyc_schema": { "id": "parcha-kyc-demo-001", "self_attested_data": { "first_name": "Jane", "last_name": "Doe" } }, "webhook_url": "https://your-webhook.com/kyc-updates" } } } ``` Conflict (409 Conflict) if `job_id` already exists: ```json theme={null} { "error": "Job with the provided ID already exists.", "job_id": "your-custom-job-id-123e4567-e89b-12d3-a456-426614174002" } ``` This endpoint initiates a KYC agent job with the provided parameters. The response includes a job ID that can be used to track the progress and retrieve results of the KYC process. # Test webhook Source: https://docs.parcha.ai/api-reference/test-webhook api-reference/openapi.yaml post /testWebhook # Test webhook receiver Source: https://docs.parcha.ai/api-reference/test-webhook-receiver api-reference/openapi.yaml post /testWebhookReceiver # Update application status Source: https://docs.parcha.ai/api-reference/update-application-status api-reference/openapi.yaml post /updateApplicationStatus Update the status of an application # Upload base64 document Source: https://docs.parcha.ai/api-reference/upload-base64-document api-reference/openapi.yaml post /uploadB64Document # Vendor Data Integration Source: https://docs.parcha.ai/api-reference/vendor-data-integration How to submit pre-existing vendor screening data to Parcha agents ## Overview When using certain Parcha agents (such as the IG AML Agent with `ig-aml-vendor-v1-demo`), you can provide pre-existing screening data from compliance vendors like ComplyAdvantage or Refinitiv. This allows you to leverage data you've already collected while still benefiting from Parcha's advanced analysis and risk assessment capabilities. When configured with `use_vendor_data_only = true`, the agent will not make fresh API calls to vendor services and will only process the vendor data included in your request. ## How It Works When you provide vendor data: 1. The agent skips vendor API calls (no fresh data fetching) 2. Uses the vendor data provided in your request 3. Still processes all weblinks in the vendor data: * Scrapes and analyzes article content * Extracts metadata from articles * Determines risk factors if not provided * Augments profiles with extracted information 4. Cross-references vendor hits with web presence data 5. Generates risk ratings based on the analysis The `use_vendor_data_only` flag only prevents new vendor API calls. All other processing (weblink scraping, LLM analysis, profile augmentation) still occurs. ## Vendor Data Specifications ### Adverse Media Screening Data Include adverse media profiles found by your vendor in the `adverse_media_event_check` section: ```json theme={null} { "adverse_media_event_check": { "vendor_data": { "vendor_case_id": "CA-123456", "vendor_case_internal_id": "abc12", "search_term": "John Doe", "vendor_adverse_media_profiles": [ { // Required fields "id": "profile-001", "full_name": "John Doe", // Recommended fields "associated_countries": ["USA", "GBR"], "associated_addresses": ["123 Main St, NYC"], "date_of_birth": "1990-01-01", "weblinks": [ { "id": "link-001", "title": "News Article", "url": "https://example.com/article" } ], // Optional fields "forename": "John", "surname": "Doe", "middle_name": "Michael", "aliases": ["J. Doe", "Johnny Doe"], "title": "Financial Fraud Investigation", "summary": "Involved in 2023 fraud case", "when": "2023-06-15", "topics": ["financial_crime", "fraud"], "age_as_of_today": 34, "gender": "male", "occupation": ["Business Executive"], "identification_info": "Passport: US123456", "biography_info": "Former executive at..." } ] } } } ``` **Required Fields:** * `id`: Unique identifier for the profile * `full_name`: Full name used for matching **Recommended Fields:** * `associated_countries`: Countries mentioned in adverse media * `associated_addresses`: Addresses mentioned * `date_of_birth`: For age verification (YYYY-MM-DD format) * `weblinks`: Source articles that will be processed **Optional Fields:** * Name components: `forename`, `surname`, `middle_name` * `aliases`: Alternative names * Event details: `title`, `summary`, `when`, `topics` * Demographics: `age_as_of_today`, `gender`, `occupation` * `identification_info`: ID documents mentioned * `biography_info`: Background information ### PEP Screening Data Include PEP (Politically Exposed Person) matches in the `pep_screening_check_v2` section: ```json theme={null} { "pep_screening_check_v2": { "vendor_data": { "vendor_case_id": "CA-789012", "vendor_case_internal_id": "def34", "search_term": "John Doe", "potential_pep_hits": [ { // Required fields "id": "pep-001", "full_name": "John Michael Doe", // Recommended fields "pep_type": "foreign", "pep_status": "current", "pep_title": "Deputy Minister of Finance", "associated_countries": ["GBR", "USA"], "date_of_birth": "1990-01-01", "roles": [ { "title": "Deputy Minister of Finance", "start_date": "2020-01-01", "end_date": null, "pep_type": "foreign", "status": "current" } ], // Optional fields "forename": "John", "middle_name": "Michael", "surname": "Doe", "aliases": ["J. Doe", "John M. Doe"], "associated_addresses": ["10 Downing St"], "location": "London, UK", "has_adverse_media": false, "biography_info": "Appointed in 2020...", "identification_info": "Passport: GB123456", "gender": "male", "age_as_of_today": 34, "known_associates": [ { "name": "Jane Doe", "association_type": "spouse", "entity_type": "person" } ], "relationships": [], "weblinks": [ { "id": "link-001", "title": "Official Biography", "url": "https://gov.uk/minister/doe" } ] } ] } } } ``` **Required Fields:** * `id`: Unique identifier * `full_name`: Full name for matching **Recommended Fields:** * `pep_type`: Values: `domestic`, `foreign`, `international_org` * `pep_status`: Values: `current`, `former` * `pep_title`: Official title * `associated_countries`: Countries of operation * `date_of_birth`: For verification * `roles`: Array of political roles with dates **Optional Fields:** * Name components and aliases * Location information * `has_adverse_media`: Boolean flag * Biography and identification details * `known_associates`: Associated persons/entities * `relationships`: Related PEP profiles ### Sanctions Screening Data Include sanctions matches in the `sanctions_screening_check_v2` section: ```json theme={null} { "sanctions_screening_check_v2": { "vendor_data": { "vendor_case_id": "CA-345678", "vendor_case_internal_id": "ghi56", "search_term": "John Doe", "potential_sanctions_hits": [ { // Required fields "id": "sanc-001", "full_name": "John Doe", // Recommended fields "associated_countries": ["IRN", "SYR"], "date_of_birth": "1990-01-01", "sanction_details": [ { "title": "OFAC SDN List", "detail": "Added for Iran sanctions violations", "jurisdiction": "USA", "list_date": "2023-01-15" } ], // Optional fields "forename": "John", "surname": "Doe", "middle_name": "Michael", "aliases": ["J. Doe"], "native_character_names": ["جان دو"], "associated_addresses": ["Tehran, Iran"], "location": "Tehran, Iran", "biography_info": "Business executive...", "identification_info": "Passport: IR123456", "gender": "male", "age_as_of_today": 34, "known_associates": [ { "name": "ABC Trading Co", "association_type": "business", "entity_type": "organization" } ], "relationships": [], "reports_origin": [ "OFAC SDN List Entry: Added 2023-01-15" ], "weblinks": [ { "id": "link-001", "title": "OFAC SDN Entry", "url": "https://sanctionssearch.ofac.treas.gov/Details.aspx?id=12345" } ] } ] } } } ``` **Required Fields:** * `id`: Unique identifier * `full_name`: Full name for matching **Recommended Fields:** * `associated_countries`: Sanctioning countries * `date_of_birth`: For verification * `sanction_details`: Array of sanction information with jurisdiction and dates **Optional Fields:** * Name components and aliases * `native_character_names`: Names in native script * Location and biographical information * `known_associates`: Associated entities * `reports_origin`: Source information ## Complete Example Request Here's a full example showing how to submit vendor data for all three screening types: ```json theme={null} { "agent_key": "ig-aml-vendor-v1-demo", "payload": { "id": "case-2024-001", "self_attested_data": { "first_name": "John", "middle_name": "Michael", "last_name": "Doe", "date_of_birth": "1990-01-01", "sex": "male", "email": "john.doe@example.com", "phone": "+1-555-123-4567", "address": { "street_1": "123 Main Street", "street_2": "Apt 4B", "city": "New York", "state": "NY", "country_code": "US", "postal_code": "10001" }, "country_of_nationality": "USA", "country_of_residence": "USA" }, "adverse_media_event_check": { "vendor_data": { "vendor_case_id": "CA-ADV-123", "search_term": "John Doe", "vendor_adverse_media_profiles": [ { "id": "adv-001", "full_name": "John Doe", "date_of_birth": "1990-01-01", "is_perpetrator": false, "topics": ["financial_crime"], "associated_countries": ["USA"], "weblinks": [ { "id": "link-002", "title": "Court Document", "url": "https://example.com/court-doc" } ] } ] } }, "pep_screening_check_v2": { "vendor_data": { "vendor_case_id": "CA-PEP-456", "search_term": "John Doe", "potential_pep_hits": [] } }, "sanctions_screening_check_v2": { "vendor_data": { "vendor_case_id": "CA-SANC-789", "search_term": "John Doe", "potential_sanctions_hits": [] } } } } ``` ## Important Notes ### General Guidelines * **Empty Results**: Use empty arrays (`[]`) when no matches are found * **Date Formats**: Use ISO 8601 format (YYYY-MM-DD) * **Country Codes**: Use ISO 3166-1 alpha-3 codes (USA, GBR, etc.) * **Topics**: Use standardized topic categories (e.g., "financial\_crime", "fraud", "money\_laundering") ### Field Requirements 1. **Minimal Required Fields**: * `id`: Unique identifier (auto-generated if not provided) * `full_name`: Critical for name matching * Other fields default to empty arrays/null if not provided 2. **Critical Fields for Risk Assessment**: * `is_perpetrator`: For adverse media - indicates if person was perpetrator vs victim/witness * `associated_countries`: For geographic matching * `topics`: For adverse media categorization * `date_of_birth`: For age/identity verification * `weblinks`: Source articles that will be scraped and processed ### Processing Behavior When you provide vendor data: * The agent will still process and analyze all weblinks * Missing fields like `is_perpetrator` will be determined through analysis * The agent will augment and enrich the vendor data with additional findings * Cross-referencing with web presence data still occurs for validation The vendor data integration feature allows you to leverage existing screening data while still benefiting from Parcha's advanced analysis, cross-referencing, and risk assessment capabilities. # null Source: https://docs.parcha.ai/api-reference/webhooks # Webhooks Webhooks allow you to receive real-time updates about results (and soon statuses) from the Parcha API. This guide explains how to use webhooks, including how to set them up, secure them with HMAC signatures, and test them. ## Setting Up Webhooks Parcha API supports two types of webhooks: 1. **Job Webhooks** (`webhook_url`): Receive notifications when the entire job is completed 2. **Tool Webhooks** (`tool_webhook_url`): Receive real-time updates each time an LLM tool is executed during the job You can specify either or both webhook URLs when initiating a job: ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-agent-key", "kyb_schema": { "id": "case-001", "self_attested_data": { "business_name": "Example Corp", "incorporation_documents": [ { "url": "https://example.com/document.pdf", "type": "Document", "file_name": "incorporation.pdf" } ] } }, "webhook_url": "https://your-webhook-url.com/job-callback", "tool_webhook_url": "https://your-webhook-url.com/tool-callback" }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' data = { "agent_key": "your-agent-key", "kyb_schema": { "id": "case-001", "self_attested_data": { "business_name": "Example Corp", "incorporation_documents": [ { "url": "https://example.com/document.pdf", "type": "Document", "file_name": "incorporation.pdf" } ] } }, "webhook_url": "https://your-webhook-url.com/job-callback", "tool_webhook_url": "https://your-webhook-url.com/tool-callback" } headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: "your-agent-key", kyb_schema: { id: "case-001", self_attested_data: { business_name: "Example Corp", incorporation_documents: [ { url: "https://example.com/document.pdf", type: "Document", file_name: "incorporation.pdf" } ] } }, webhook_url: "https://your-webhook-url.com/job-callback", tool_webhook_url: "https://your-webhook-url.com/tool-callback" }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ## Webhook Payloads ### Job Webhook Payload When a job is completed, Parcha API sends a POST request to your webhook URL with a payload containing job status information. **Note: The webhook payload contains job status updates only, not the full check results.** ```json theme={null} { "id": "e85e0cc4-b1e8-40b0-9a3d-83c328eee0f4", "agent_id": "remediation-v1", "status": "complete", "recommendation": "Approve", "created_at": "2024-09-18T18:30:00.000000", "updated_at": "2024-09-18T18:31:05.094700", "input_payload": { "id": "case-001", "self_attested_data": { "business_name": "Example Corp" } } } ``` ### Fetching Full Check Results To get the complete check results after receiving a webhook notification, use the `getJobById` endpoint with `include_check_results=true`: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=e85e0cc4-b1e8-40b0-9a3d-83c328eee0f4&include_check_results=true' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` Process webhook payloads quickly and asynchronously. Use the `job_id` from the webhook to fetch full results via the API when needed. ### Tool Webhook Payload Tool webhooks provide real-time updates for individual tool executions. You can filter events by tool ID. For example, `kyb.incorporation_document_extractor` provides events related to incorporation document checks in the following order: 1. Text extraction results (fastest) 2. Visual verification 3. Fraud detection (slowest) Here are examples of different tool webhook payloads: #### Text Extraction Results The text extraction event is typically the fastest and includes important validation and extracted data fields: ```json theme={null} { "job_id": "74f4634849d747a4b6546dfc35bdde29", "agent_instance_id": "c50aee83-45d6-48a2-800d-78e50ab5ea3f", "tool_id": "kyb.incorporation_document_extraction_tool", "results": { "explanation": "I analyzed the provided document and determined it is a valid Certificate of Incorporation for Parcha Labs, Inc. The document contains all necessary information including business name, incorporation date, registered agent address, and filing number.", "payload": { "extraction_data": { "is_valid_document": true, "analysis": "This document is a valid Certificate of Incorporation for Parcha Labs, Inc. It contains all the necessary elements of a valid incorporation document, including the business name, incorporation date, registered agent address, jurisdiction, and filing number.", "summary": "This document is a Certificate of Incorporation for Parcha Labs, Inc., filed with the Delaware Secretary of State on March 29, 2023. It outlines the company's basic information, including its name, registered agent, purpose, authorized shares, and various articles detailing the corporation's governance and legal matters.", "date": "2023-03-29", "alerts": null, "business_name": "Parcha Labs, Inc.", "all_business_names": [ "Parcha Labs, Inc." ], "incorporation_date": "2023-03-29", "business_address": { "type": "Address", "street_1": "251 Little Falls Drive", "street_2": null, "city": "Wilmington", "state": "Delaware", "country_code": "US", "postal_code": "19808" }, "all_extracted_addresses": { "registered_agent_address": { "type": "Address", "street_1": "251 Little Falls Drive", "street_2": null, "city": "Wilmington", "state": "Delaware", "country_code": "US", "postal_code": "19808" }, "incorporator_address": { "type": "Address", "street_1": "746 4th Avenue", "street_2": null, "city": "San Francisco", "state": "CA", "country_code": "US", "postal_code": "94118" } }, "business_activity": "To engage in any lawful act or activity for which corporations may be organized under the Delaware General Corporation Law", "jurisdiction": "Delaware", "business_registration_number": [ "7379553" ] } }, "passed": true, "answer": "The document is a valid Certificate of Incorporation for Parcha Labs, Inc., containing all necessary information for a Delaware corporation.", "alerts": null } } ``` Key fields in the extraction results include: * `is_valid_document`: Boolean indicating if the document is a valid incorporation document * `business_name`: The primary name of the business * `all_business_names`: Array of all business names found in the document * `incorporation_date`: The date of incorporation * `business_address`: The primary business address * `all_extracted_addresses`: Object containing all addresses found in the document, categorized by type * `business_activity`: The stated purpose or activity of the business * `jurisdiction`: The jurisdiction where the business is incorporated * `business_registration_number`: Array of registration numbers found in the document #### Visual Verification Results ```json theme={null} { "job_id": "74f4634849d747a4b6546dfc35bdde29", "agent_instance_id": "92e52dec-4ec1-4dc9-8040-25d9b78a525f", "tool_id": "kyb.visual_verification_v3", "results": { "explanation": "Visual verification of the document features", "payload": { "visual_inspection": { "type": "VisualInspectionResults", "comparison": "The Delaware Certificate of Incorporation for Parcha Labs, Inc. is consistent with other Delaware business registration documents reviewed.", "reasoning": "The document's authenticity is supported by several key features: (1) The presence of the official Delaware state seal, verifying the document's origin and jurisdiction. (2) The signature of Jeffrey W. Bullock, Secretary of State of Delaware, adds further validation. (3) The document's structure, layout, and content align with the standard format for Delaware Certificates of Incorporation. (4) The absence of any visible alterations or inconsistencies further supports its authenticity.", "visual_analysis": { "document_analysis_and_classification": { "analysis": "The document is a Certificate of Incorporation for Parcha Labs, Inc., filed in Delaware on March 29, 2023.", "passed": true }, "seal_verification": { "analysis": "The first page contains a Delaware state seal. The seal's design, text content, and unique identifiers are consistent with the expected Delaware state seal.", "passed": true, "present": true }, "signature_verification": { "analysis": "The document contains a signature attributed to Jeffrey W. Bullock, Secretary of State of Delaware.", "passed": true, "present": true }, "document_layout_and_content_verification": { "analysis": "The layout is consistent with a Delaware Certificate of Incorporation.", "passed": true }, "authenticity_verification": { "analysis": "The document appears authentic based on the presence of the official Delaware seal.", "passed": true }, "cross_referencing_and_consistency_check": { "analysis": "The business name, address, and key dates are consistent throughout the document.", "passed": true } }, "inspection_passed": true, "summary": "Visual inspection and comparison with other Delaware business registration documents indicate that the Certificate of Incorporation is authentic." } }, "passed": true } } ``` #### Fraud Detection Results ```json theme={null} { "job_id": "74f4634849d747a4b6546dfc35bdde29", "agent_instance_id": "8fab01c9-2a96-40ad-a01a-46e1b7a88db3", "tool_id": "document_fraud_check", "results": { "explanation": "The document verification analysis reveals significant concerns regarding potential fraud or tampering.", "payload": { "fraud_verification_data": { "verification_passed": false, "verification_result": "HIGH_RISK", "verification_data": [ { "indicator_id": "has_anomalous_hsv_regions", "type": "RISK", "category": "modifications", "title": "Document contains regions with font color inconsistency", "description": "This PDF document contains characters with color artefacts distinctively different from the rest of the document." }, { "indicator_id": "is_pdf_unmodified_per_metadata", "type": "TRUST", "category": "authenticity", "title": "No modification in document metadata", "description": "Timestamps in this document's metadata do not indicate that the file was incrementally updated or modified." }, { "indicator_id": "is_joined_pdf", "type": "INFO", "category": "known_creator", "title": "PDF is likely composed of more documents", "description": "This document has both selectable text and image pages." } ], "verification_description": "The document failed the fraud verification check due to high-risk indicators." } }, "passed": false } } ``` ## HMAC Signature Verification To ensure the security and authenticity of webhook payloads, Parcha API signs each webhook request with HMAC-SHA256 signatures. Two signatures are provided in the webhook request headers: 1. **Standard Signature** (`X-Signature-SHA256`): Signs the entire JSON payload 2. **Compact Signature** (`parcha-signature-compact`): Signs only the case ID for lightweight verification ### Standard Signature Verification The standard signature is included in the `X-Signature-SHA256` header and covers the entire request body. To verify the standard signature: 1. Compute the HMAC-SHA256 signature of the raw request body using your API secret key. 2. Compare this computed signature with the one in the `X-Signature-SHA256` header. Here's an example of how to verify the signature in Python: ```python theme={null} import hmac import hashlib import base64 def verify_signature(payload, signature, api_secret_key): computed_signature = base64.b64encode( hmac.new(api_secret_key.encode('utf-8'), payload, digestmod=hashlib.sha256).digest() ).decode('utf-8') return hmac.compare_digest(computed_signature, signature) # In your webhook handler: @app.route('/webhook', methods=['POST']) def handle_webhook(): payload = request.get_data() signature = request.headers.get('X-Signature-SHA256') if verify_signature(payload, signature, YOUR_API_SECRET_KEY): # Process the webhook data = request.json # ... handle the webhook data ... return 'Webhook received and verified', 200 else: return 'Invalid signature', 401 ``` ### Parcha Compact Signature The compact signature provides a lightweight alternative for verifying webhook authenticity without needing to process the entire payload. This signature is included in the `parcha-signature-compact` header and signs only the case ID from `input_payload.id`. **When to use the compact signature:** * When you need quick verification before processing large payloads * When you want to validate the webhook source using only the case ID * For implementing rate limiting or deduplication based on case ID * When you need to verify webhooks in environments with limited payload access **How the compact signature is generated:** 1. Extract the `id` field from `input_payload` in the webhook payload 2. Compute HMAC-SHA256 of the ID string using your API secret key 3. Base64 encode the resulting digest Here's an example of how to verify the compact signature: ```python Python theme={null} import hmac import hashlib import base64 import json def verify_compact_signature(payload_data, compact_signature, api_secret_key): """ Verify the Parcha compact signature using only the case ID. Args: payload_data: The parsed JSON payload (dict) compact_signature: The signature from the parcha-signature-compact header api_secret_key: Your API secret key Returns: bool: True if signature is valid, False otherwise """ # Extract the case ID from the payload case_id = payload_data.get('input_payload', {}).get('id') if not case_id: return False # Convert case ID to string and compute signature id_string = str(case_id) computed_signature = base64.b64encode( hmac.new( api_secret_key.encode('utf-8'), id_string.encode('utf-8'), digestmod=hashlib.sha256 ).digest() ).decode('utf-8') # Use constant-time comparison to prevent timing attacks return hmac.compare_digest(computed_signature, compact_signature) # In your webhook handler with both signatures: @app.route('/webhook', methods=['POST']) def handle_webhook(): # Get both signatures full_signature = request.headers.get('X-Signature-SHA256') compact_signature = request.headers.get('parcha-signature-compact') # Parse the payload payload_data = request.json raw_payload = request.get_data() # Option 1: Quick verification with compact signature if compact_signature and verify_compact_signature(payload_data, compact_signature, YOUR_API_SECRET_KEY): # Lightweight verification passed - process webhook case_id = payload_data['input_payload']['id'] # ... quick processing based on case_id ... return 'Webhook received', 200 # Option 2: Full verification with standard signature elif full_signature and verify_signature(raw_payload, full_signature, YOUR_API_SECRET_KEY): # Full verification passed - process complete payload # ... full processing ... return 'Webhook received and verified', 200 else: return 'Invalid signature', 401 ``` ```typescript TypeScript theme={null} import crypto from 'crypto'; function verifyCompactSignature( payloadData: any, compactSignature: string, apiSecretKey: string ): boolean { /** * Verify the Parcha compact signature using only the case ID. * * @param payloadData - The parsed JSON payload * @param compactSignature - The signature from the parcha-signature-compact header * @param apiSecretKey - Your API secret key * @returns True if signature is valid, false otherwise */ // Extract the case ID from the payload const caseId = payloadData?.input_payload?.id; if (!caseId) { return false; } // Convert case ID to string and compute signature const idString = String(caseId); const computedSignature = crypto .createHmac('sha256', apiSecretKey) .update(idString) .digest('base64'); // Use constant-time comparison to prevent timing attacks return crypto.timingSafeEqual( Buffer.from(computedSignature), Buffer.from(compactSignature) ); } // In your webhook handler with both signatures: app.post('/webhook', (req, res) => { // Get both signatures const fullSignature = req.headers['x-signature-sha256'] as string; const compactSignature = req.headers['parcha-signature-compact'] as string; const payloadData = req.body; const rawPayload = JSON.stringify(req.body); // Option 1: Quick verification with compact signature if (compactSignature && verifyCompactSignature(payloadData, compactSignature, YOUR_API_SECRET_KEY)) { // Lightweight verification passed - process webhook const caseId = payloadData.input_payload.id; // ... quick processing based on case_id ... res.status(200).send('Webhook received'); } // Option 2: Full verification with standard signature else if (fullSignature && verifySignature(rawPayload, fullSignature, YOUR_API_SECRET_KEY)) { // Full verification passed - process complete payload // ... full processing ... res.status(200).send('Webhook received and verified'); } else { res.status(401).send('Invalid signature'); } }); ``` ```javascript Node.js theme={null} const crypto = require('crypto'); function verifyCompactSignature(payloadData, compactSignature, apiSecretKey) { /** * Verify the Parcha compact signature using only the case ID. * * @param {Object} payloadData - The parsed JSON payload * @param {string} compactSignature - The signature from the parcha-signature-compact header * @param {string} apiSecretKey - Your API secret key * @returns {boolean} True if signature is valid, false otherwise */ // Extract the case ID from the payload const caseId = payloadData?.input_payload?.id; if (!caseId) { return false; } // Convert case ID to string and compute signature const idString = String(caseId); const computedSignature = crypto .createHmac('sha256', apiSecretKey) .update(idString) .digest('base64'); // Use constant-time comparison to prevent timing attacks return crypto.timingSafeEqual( Buffer.from(computedSignature), Buffer.from(compactSignature) ); } // In your webhook handler with both signatures: app.post('/webhook', (req, res) => { // Get both signatures const fullSignature = req.headers['x-signature-sha256']; const compactSignature = req.headers['parcha-signature-compact']; const payloadData = req.body; const rawPayload = JSON.stringify(req.body); // Option 1: Quick verification with compact signature if (compactSignature && verifyCompactSignature(payloadData, compactSignature, YOUR_API_SECRET_KEY)) { // Lightweight verification passed - process webhook const caseId = payloadData.input_payload.id; // ... quick processing based on case_id ... res.status(200).send('Webhook received'); } // Option 2: Full verification with standard signature else if (fullSignature && verifySignature(rawPayload, fullSignature, YOUR_API_SECRET_KEY)) { // Full verification passed - process complete payload // ... full processing ... res.status(200).send('Webhook received and verified'); } else { res.status(401).send('Invalid signature'); } }); ``` **Important notes:** * The compact signature is only present when the payload contains `input_payload.id` * Both signatures use the same API secret key * The compact signature signs the **string representation** of the case ID * Always use constant-time comparison (`hmac.compare_digest` or `crypto.timingSafeEqual`) to prevent timing attacks * The compact signature is useful for quick validation, but you should still verify the full signature for complete payload integrity ## Testing Your Webhooks Parcha API provides a `/api/v1/testWebhook` endpoint to help you test both job and tool webhooks. This endpoint sends sample payloads to your specified webhook URLs. ```bash cURL theme={null} curl -X POST 'https://demo.parcha.ai/api/v1/testWebhook' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "webhook_url": "https://your-webhook-url.com/job-callback", "tool_webhook_url": "https://your-webhook-url.com/tool-callback", "tool_webhook_ids": ["kyb.incorporation_document_extraction_tool"] }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://demo.parcha.ai/api/v1/testWebhook' data = { "webhook_url": "https://your-webhook-url.com/job-callback", "tool_webhook_url": "https://your-webhook-url.com/tool-callback", "tool_webhook_ids": ["kyb.incorporation_document_extraction_tool"] } headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } response = requests.post(url, json=data, headers=headers) print(response.json()) # {"message": "Webhook test successful"} ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://demo.parcha.ai/api/v1/testWebhook'; const data = { webhook_url: "https://your-webhook-url.com/job-callback", tool_webhook_url: "https://your-webhook-url.com/tool-callback", tool_webhook_ids: ["kyb.incorporation_document_extraction_tool"] }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) // {"message": "Webhook test successful"} .catch(error => console.error('Error:', error)); ``` The test endpoint will trigger webhooks for a sample job and send appropriate payloads to your specified URLs. You can test: * Job webhooks by providing a `webhook_url` * Tool webhooks by providing a `tool_webhook_url` * Filtered tool webhooks by also including `tool_webhook_ids` A successful test will return: ```json theme={null} { "message": "Webhook test successful" } ``` This allows you to verify your webhook implementation before processing real job events. ## Best Practices 1. Always verify the HMAC signature to ensure the authenticity of webhook payloads. 2. Implement proper error handling and retries in your webhook receiver to manage potential network issues or service interruptions. 3. Process webhook payloads asynchronously to avoid blocking your webhook receiver. 4. Store the raw payload for debugging purposes before processing it. 5. Respond quickly to the webhook request (ideally within a few seconds) to avoid timeouts. 6. When using tool webhooks, be prepared to handle events in any order as different tools have different processing times. 7. Consider implementing separate endpoints for job webhooks and tool webhooks to simplify processing logic. By following these guidelines and using the provided testing tools, you can ensure a robust and secure webhook integration with the Parcha API. # Authentication Source: https://docs.parcha.ai/authentication Learn how to authenticate your requests to the Parcha API Parcha API uses bearer token authentication for all endpoints. This method provides a secure way to authenticate your requests and access our API services. ## Obtaining an API Key Before you can start using the Parcha API, you need to obtain an API key. Follow these steps: 1. Sign up for a Parcha account at [https://app.parcha.ai](https://app.parcha.ai). 2. Once logged in, navigate to the API Keys section in your account settings. 3. Generate a new API key. Store your API key securely. It won't be displayed again after generation. If you lose it, you'll need to generate a new one. ## Using Your API Key To authenticate your requests, include your API key in the Authorization header as a Bearer token: ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` Replace `YOUR_API_KEY` with your actual Parcha API key. ## API Request Examples Here are examples of how to include the bearer token in API requests using various programming languages: You also need your **agent key** which identifies which agent to use. Find your agent key in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "kyb_schema": { "id": "parcha-demo-case-001", "self_attested_data": { "business_name": "Acme Corp", "website": "https://www.acmecorp.com" } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'kyb_schema': { 'id': 'parcha-demo-case-001', 'self_attested_data': { 'business_name': 'Acme Corp', 'website': 'https://www.acmecorp.com' } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key kyb_schema: { id: 'parcha-demo-case-001', self_attested_data: { business_name: 'Acme Corp', website: 'https://www.acmecorp.com' } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ## Error Handling If you provide an invalid or expired API key, you'll receive a 401 Unauthorized response. Here's an example of what this might look like: ```json theme={null} { "error": "Unauthorized", "message": "Invalid API key provided" } ``` If you encounter this error, double-check that you're using the correct API key and that it hasn't been revoked or expired. ## API Key Best Practices To ensure the security of your Parcha account and data, follow these best practices: 1. **Keep it secret**: Never share your API key publicly or with unauthorized parties. 2. **Use environment variables**: Store your API key in environment variables rather than hardcoding it in your application. 3. **Rotate regularly**: Periodically generate new API keys and update your applications to use the new keys. 4. **Limit exposure**: Use different API keys for different environments (development, staging, production) to limit the impact of a compromised key. 5. **Monitor usage**: Regularly review your API usage logs to detect any unauthorized access or unusual activity. 6. **Least privilege**: If possible, use scoped API keys that only have the permissions necessary for the specific tasks they need to perform. 7. **Secure transmission**: Always use HTTPS when making API requests to ensure your API key is transmitted securely. ## Revoking API Keys If you suspect that an API key has been compromised, you should immediately revoke it: 1. Log in to your Parcha account. 2. Navigate to the API Keys section in your account settings. 3. Find the compromised key and click the "Revoke" or "Delete" button. 4. Generate a new API key to replace the revoked one. 5. Update all your applications and scripts to use the new API key. By following these authentication guidelines and best practices, you'll be able to securely access and utilize the full power of the Parcha API for your KYB and KYC processes. # Address Verification Check Source: https://docs.parcha.ai/checks/addresses-check Verify business addresses and validate physical location presence The Address Verification check validates that a business operates from a legitimate physical address and identifies any additional addresses associated with the business. This check helps detect virtual offices, mail drops, and other address-related risks. ## Overview The check examines: * Physical address validation * Address type identification (residential, commercial, PO Box, etc.) * Multiple address associations * Address consistency across sources * Geographic verification ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.addresses_check"` for address verification. The business information for verification. A unique identifier for this check case. The legal name of the business to verify. The street address of the business. The city where the business is located. The state or region where the business is located. The postal or ZIP code. The country code (ISO 3166-1 alpha-2). Registered address if different from operational address. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.addresses_check", "payload": { "id": "address-check-001", "self_attested_data": { "business_name": "Acme Corporation", "address_of_operation": { "street_address": "123 Main Street", "city": "San Francisco", "state": "CA", "postal_code": "94102", "country_code": "US" } } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.addresses_check', 'payload': { 'id': 'address-check-001', 'self_attested_data': { 'business_name': 'Acme Corporation', 'address_of_operation': { 'street_address': '123 Main Street', 'city': 'San Francisco', 'state': 'CA', 'postal_code': '94102', 'country_code': 'US' } } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.addresses_check', payload: { id: 'address-check-001', self_attested_data: { business_name: 'Acme Corporation', address_of_operation: { street_address: '123 Main Street', city: 'San Francisco', state: 'CA', postal_code: '94102', country_code: 'US' } } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The address verification check follows these steps: 1. **Address Validation** * Validates address format and completeness * Verifies address exists in postal databases * Checks for geocoding accuracy 2. **Address Type Detection** * Identifies if address is residential, commercial, or mixed-use * Detects PO Boxes, mail forwarding services, or virtual offices * Flags registered agent addresses 3. **Cross-Reference Analysis** * Compares operational address with incorporation address * Searches for additional addresses associated with the business * Validates address consistency across data sources 4. **Risk Assessment** * Evaluates address legitimacy for business operations * Identifies high-risk address types * Assesses physical presence indicators ## Check Results ### Response Structure ```typescript theme={null} { type: "AddressesCheckResult"; passed: boolean; operational_address: AddressValidation; incorporation_address?: AddressValidation; additional_addresses?: Array; risk_flags?: Array; } type AddressValidation = { address: string; validated: boolean; address_type: "commercial" | "residential" | "mixed" | "po_box" | "virtual" | "registered_agent"; geocoded: boolean; coordinates?: { latitude: number; longitude: number; }; verification_source?: string; } type RiskFlag = { type: string; severity: "low" | "medium" | "high"; description: string; } ``` ### Example Results ```json Low Risk theme={null} { "type": "AddressesCheckResult", "passed": true, "operational_address": { "address": "123 Main Street, San Francisco, CA 94102", "validated": true, "address_type": "commercial", "geocoded": true, "coordinates": { "latitude": 37.7749, "longitude": -122.4194 }, "verification_source": "Google Places" }, "additional_addresses": [], "risk_flags": [] } ``` ```json Medium Risk theme={null} { "type": "AddressesCheckResult", "passed": true, "operational_address": { "address": "456 Oak Avenue, Austin, TX 78701", "validated": true, "address_type": "residential", "geocoded": true, "coordinates": { "latitude": 30.2672, "longitude": -97.7431 } }, "risk_flags": [ { "type": "residential_address", "severity": "medium", "description": "Business operates from a residential address" } ] } ``` ```json High Risk theme={null} { "type": "AddressesCheckResult", "passed": false, "operational_address": { "address": "PO Box 1234, Wilmington, DE 19850", "validated": true, "address_type": "po_box", "geocoded": false }, "risk_flags": [ { "type": "invalid_address_type", "severity": "high", "description": "PO Box addresses are not acceptable for business operations" }, { "type": "no_physical_presence", "severity": "high", "description": "No verifiable physical business location found" } ] } ``` ## Risk Factors The check may flag concerns if: * Address is a PO Box or mail forwarding service * Address is a registered agent address (common in Delaware) * Address is a virtual office with no physical presence * Address cannot be validated or geocoded * Multiple businesses operate from the same residential address * Operational address differs significantly from incorporation address * Address is in a high-risk jurisdiction ## Best Practices 1. **Require Physical Addresses**: Don't accept PO Boxes for business operations 2. **Verify Consistency**: Ensure addresses match across documents 3. **Check Multiple Sources**: Cross-reference with business directories and government databases 4. **Document Changes**: Track address changes over time 5. **Combine with Other Checks**: Use alongside incorporation and business profile checks ## Related Checks * [Proof of Address Document Verification](/checks/proof-of-address-document-verification) - Verify address documents * [Incorporation Document Verification](/checks/incorporation-document-verification) - Verify registration address * [Basic Business Profile Check](/checks/basic-business-profile-check) - Verify overall business profile * [Web Presence Check](/checks/web-presence-check) - Verify online presence includes address # Adverse Media Screening Check Source: https://docs.parcha.ai/checks/adverse-media-screening Learn how to run adverse media screening checks to identify potential risks associated with businesses The Adverse Media Screening check helps identify potential risks by analyzing news articles, media coverage, and customer reviews related to a business. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Overview The check searches through various news sources and review platforms to identify: * Negative news coverage * Regulatory investigations * Legal proceedings * Customer complaints * Reputational issues ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.adverse_media_screening_check_v2"` for adverse media screening. The business information for screening. A unique identifier for this check case. The legal name of the business to screen. The country code where the business is incorporated (ISO 3166-1 alpha-2). The country code where the business operates (ISO 3166-1 alpha-2). The business's incorporation date (YYYY-MM-DD format). List of country codes where the business has customers. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.adverse_media_screening_check_v2", "kyb_schema": { "id": "adverse-media-check-001", "self_attested_data": { "business_name": "Acme Corp", "address_of_incorporation": { "country_code": "US" }, "address_of_operation": { "country_code": "US" }, "incorporation_date": "2020-01-15", "customer_countries": ["US", "CA", "GB"] } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.adverse_media_screening_check_v2', 'payload': { 'id': 'adverse-media-check-001', 'self_attested_data': { 'business_name': 'Acme Corp', 'address_of_incorporation': { 'country_code': 'US' }, 'address_of_operation': { 'country_code': 'US' }, 'incorporation_date': '2020-01-15', 'customer_countries': ['US', 'CA', 'GB'] } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.adverse_media_screening_check_v2', payload: { id: 'adverse-media-check-001', self_attested_data: { business_name: 'Acme Corp', address_of_incorporation: { country_code: 'US' }, address_of_operation: { country_code: 'US' }, incorporation_date: '2020-01-15', customer_countries: ['US', 'CA', 'GB'] } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The adverse media screening check follows these steps: 1. **Data Collection** * Searches news archives and media databases * Analyzes customer review platforms * Gathers information from business registries 2. **Match Analysis** * Compares business names and aliases * Validates geographic relevance * Checks temporal relevance (based on incorporation date) * Evaluates source credibility 3. **Risk Assessment** * Categorizes findings by severity * Analyzes impact on business operations * Evaluates reputational risk ## Check Results Once the check is complete, you can retrieve the results using the check ID. The results will include: ### Response Structure ```typescript theme={null} { type: "KYBAdverseMediaScreeningCheckResultV2"; verified_adverse_media_hits: Array; } type BusinessAdverseMediaProfile = { profile_review: { match_rating: { match: "STRONG_MATCH" | "PARTIAL_MATCH" | "WEAK_MATCH" | "NO_MATCH" | "UNKNOWN"; score: number; }; business_name_match: boolean; location_match: boolean; summarize: () => string; }; business_name: string | null; location: string | null; adverse_events: Array<{ event_type: string; description: string; source_url: string | null; source_name: string | null; publication_date: string | null; }>; escalate_for_review: boolean; } ``` ### Example Result ```json theme={null} { "type": "KYBAdverseMediaScreeningCheckResultV2", "verified_adverse_media_hits": [ { "profile_review": { "match_rating": { "match": "STRONG_MATCH", "score": 95 }, "business_name_match": true, "location_match": true }, "business_name": "Company XYZ Inc", "location": "Delaware, US", "adverse_events": [ { "event_type": "Regulatory Investigation", "description": "Company XYZ is under investigation for potential compliance violations regarding financial reporting practices", "source_url": "https://example.com/article1", "source_name": "Business News Daily", "publication_date": "2024-01-15" }, { "event_type": "Civil Litigation", "description": "Class action lawsuit filed against Company XYZ alleging securities fraud", "source_url": "https://example.com/article2", "source_name": "Legal News", "publication_date": "2024-02-01" } ], "escalate_for_review": true } ] } ``` ## Risk Categories The check evaluates findings across different risk levels: ### High Risk * Criminal activities * Regulatory violations * Major legal issues * Severe financial problems * Significant fraud allegations ### Medium Risk * Customer complaints * Service issues * Minor legal disputes * Operational problems * Negative reviews ### Low Risk * Isolated incidents * Minor complaints * Resolved issues * Historical events * Non-material concerns ## Best Practices 1. **Provide Accurate Business Information** * Use the legal business name * Include all known operating countries * Specify accurate incorporation date 2. **Consider Time Frames** * Recent events (within 1 year) are most relevant * Historical events may require context * Consider the business's age when evaluating findings 3. **Evaluate Results Holistically** * Consider the credibility of sources * Look for patterns in findings * Assess the severity and frequency of issues 4. **Follow Up Actions** * Document significant findings * Investigate serious allegations * Consider additional due diligence if needed ## Error Handling Common errors and their solutions: | Error Code | Description | Solution | | ---------- | ----------------------- | --------------------------------------------------------- | | 400 | Missing required fields | Ensure all required fields are provided in the payload | | 401 | Invalid API key | Check your API key is valid and has necessary permissions | | 429 | Rate limit exceeded | Implement appropriate request rate limiting | | 500 | Internal server error | Retry the request after a short delay | ## Limitations * The check only covers publicly available information * Results may vary based on the availability of data in different jurisdictions * Some sources may have delayed reporting of incidents * Coverage may be limited in certain geographic regions ## Support If you encounter any issues or need assistance: * Email: [support@parcha.ai](mailto:support@parcha.ai) * Documentation: [https://docs.parcha.ai](https://docs.parcha.ai) * API Status: [https://status.parcha.ai](https://status.parcha.ai) # Basic Business Profile Check Source: https://docs.parcha.ai/checks/basic-business-profile-check Learn how to run basic business profile checks to verify fundamental business information The Basic Business Profile check helps verify the authenticity of fundamental business information by comparing self-attested data against information found through web research. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Overview The check verifies several key aspects of a business's profile: * Business name and registration * Business description and activities * Industry classification * Operating status * Basic contact information ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.basic_business_profile_check"` for basic profile verification. The business information for verification. A unique identifier for this check case. The legal name of the business to verify. A detailed description of the business's activities. The industry in which the business operates. The official website URL of the business. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.basic_business_profile_check", "kyb_schema": { "id": "basic-profile-check-001", "self_attested_data": { "business_name": "Parcha Labs Inc", "business_description": "Business verification and compliance platform", "industry": "Financial Technology Services", "website": "https://parcha.ai" } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.basic_business_profile_check', 'payload': { 'id': 'basic-profile-check-001', 'self_attested_data': { 'business_name': 'Parcha Labs Inc', 'business_description': 'Business verification and compliance platform', 'industry': 'Financial Technology Services', 'website': 'https://parcha.ai' } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.basic_business_profile_check', payload: { id: 'basic-profile-check-001', self_attested_data: { business_name: 'Parcha Labs Inc', business_description: 'Business verification and compliance platform', industry: 'Financial Technology Services', website: 'https://parcha.ai' } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The basic business profile check follows these steps: 1. **Data Collection** * Gathers information from business registries * Searches web sources and directories * Analyzes business websites * Reviews professional networks 2. **Profile Analysis** * Validates business name and registration * Verifies business description * Confirms industry classification * Cross-references contact information 3. **Consistency Check** * Compares data across sources * Identifies discrepancies * Evaluates information reliability * Assesses overall profile consistency ## Check Results Once the check is complete, you can retrieve the results using the check ID. The results will include: ### Response Structure ```json theme={null} { "command_instance_id": "string", "command_name": "string", "command_id": "string", "answer": "string", "passed": "boolean", "verified_data": { "type": "BasicBusinessProfileCheckData", "business_name_found": { "source_id": "string", "evidence": "string", "business_name": "string" }, "contact_info_found": { /* Populated object or null, see example for detailed structure */ }, "business_industry_found": { /* Populated object or null, see example for detailed structure */ }, "business_locations_found": [ /* Array of location objects, see example for detailed structure */ ], "investment_received_found": "object | null", "backed_by_found": "object | null", "estimated_range_num_employees_found": { /* Populated object or null, see example for detailed structure */ }, "launched_or_incorporated_date_found": { /* Populated object or null, see example for detailed structure */ }, "business_profile_urls": ["string", "..."], "social_media_urls": ["string", "..."], "business_profile_source_ids": ["string", "..."], "social_media_source_ids": ["string", "..."] }, "check_result": { "type": "BasicBusinessProfileCheckResult", "business_name_match": { "exact_match": "boolean", "partial_match": "boolean", "source_ids": ["string", "..."], "explanation": "string", "name": "string" } | null, "business_description_match": { /* Populated object or null, see example for detailed structure */ } | null, "business_industry_match": { /* Populated object or null, see example for detailed structure */ } | null }, "status": "string", "agent_instance_id": "string", "case_type": "string", "status_messages": [ /* Array of status message objects, see example for detailed structure */ ], "created_at": "string", "input_data": { "business_name": "string", "business_description": "string | null", "business_industry": "string | null" }, "alerts": {}, "recommendation": "string | null", "business_name": "string", "registered_business_name": "string | null" } ``` ## Key Components ### Business Identity Verification * Validates business name across multiple sources * Confirms business description accuracy * Verifies industry classification ### Profile Analysis * Cross-references self-attested information * Evaluates consistency of business details * Identifies potential discrepancies ### Data Sources * Official business websites * Business registrations * Industry directories * News and media coverage * Professional networks ## Interpreting the Check Output The Basic Business Profile Check provides a detailed output that helps you understand the verification process and its findings. Here's a breakdown of an example output and how to interpret its key components. ### Example Check Output ```json theme={null} { "command_instance_id": "5a01581ceda046568e1b287dad57edb3", "command_name": "Basic Profile Check", "command_id": "kyb.basic_business_profile_check", "answer": "The business profile check has passed because the self-reported business name \\"Acme Innovations Ltd.\\" exactly matches the verified information. No business description or industry was self-reported, so these fields were not considered in the verification process.", "passed": true, "verified_data": { "type": "BasicBusinessProfileCheckData", "business_name_found": { "source_id": "sample123", "evidence": "The business name appears on their official website as 'Acme Innovations Ltd.'", "business_name": "Acme Innovations Ltd." }, "contact_info_found": { "type": "FoundContactInfo", "email": { "source_id": "sample123", "evidence": "Contact email listed as contact@acmeinnovations.example.com", "email": "contact@acmeinnovations.example.com" }, "phone": { "source_id": "sample456", "evidence": "Phone number listed on directory: (555) 123-4567", "phone": "(555) 123-4567" } }, "business_industry_found": { "source_id": "sample789", "evidence": "Listed under 'Software Development' in industry catalog.", "industry": "Technology", "business_activity": "Develops and markets enterprise software solutions for various industries. Specializes in cloud-based CRM and data analytics tools." }, "business_locations_found": [ { "source_id": "sample123", "evidence": "Headquarters: 123 Innovation Drive, Tech City, TC 54321", "address": { "type": "AddressWithType", "street_1": "123 Innovation Drive", "street_2": "Suite 100", "city": "Tech City", "state": "TC", "country_code": "US", "postal_code": "54321", "address_type": "headquarters" } }, { "source_id": "sample456", "evidence": "Branch Office: 456 Future Road, Metroville, MV 67890", "address": { "type": "AddressWithType", "street_1": "456 Future Road", "street_2": null, "city": "Metroville", "state": "MV", "country_code": "US", "postal_code": "67890", "address_type": "branch" } } ], "investment_received_found": null, "backed_by_found": null, "estimated_range_num_employees_found": { "source_id": "sample789", "evidence": "Company profile indicates 50-100 employees.", "estimated_range_num_employees": "50-100" }, "launched_or_incorporated_date_found": { "source_id": "sample123", "evidence": "Established in 2010.", "launched_or_incorporated_date": "2010-03-15" }, "business_profile_urls": [ "https://www.acmeinnovations.example.com", "https://www.businessdirectory.example.com/acme-innovations" ], "social_media_urls": [ "https://www.linkedin.example.com/company/acme-innovations" ], "business_profile_source_ids": [ "sample123", "sample456", "sample789" ], "social_media_source_ids": [ "sampleLinkedIn" ] }, "check_result": { "type": "BasicBusinessProfileCheckResult", "business_name_match": { "exact_match": true, "partial_match": false, "source_ids": [ "sample123" ], "explanation": "The business name \\"Acme Innovations Ltd.\\" appears in the verified source exactly as self-reported.", "name": "Acme Innovations Ltd." }, "business_description_match": null, "business_industry_match": null }, "status": "complete", "agent_instance_id": "437c1d2a29d9465a8fc1304e457942df", "case_type": "business", "status_messages": [ { "updated_at": "2025-05-20T19:59:55.512531", "id": "6cf21f64-96a3-43cd-9791-004d6e633364", "timestamp": "2025-05-20T19:59:55.512544", "content": { "agent_key": "your-agent-key-here", "status": "Loading: WebPresence Data Loader...", "command_instance_id": "5a01581ceda046568e1b287dad57edb3", "command_id": "kyb.basic_business_profile_check", "command_name": "KYB Basic Business Profile Check", "is_agent_status": null, "agent_name": "Business Due Diligence Agent", "agent_instance_id": "437c1d2a29d9465a8fc1304e457942df", "command_args": null }, "command_instance_id": "5a01581c-eda0-4656-8e1b-287dad57edb3", "created_at": "2025-05-20T19:59:55.512527", "job_id": "67664a52-96f2-4845-a74f-dc341fd0cc17", "event": "status", "agent_instance_id": "437c1d2a-29d9-465a-8fc1-304e457942df" } ], "created_at": "2025-05-20T19:59:52.994494", "input_data": { "business_name": "Acme Innovations Ltd.", "business_description": null, "business_industry": null }, "alerts": {}, "recommendation": null, "business_name": "ACME INNOVATIONS LTD.", "registered_business_name": null } ``` ### Key Fields Explained #### `passed` (boolean) This field is a straightforward indicator of the check's outcome. * `true`: The self-attested information (primarily the business name, in this example) aligns with the verified data found through research. If certain fields like business description or industry are not provided by the user, they are typically considered as matching by default, as per the check's logic. * `false`: There are significant discrepancies between the self-attested information and the verified data. For instance, if the self-reported business name was "Acme Software" but research consistently showed "Acme Hardware," the check would likely fail. Or, if the business claimed to be in "Retail" but was found to be in a "High-Risk Financial Services" industry. #### `verified_data` (object) This section contains the comprehensive profile of the business as assembled from various online sources. It represents the "ground truth" that Parcha discovered. * **`business_name_found`**: Details about the business name as found by research, including the source and evidence. * `business_name`: "Acme Innovations Ltd." (The name found by Parcha) * **`contact_info_found`**: Contact details like email and phone numbers. * `email`: "[contact@acmeinnovations.example.com](mailto:contact@acmeinnovations.example.com)" * `phone`: "(555) 123-4567" * **`business_industry_found`**: The industry and specific business activities identified. * `industry`: "Technology" * `business_activity`: "Develops and markets enterprise software solutions..." * **`business_locations_found`**: An array of physical addresses associated with the business, each with source and evidence. * Address 1: "123 Innovation Drive, Tech City..." (headquarters) * Address 2: "456 Future Road, Metroville..." (branch) * **`estimated_range_num_employees_found`**: If found, an estimation of the company's size. * `estimated_range_num_employees`: "50-100" * **`launched_or_incorporated_date_found`**: The date the business was reportedly established or incorporated. * `launched_or_incorporated_date`: "2010-03-15" * **`business_profile_urls`**: URLs to official business profiles (e.g., company website, directory listings). * **`social_media_urls`**: URLs to social media pages associated with the business. * **`business_profile_source_ids`** and **`social_media_source_ids`**: Internal identifiers for the sources of this information. Other fields like `investment_received_found` and `backed_by_found` would be populated if such information was discovered during the research phase. #### `check_result` (object) This section details the comparison between the `input_data` (what the user provided) and the `verified_data` (what Parcha found). * **`type`**: "BasicBusinessProfileCheckResult" - Identifies the type of check result. * **`business_name_match`**: * `exact_match`: `true` - Indicates if the self-reported name is an exact match to a verified name. * `partial_match`: `false` - Would be true if there was a close but not exact match (e.g., "Acme Innovations" vs "Acme Innovations Ltd."). * `source_ids`: \["sample123"] - The source(s) that confirmed this match. * `explanation`: Provides a human-readable reason for the match status. * `name`: "Acme Innovations Ltd." (The name that was compared). * **`business_description_match`**: `null` in this example because no business description was provided in the `input_data`. If a description *had* been provided, this section would detail whether it matched the `verified_data.business_industry_found.business_activity`. * **`business_industry_match`**: `null` for the same reason as above. If an industry *had* been provided, this would show how it compared to `verified_data.business_industry_found.industry`. #### Other Important Fields * **`answer`**: An AI-generated summary explaining the overall outcome of the check in natural language. * **`input_data`**: Shows the information that was initially provided for the check (e.g., "Acme Innovations Ltd." as `business_name`, with `business_description` and `business_industry` being `null`). * **`status_messages`**: A log of the different steps and API calls made during the check execution. This is useful for debugging or understanding the check's progression. By examining these sections, you can understand not only *if* the business profile passed verification but also *why*, based on the data found and how it compares to the information your system had on file. # Business Owners Research Check Source: https://docs.parcha.ai/checks/business-owners-check Identify and verify business owners and beneficial ownership through online research The Business Owners Research check identifies individuals associated with business ownership through online research and cross-references them with self-attested ownership data. This check helps verify ownership structure and identify ultimate beneficial owners (UBOs). ## Overview The check examines: * Online mentions of business owners and leadership * LinkedIn profiles and professional networks * Corporate registry data * News articles and press releases * Company websites and about pages * Social media profiles ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.business_owners_check"` for business owners research. The business information for verification. A unique identifier for this check case. The legal name of the business to verify. The official website URL of the business. Array of self-attested owners to verify. Owner's first name. Owner's last name. Must be true for owners. Ownership percentage (0-100). Job title or role in the company. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.business_owners_check", "payload": { "id": "owners-check-001", "self_attested_data": { "business_name": "TechCorp Inc", "website": "https://techcorp.example", "associated_individuals": [ { "first_name": "Jane", "last_name": "Smith", "is_business_owner": true, "business_ownership_percentage": 51, "title": "CEO & Founder" }, { "first_name": "John", "last_name": "Doe", "is_business_owner": true, "business_ownership_percentage": 49, "title": "CTO & Co-Founder" } ] } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.business_owners_check', 'payload': { 'id': 'owners-check-001', 'self_attested_data': { 'business_name': 'TechCorp Inc', 'website': 'https://techcorp.example', 'associated_individuals': [ { 'first_name': 'Jane', 'last_name': 'Smith', 'is_business_owner': True, 'business_ownership_percentage': 51, 'title': 'CEO & Founder' }, { 'first_name': 'John', 'last_name': 'Doe', 'is_business_owner': True, 'business_ownership_percentage': 49, 'title': 'CTO & Co-Founder' } ] } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.business_owners_check', payload: { id: 'owners-check-001', self_attested_data: { business_name: 'TechCorp Inc', website: 'https://techcorp.example', associated_individuals: [ { first_name: 'Jane', last_name: 'Smith', is_business_owner: true, business_ownership_percentage: 51, title: 'CEO & Founder' }, { first_name: 'John', last_name: 'Doe', is_business_owner: true, business_ownership_percentage: 49, title: 'CTO & Co-Founder' } ] } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The business owners research check follows these steps: 1. **Online Research** * Searches LinkedIn for company leadership * Analyzes company website team pages * Reviews business directories and registries * Examines news articles and press releases 2. **Owner Identification** * Identifies individuals in leadership roles * Extracts ownership and title information * Builds ownership structure from public data 3. **Verification** * Cross-references found owners with self-attested data * Validates names, titles, and ownership percentages * Identifies discrepancies or missing owners 4. **Risk Assessment** * Flags undisclosed owners with significant stakes * Identifies ownership structure concerns * Evaluates transparency of ownership information ## Check Results ### Response Structure ```typescript theme={null} { type: "BusinessOwnersCheckResult"; passed: boolean; identified_owners: Array; self_attested_owners: Array; match_results: Array; discrepancies?: Array; } type IdentifiedOwner = { name: string; title?: string; ownership_percentage?: number; source: string; source_url?: string; confidence_score: number; } type OwnerMatch = { self_attested_owner: string; identified_owner?: string; match_status: "verified" | "partial_match" | "not_found" | "mismatch"; confidence_score?: number; } type Discrepancy = { type: string; severity: "low" | "medium" | "high"; description: string; } ``` ### Example Results ```json Low Risk - All Owners Verified theme={null} { "type": "BusinessOwnersCheckResult", "passed": true, "identified_owners": [ { "name": "Jane Smith", "title": "CEO & Founder", "ownership_percentage": 51, "source": "LinkedIn", "source_url": "https://linkedin.com/in/janesmith", "confidence_score": 95 }, { "name": "John Doe", "title": "CTO & Co-Founder", "ownership_percentage": 49, "source": "Company Website", "source_url": "https://techcorp.example/about", "confidence_score": 92 } ], "match_results": [ { "self_attested_owner": "Jane Smith", "identified_owner": "Jane Smith", "match_status": "verified", "confidence_score": 95 }, { "self_attested_owner": "John Doe", "identified_owner": "John Doe", "match_status": "verified", "confidence_score": 92 } ], "discrepancies": [] } ``` ```json Medium Risk - Partial Verification theme={null} { "type": "BusinessOwnersCheckResult", "passed": true, "identified_owners": [ { "name": "Jane Smith", "title": "CEO", "source": "LinkedIn", "confidence_score": 88 } ], "match_results": [ { "self_attested_owner": "Jane Smith", "identified_owner": "Jane Smith", "match_status": "verified", "confidence_score": 88 }, { "self_attested_owner": "John Doe", "match_status": "not_found" } ], "discrepancies": [ { "type": "owner_not_verified", "severity": "medium", "description": "Self-attested owner John Doe (49% ownership) could not be verified online" } ] } ``` ```json High Risk - Undisclosed Owners Found theme={null} { "type": "BusinessOwnersCheckResult", "passed": false, "identified_owners": [ { "name": "Jane Smith", "title": "CEO", "ownership_percentage": 40, "source": "OpenCorporates", "confidence_score": 92 }, { "name": "Michael Brown", "title": "Chairman", "ownership_percentage": 60, "source": "OpenCorporates", "confidence_score": 90 } ], "match_results": [ { "self_attested_owner": "Jane Smith", "identified_owner": "Jane Smith", "match_status": "verified", "confidence_score": 92 } ], "discrepancies": [ { "type": "undisclosed_owner", "severity": "high", "description": "Major owner Michael Brown (60% ownership) not disclosed in application" }, { "type": "ownership_mismatch", "severity": "high", "description": "Jane Smith's ownership differs: stated 100%, found 40%" } ] } ``` ## Risk Factors The check may flag concerns if: * Self-attested owners cannot be verified online * Additional owners found who were not disclosed * Ownership percentages don't match between sources * Complex or opaque ownership structures * Frequent changes in ownership * No ownership information publicly available * Owners appear on sanctions or PEP lists ## Configuration Options The check can be configured with: * **enable\_linkedin\_search**: Search LinkedIn for owners * **enable\_open\_search**: Use open web search for ownership data * **enable\_ubo\_search**: Search for ultimate beneficial owners * **enable\_opencorporates**: Include OpenCorporates registry data * **enable\_smart\_crawling**: Crawl company websites for team pages * **use\_web\_presence\_data**: Use web presence check data for context ## Best Practices 1. **Request Complete Information**: Ask for all owners with 25%+ stakes 2. **Cross-Verify**: Use multiple sources to confirm ownership 3. **Document Sources**: Track where ownership information comes from 4. **Regular Updates**: Re-verify ownership periodically 5. **Combine Checks**: Use alongside ownership document verification ## Related Checks * [Business Ownership Document Verification](/checks/business-ownership-document-verification) - Verify ownership documents * [Basic Business Profile Check](/checks/basic-business-profile-check) - Verify business profile * [Web Presence Check](/checks/web-presence-check) - Research online presence * [Sanctions Screening](/checks/sanctions-screening-check) - Screen owners against sanctions lists # Business Ownership Document Verification Source: https://docs.parcha.ai/checks/business-ownership-document-verification Learn how to run business ownership document verification checks to validate business ownership information The Business Ownership Document Verification check helps verify the authenticity of business ownership documents and validates the ownership structure of a business. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Check ID `kyb.business_ownership_verification_tool` ## Overview The check analyzes various aspects of business ownership documents: * Document authenticity and validity * Business owner verification * Ownership share validation * Document type verification * Total ownership verification ## How the Check Works 1. **Document Analysis** * Extracts key information from business ownership documents * Validates document structure and format * Verifies document authenticity * Identifies business owners and their ownership shares 2. **Information Verification** * Cross-references extracted data with self-attested information * Validates business owner names match * Confirms ownership shares * Verifies total ownership percentage 3. **Ownership Validation** * Verifies all significant owners (≥25%) are disclosed * Validates ownership shares add up to expected total * Checks for missing or undocumented owners * Ensures ownership information is complete and accurate ### Document Requirements The following information must be present in the business ownership documents for it to be considered valid: #### Cap Table or Share Register * Names of all shareholders/owners * Number of shares or ownership percentage for each owner * Total number of shares or ownership percentages must sum to 100% * Date of ownership information #### Operating Agreement * Names of all members/owners * Ownership percentages or shares for each member * Roles and responsibilities of members * Date of agreement #### Share Certificates * Name of shareholder * Number of shares owned * Class of shares * Date of issuance * Company name and registration details #### Partnership Agreement * Names of all partners * Partnership type (general, limited, etc.) * Ownership percentages or profit-sharing ratios * Date of agreement #### Articles of Organization (if sole proprietorship) * Name of sole owner * Business name * Date of organization * Confirmation of 100% ownership ## Check Configuration The check can be configured with the following parameters: Minimum percentage of ownership to be considered significant. Owners with ownership percentage at or above this threshold must be included in self-attested data. Total percentage of ownership that must be accounted for in the documentation. The check will fail if the total documented ownership is less than this threshold. Whether to verify that self-attested ownership shares match the documented shares. If true, the check will fail if self-attested ownership data is missing. Whether to enable visual verification of documents. Whether to enable document fraud detection. Whether to include incorporation documents in the ownership verification process. ### Example Configuration ```json theme={null} { "min_ownership_threshold": 25, "total_ownership_threshold": 100, "check_self_attested_ownership": true, "enable_visual_verification": true, "enable_fraud_check": true, "include_incorporation_documents": false } ``` ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.business_ownership_verification_tool", "kyb_schema": { "id": "ownership-check-001", "self_attested_data": { "business_name": "Acme Corp, Inc.", "business_ownership_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/acme_cap_table.pdf", "file_name": "acme_cap_table.pdf", "source_type": "file_url" } ] }, "associated_individuals": [ { "id": "owner-001", "self_attested_data": { "first_name": "John", "last_name": "Smith", "title": "CEO", "is_business_owner": true, "business_ownership_percentage": 60 } }, { "id": "owner-002", "self_attested_data": { "first_name": "Jane", "last_name": "Doe", "title": "CTO", "is_business_owner": true, "business_ownership_percentage": 30 } } ], "associated_entities": [ { "id": "entity-001", "self_attested_data": { "business_name": "Venture Capital LLC", "business_ownership_percentage": 10, "is_trust": false } } ] }, "check_args": { "min_ownership_threshold": 25, "total_ownership_threshold": 100, "check_self_attested_ownership": true, "enable_visual_verification": true, "enable_fraud_check": true, "include_incorporation_documents": false }, "webhook_url": "https://your-webhook.com/check-updates" }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.business_ownership_verification_tool', 'kyb_schema': { 'id': 'ownership-check-001', 'self_attested_data': { 'business_name': 'Acme Corp, Inc.', 'business_ownership_documents': [ { 'url': 'https://storage.googleapis.com/parcha-ai-public-assets/acme_cap_table.pdf', 'file_name': 'acme_cap_table.pdf', 'source_type': 'file_url' } ] }, 'associated_individuals': [ { 'id': 'owner-001', 'self_attested_data': { 'first_name': 'John', 'last_name': 'Smith', 'title': 'CEO', 'is_business_owner': True, 'business_ownership_percentage': 60 } }, { 'id': 'owner-002', 'self_attested_data': { 'first_name': 'Jane', 'last_name': 'Doe', 'title': 'CTO', 'is_business_owner': True, 'business_ownership_percentage': 30 } } ], 'associated_entities': [ { 'id': 'entity-001', 'self_attested_data': { 'business_name': 'Venture Capital LLC', 'business_ownership_percentage': 10, 'is_trust': False } } ] }, 'check_args': { 'min_ownership_threshold': 25, 'total_ownership_threshold': 100, 'check_self_attested_ownership': True, 'enable_visual_verification': True, 'enable_fraud_check': True, 'include_incorporation_documents': False }, 'webhook_url': 'https://your-webhook.com/check-updates' } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.business_ownership_verification_tool', payload: { id: 'ownership-check-001', self_attested_data: { business_name: 'Acme Corp, Inc.', business_ownership_documents: [ { url: 'https://storage.googleapis.com/parcha-ai-public-assets/acme_cap_table.pdf', file_name: 'acme_cap_table.pdf', source_type: 'file_url' } ] }, associated_individuals: [ { id: 'owner-001', self_attested_data: { first_name: 'John', last_name: 'Smith', title: 'CEO', is_business_owner: true, business_ownership_percentage: 60 } }, { id: 'owner-002', self_attested_data: { first_name: 'Jane', last_name: 'Doe', title: 'CTO', is_business_owner: true, business_ownership_percentage: 30 } } ], associated_entities: [ { id: 'entity-001', self_attested_data: { business_name: 'Venture Capital LLC', business_ownership_percentage: 10, is_trust: false } } ] }, check_args: { min_ownership_threshold: 25, total_ownership_threshold: 100, check_self_attested_ownership: true, enable_visual_verification: true, enable_fraud_check: true, include_incorporation_documents: false }, webhook_url: 'https://your-webhook.com/check-updates' }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ### Example Response ```json theme={null} { "id": "check-12345-abcde", "status": "PENDING", "created_at": "2024-03-15T15:30:00Z", "updated_at": "2024-03-15T15:30:00Z", "agent_id": "your-agent-key", "input_payload": { "agent_key": "your-kyb-agent-key", "check_id": "kyb.business_ownership_verification_tool", "payload": { "id": "ownership-check-001", "self_attested_data": { "business_name": "Acme Corp, Inc.", "business_ownership_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/acme_cap_table.pdf", "file_name": "acme_cap_table.pdf", "source_type": "file_url" } ] }, "associated_individuals": [ { "id": "owner-001", "self_attested_data": { "first_name": "John", "last_name": "Smith", "title": "CEO", "is_business_owner": true, "business_ownership_percentage": 60 } }, { "id": "owner-002", "self_attested_data": { "first_name": "Jane", "last_name": "Doe", "title": "CTO", "is_business_owner": true, "business_ownership_percentage": 30 } } ], "associated_entities": [ { "id": "entity-001", "self_attested_data": { "business_name": "Venture Capital LLC", "business_ownership_percentage": 10, "is_trust": false } } ] }, "check_args": { "min_ownership_threshold": 25, "total_ownership_threshold": 100, "check_self_attested_ownership": true, "enable_visual_verification": true, "enable_fraud_check": true, "include_incorporation_documents": false }, "webhook_url": "https://your-webhook.com/check-updates" } } ``` ## Check Results The check returns a detailed analysis of the business ownership documents and verification results. For full details of the response structure, see the [Business Ownership Document Verification Result](/api-reference/check-results/business-ownership-document-verification) documentation. # Business Registration Check Source: https://docs.parcha.ai/checks/business-registration-check Verify business registration and legal status through OpenCorporates The Business Registration check validates a business's legal registration status by searching global corporate registries through OpenCorporates. This check confirms the business exists as a registered legal entity and provides key registration details. ## Overview The check examines: * Business registration in official corporate registries * Legal entity status and type * Registration number and jurisdiction * Incorporation date and current status * Company officers and directors (when available) ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.open_corporates_business_check"` for business registration verification. The business information for verification. A unique identifier for this check case. The legal name of the business to verify. The official registered name if different from business name. The company registration or incorporation number. The country code where the business is registered (ISO 3166-1 alpha-2). The state or region of incorporation. The date of incorporation (YYYY-MM-DD format). ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.open_corporates_business_check", "payload": { "id": "registration-check-001", "self_attested_data": { "business_name": "Acme Corporation", "registered_business_name": "ACME CORPORATION INC", "business_registration_number": "C1234567", "address_of_incorporation": { "country_code": "US", "state": "DE" }, "incorporation_date": "2020-01-15" } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.open_corporates_business_check', 'payload': { 'id': 'registration-check-001', 'self_attested_data': { 'business_name': 'Acme Corporation', 'registered_business_name': 'ACME CORPORATION INC', 'business_registration_number': 'C1234567', 'address_of_incorporation': { 'country_code': 'US', 'state': 'DE' }, 'incorporation_date': '2020-01-15' } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.open_corporates_business_check', payload: { id: 'registration-check-001', self_attested_data: { business_name: 'Acme Corporation', registered_business_name: 'ACME CORPORATION INC', business_registration_number: 'C1234567', address_of_incorporation: { country_code: 'US', state: 'DE' }, incorporation_date: '2020-01-15' } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The business registration check follows these steps: 1. **Registry Search** * Searches OpenCorporates database by business name * Filters by jurisdiction if provided * Matches against registration number if provided 2. **Entity Verification** * Confirms business exists as registered entity * Validates registration details match self-attested data * Extracts current status (active, dissolved, etc.) 3. **Data Extraction** * Retrieves incorporation date * Extracts registration/company number * Identifies business type and jurisdiction * Collects officer information (when available) 4. **Validation** * Cross-references self-attested data with registry data * Flags discrepancies in key details * Confirms business is in good standing ## Check Results ### Response Structure ```typescript theme={null} { type: "BusinessRegistrationCheckResult"; passed: boolean; company_found: boolean; registry_data?: { company_name: string; registration_number: string; jurisdiction: string; incorporation_date: string; company_type: string; status: "active" | "dissolved" | "suspended" | "unknown"; registered_address?: string; officers?: Array<{ name: string; position: string; start_date?: string; }>; opencorporates_url: string; }; verification?: { name_match: boolean; registration_number_match?: boolean; incorporation_date_match?: boolean; }; discrepancies?: Array; } type Discrepancy = { field: string; self_attested: string; registry_value: string; severity: "low" | "medium" | "high"; } ``` ### Example Results ```json Low Risk - Verified Registration theme={null} { "type": "BusinessRegistrationCheckResult", "passed": true, "company_found": true, "registry_data": { "company_name": "ACME CORPORATION INC", "registration_number": "C1234567", "jurisdiction": "Delaware, US", "incorporation_date": "2020-01-15", "company_type": "Corporation", "status": "active", "registered_address": "123 Corporate Blvd, Wilmington, DE 19801", "officers": [ { "name": "Jane Smith", "position": "Director", "start_date": "2020-01-15" } ], "opencorporates_url": "https://opencorporates.com/companies/us_de/C1234567" }, "verification": { "name_match": true, "registration_number_match": true, "incorporation_date_match": true }, "discrepancies": [] } ``` ```json Medium Risk - Minor Discrepancies theme={null} { "type": "BusinessRegistrationCheckResult", "passed": true, "company_found": true, "registry_data": { "company_name": "ACME CORPORATION INC", "registration_number": "C1234567", "jurisdiction": "Delaware, US", "incorporation_date": "2020-02-01", "company_type": "Corporation", "status": "active", "opencorporates_url": "https://opencorporates.com/companies/us_de/C1234567" }, "verification": { "name_match": true, "registration_number_match": true, "incorporation_date_match": false }, "discrepancies": [ { "field": "incorporation_date", "self_attested": "2020-01-15", "registry_value": "2020-02-01", "severity": "medium" } ] } ``` ```json High Risk - Not Found or Dissolved theme={null} { "type": "BusinessRegistrationCheckResult", "passed": false, "company_found": true, "registry_data": { "company_name": "ACME CORPORATION INC", "registration_number": "C1234567", "jurisdiction": "Delaware, US", "incorporation_date": "2020-01-15", "company_type": "Corporation", "status": "dissolved", "opencorporates_url": "https://opencorporates.com/companies/us_de/C1234567" }, "verification": { "name_match": true, "registration_number_match": true, "incorporation_date_match": true }, "discrepancies": [ { "field": "status", "self_attested": "active", "registry_value": "dissolved", "severity": "high" } ] } ``` ## Risk Factors The check may flag concerns if: * Business cannot be found in any corporate registry * Business is dissolved, suspended, or not in good standing * Significant discrepancies in registration details * Registration number doesn't match * Incorporation date differs significantly * Business name doesn't match registered name * Recently incorporated (\< 6 months) in high-risk jurisdictions ## Data Sources This check utilizes: * **OpenCorporates**: Global database of company information * Official government corporate registries from 130+ jurisdictions * Regularly updated company status and officer information ## Best Practices 1. **Provide Complete Data**: Include registration number and jurisdiction for faster matching 2. **Allow Name Variations**: Account for different business name formats (LLC, Inc, Ltd, etc.) 3. **Check Status Regularly**: Corporate status can change over time 4. **Verify Officers**: Cross-check officers with ownership documents 5. **Consider Jurisdiction**: Some registries provide more detailed information than others ## Related Checks * [Incorporation Document Verification](/checks/incorporation-document-verification) - Verify incorporation documents * [Basic Business Profile Check](/checks/basic-business-profile-check) - Verify business profile * [Business Owners Research](/checks/business-owners-check) - Research ownership structure * [Address Verification](/checks/addresses-check) - Verify business addresses # Business Reviews Check Source: https://docs.parcha.ai/checks/business-reviews-check Analyze customer reviews and business reputation across online platforms The Business Reviews Check evaluates a business's reputation by analyzing customer reviews, ratings, and feedback across various online platforms. This check helps assess business credibility, customer satisfaction, and potential red flags in customer experiences. ## Request ### Parameters The name of the business to analyze List of business addresses to help identify correct review profiles List of business websites to help identify correct review profiles The officially registered name of the business ## Response The type of the check result - "BusinessReviewCheckResult" Whether the check passed or failed The verified name of the business The operational status of the business (e.g., "ACTIVE", "CLOSED") A summary of the business based on review data The average review score across all platforms The total number of reviews analyzed List of high-risk issues mentioned in reviews The type of risk identified Description of the risk mention Source of the risk mention List of potentially suspicious reviews The text content of the suspicious review Reason why the review was flagged as suspicious Date when the review was posted ### Example Response ```json theme={null} { "type": "BusinessReviewCheckResult", "passed": true, "business_name": "Parcha Labs, Inc.", "business_status": "ACTIVE", "business_summary": "Technology company with strong customer satisfaction and professional service delivery", "avg_score": 4.8, "num_reviews": 156, "high_risk_mentions": [ { "risk_type": "SERVICE_DISRUPTION", "description": "Temporary platform outage reported", "source": "Trustpilot" } ], "suspectful_reviews": [ { "review_text": "Best service ever! Highly recommended to everyone!", "suspect_reason": "Generic positive review with no specific details", "review_date": "2024-01-15" } ] } ``` ## Key Components ### Review Analysis * Aggregates reviews from multiple platforms * Calculates average ratings and trends * Identifies common themes in feedback ### Risk Assessment * Detects suspicious review patterns * Flags potential reputation risks * Analyzes negative feedback patterns ### Verification Process * Confirms business review profiles * Validates review authenticity * Cross-references business information # EIN Document Verification Source: https://docs.parcha.ai/checks/ein-document-verification Learn how to run EIN document verification checks to validate business tax identification information The EIN Document Verification check helps verify the authenticity of Employer Identification Number (EIN) documents and validates the business tax identification information. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Check ID `kyb.ein_document_verification` ## Overview The check analyzes various aspects of EIN documents: * Document authenticity and validity * IRS document type verification * EIN number validation * Business name and address verification * Document fraud detection ## How the Check Works 1. **Document Analysis** * Extracts key information from EIN documents * Validates document structure and format * Verifies document authenticity * Identifies EIN, business name, and address 2. **Information Verification** * Cross-references extracted data with self-attested information * Validates business name matches * Confirms EIN number * Verifies business address 3. **Visual Verification** * Validates IRS logo presence and authenticity * Verifies form layout matches official IRS documents * Checks document type (CP-575, CP-575A, 147C, etc.) * Ensures document is authentic and unaltered ### Document Requirements The following information must be present in the EIN documents for it to be considered valid: #### Valid IRS Documents * Must be one of the following document types: * CP-575 Notice * CP-575A Notice * 147C Letter * IRS EIN Confirmation Letter #### Required Information * Employer Identification Number (EIN) in XX-XXXXXXX format * Business Name * Business Address * Document/Statement Date * IRS Logo and Official Layout * Document must be from the IRS #### Document Authenticity * Must contain valid IRS logo * Must match official IRS form layout * Must be a genuine IRS document (not altered or fake) * Must be properly formatted and structured ## Check Configuration The check can be configured with the following parameters: Whether to enable visual verification of documents. Whether to enable document fraud detection. ### Example Configuration ```json theme={null} { "enable_visual_verification": true, "enable_fraud_check": true } ``` ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.ein_document_verification", "kyb_schema": { "id": "ein-check-001", "self_attested_data": { "business_name": "Parcha Labs Incorporated", "tin_number": "92-3265708", "ein_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/CP575Notice_Parcha.pdf", "file_name": "Parcha_EIN.pdf", "source_type": "file_url" } ] } }, "check_args": { "enable_visual_verification": true, "enable_fraud_check": true }, "webhook_url": "https://your-webhook.com/check-updates" }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.ein_document_verification', 'kyb_schema': { 'id': 'ein-check-001', 'self_attested_data': { 'business_name': 'Parcha Labs Incorporated', 'tin_number': '92-3265708', 'ein_documents': [ { 'url': 'https://storage.googleapis.com/parcha-ai-public-assets/CP575Notice_Parcha.pdf', 'file_name': 'Parcha_EIN.pdf', 'source_type': 'file_url' } ] } }, 'check_args': { 'enable_visual_verification': True, 'enable_fraud_check': True }, 'webhook_url': 'https://your-webhook.com/check-updates' } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.ein_document_verification', payload: { id: 'ein-check-001', self_attested_data: { business_name: 'Parcha Labs Incorporated', tin_number: '92-3265708', ein_documents: [ { url: 'https://storage.googleapis.com/parcha-ai-public-assets/CP575Notice_Parcha.pdf', file_name: 'Parcha_EIN.pdf', source_type: 'file_url' } ] } }, check_args: { enable_visual_verification: true, enable_fraud_check: true }, webhook_url: 'https://your-webhook.com/check-updates' }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ### Example Response ```json theme={null} { "id": "check-12345-abcde", "status": "PENDING", "created_at": "2024-03-15T15:30:00Z", "updated_at": "2024-03-15T15:30:00Z", "agent_id": "your-agent-key", "input_payload": { "agent_key": "your-kyb-agent-key", "check_id": "kyb.ein_document_verification", "payload": { "id": "ein-check-001", "self_attested_data": { "business_name": "Parcha Labs Incorporated", "tin_number": "92-3265708", "ein_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/CP575Notice_Parcha.pdf", "file_name": "Parcha_EIN.pdf", "source_type": "file_url" } ] } }, "check_args": { "enable_visual_verification": true, "enable_fraud_check": true }, "webhook_url": "https://your-webhook.com/check-updates" } } ``` ## Check Results The check returns a detailed analysis of the EIN documents and verification results. For full details of the response structure, see the [EIN Document Verification Result](/api-reference/check-results/ein-document-verification) documentation. # High Risk Country Check Source: https://docs.parcha.ai/checks/high-risk-country-check Verify that a business and its customers do not operate in prohibited or high risk countries The High Risk Country Check analyzes a business's operational locations and customer base to identify potential geographic risks. This check helps ensure compliance with international regulations and sanctions by verifying the countries where a business operates and serves customers. ## Request ### Parameters The name of the business to verify The primary country where the business operates List of countries where the business serves customers ## Response The type of the check result - "HighRiskCountryCheckResult" Whether the check passed or failed The verified primary country of operation List of verified countries where the business serves customers ### Example Response ```json theme={null} { "type": "HighRiskCountryCheckResult", "passed": true, "verified_country": "US", "verified_customer_countries": ["US", "CA", "GB", "DE", "FR"] } ``` ## Key Components ### Geographic Risk Analysis * Evaluates business operation locations * Assesses customer base distribution * Analyzes cross-border activities ### Risk Categories #### Prohibited Countries * Countries under comprehensive sanctions * Non-cooperative jurisdictions * State sponsors of terrorism * Restricted markets #### High Risk Countries * Countries with partial sanctions * Jurisdictions with weak AML controls * Regions with political instability * Areas with high financial crime rates #### Standard Risk Countries * FATF member countries * Established financial markets * Strong regulatory frameworks * Stable political environments ### Verification Process 1. Analysis of business registration 2. Review of operational presence 3. Verification of customer locations 4. Assessment of regulatory compliance 5. Evaluation of geographic exposure # High Risk Industry Check Source: https://docs.parcha.ai/checks/high-risk-industry-check Learn how to run high risk industry checks to verify a business's industry classification The High Risk Industry check helps identify potential risks by verifying a business's industry classification and ensuring it does not operate in prohibited or high-risk industries. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Overview The check analyzes various aspects of a business's industry: * Primary business activities * Industry classification * Prohibited industry screening * High-risk sector evaluation * Business model assessment ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.high_risk_industry_check"` for industry risk verification. The business information for verification. A unique identifier for this check case. The legal name of the business to verify. The self-attested industry of the business. Description of the business's activities and operations. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.high_risk_industry_check", "payload": { "id": "industry-check-001", "self_attested_data": { "business_name": "Parcha Labs Inc", "industry": "Financial Technology Services", "business_activity": "Development and provision of business verification and compliance software solutions" } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.high_risk_industry_check', 'payload': { 'id': 'industry-check-001', 'self_attested_data': { 'business_name': 'Parcha Labs Inc', 'industry': 'Financial Technology Services', 'business_activity': 'Development and provision of business verification and compliance software solutions' } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const api_key = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.high_risk_industry_check', payload: { id: 'industry-check-001', self_attested_data: { business_name: 'Parcha Labs Inc', industry: 'Financial Technology Services', business_activity: 'Development and provision of business verification and compliance software solutions' } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${api_key}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The high risk industry check follows these steps: 1. **Industry Analysis** * Evaluates primary business activities * Analyzes business model and operations * Reviews product and service offerings 2. **Risk Classification** * Screens against prohibited industries * Identifies high-risk sectors * Assesses regulatory requirements 3. **Verification Process** * Reviews business documentation * Analyzes online presence * Verifies against NAICS standards * Cross-references industry databases ## Check Results Once the check is complete, you can retrieve the results using the check ID. The results will include: ### Response Structure ```typescript theme={null} { type: "IndustryActivityCheckResult"; passed: boolean; verified_industry: string | null; verified_business_activity: string | null; } ``` # Incorporation Document Verification Source: https://docs.parcha.ai/checks/incorporation-document-verification Learn how to run incorporation document verification checks to validate business incorporation information The Incorporation Document Verification check helps verify the authenticity of business incorporation documents and validates key incorporation information. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Check ID `kyb.incorporation_document_verification` ## Overview The check analyzes various aspects of incorporation documents: * Document authenticity and validity * Business name verification * Incorporation date confirmation * Registered address validation * Business activity verification * Jurisdiction confirmation * Registration number validation ## How the Check Works 1. **Document Analysis** * Extracts key information from incorporation documents * Validates document structure and format * Verifies official seals and signatures * Checks document authenticity 2. **Information Verification** * Cross-references extracted data with self-attested information * Validates business registration details * Confirms incorporation jurisdiction * Verifies registered address 3. **Fraud Detection** * Analyzes for document tampering * Checks for inconsistencies * Validates document authenticity * Reviews visual elements ### Document Requirements The following information must be present in the incorporation documents for it to be considered valid: #### Required Information * Business Name * Incorporation Date * Business Address * Jurisdiction of Incorporation * Business filing number or registration number #### Document Types Must be one of the following document types: * Articles of Incorporation * Certificate of Formation * Certificate of Organization * Business Registration Certificate * Company Registration Document #### Document Authenticity * Must contain official seals/stamps where applicable * Must match official government document layout * Must be from the appropriate government authority * Must be properly formatted and structured * Must not show signs of tampering or alteration #### Document Content The document must clearly show: * Complete legal business name * Date of incorporation/formation * Registered business address * Registration/filing number * Jurisdiction where business is registered * Business purpose or activities (if required by jurisdiction) * Any required government seals or certifications ## Check Configuration The check can be configured with the following parameters: ### Check Arguments Whether to strictly verify the incorporation date. If true: * Must be present in both self-attested data and documented information * If missing in self-attested data, verification fails * If dates differ by more than validity\_period\_days, verification fails Number of days allowed for difference between self-attested and documented incorporation dates. Only used if verify\_incorporation\_date is true. Whether to strictly verify the business registration number. If true: * Must be present in both self-attested data and documented information * If missing in self-attested data, verification fails * Numbers must match exactly or be part of a compound number Whether to strictly verify the business address. If true: * Must be present in both self-attested data and documented information * If missing in self-attested data, verification fails * Address components must match with only minor formatting differences allowed Whether to fail verification if high-risk fraud is detected. If true: * Verification fails if fraud\_verification\_data shows "HIGH\_RISK" * Non-high-risk fraud issues are flagged but don't fail verification Whether to fail verification if visual verification fails. If true: * Verification fails if visual\_verification\_data shows verification\_passed as false ### Data Processing Configuration Whether to enable visual verification of documents. Whether to enable document fraud detection. ### Example Configuration ```json theme={null} { "verify_incorporation_date": true, "validity_period_days": 3, "verify_registration_number": true, "verify_address": true, "verify_no_high_risk_fraud": true, "verify_visual_verification_passed": true, "enable_visual_verification": true, "enable_fraud_check": true, } ``` ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.incorporation_document_verification"` for incorporation document verification. The business information and documents for verification. A unique identifier for this check case. The legal name of the business to verify. The date when the business was incorporated (YYYY-MM-DD). Primary street address. Secondary street address (optional). City name. State or region. Postal or ZIP code. Two-letter country code (ISO 3166-1 alpha-2). The jurisdiction where the business is incorporated. The business registration number. Array of document objects containing incorporation documents. URL of the document file. Type of the document (e.g., "certificate\_of\_incorporation"). Optional description of the document. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.incorporation_document_verification", "payload": { "id": "inc-doc-check-001", "self_attested_data": { "registered_business_name": "Acme Corp, Inc.", "incorporation_date": "2023-03-29", "address_of_incorporation": { "street_1": "251 Little Falls Drive", "city": "Wilmington", "state": "Delaware", "postal_code": "19808", "country_code": "US" }, "incorporation_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/acme_incorporation_doc.pdf", "type": "Document", "file_name": "acme_incorporation_doc.pdf", "source_type": "gcs" } ] } }, "check_args": { "verify_incorporation_date": true, "verify_registration_number": true, "verify_address": true, "verify_no_high_risk_fraud": true, "verify_visual_verification_passed": true, "enable_visual_verification": true, "enable_fraud_check": true, }, "webhook_url": "https://your-webhook.com/check-updates" }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.incorporation_document_verification', 'payload': { 'id': 'inc-doc-check-001', 'self_attested_data': { 'registered_business_name': 'Acme Corp, Inc.', 'incorporation_date': '2023-03-29', 'address_of_incorporation': { 'street_1': '251 Little Falls Drive', 'city': 'Wilmington', 'state': 'Delaware', 'postal_code': '19808', 'country_code': 'US' }, 'incorporation_documents': [ { 'url': 'https://storage.googleapis.com/parcha-ai-public-assets/acme_incorporation_doc.pdf', 'type': 'Document', 'file_name': 'acme_incorporation_doc.pdf', 'source_type': 'gcs' } ] } }, 'check_args': { 'verify_incorporation_date': True, 'verify_registration_number': True, 'verify_address': True, 'verify_no_high_risk_fraud': True, 'verify_visual_verification_passed': True, 'enable_visual_verification': True, 'enable_fraud_check': True, }, 'webhook_url': 'https://your-webhook.com/check-updates' } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.incorporation_document_verification', payload: { id: 'inc-doc-check-001', self_attested_data: { registered_business_name: 'Acme Corp, Inc.', incorporation_date: '2023-03-29', address_of_incorporation: { street_1: '251 Little Falls Drive', city: 'Wilmington', state: 'Delaware', postal_code: '19808', country_code: 'US' }, incorporation_documents: [ { url: 'https://storage.googleapis.com/parcha-ai-public-assets/acme_incorporation_doc.pdf', type: 'Document', file_name: 'acme_incorporation_doc.pdf', source_type: 'gcs' } ] } }, check_args: { verify_incorporation_date: true, verify_registration_number: true, verify_address: true, verify_no_high_risk_fraud: true, verify_visual_verification_passed: true, enable_visual_verification: true, enable_fraud_check: true, }, webhook_url: 'https://your-webhook.com/check-updates' }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ### Example Response ```json theme={null} { "id": "check-12345-abcde", "status": "PENDING", "created_at": "2024-03-15T15:30:00Z", "updated_at": "2024-03-15T15:30:00Z", "agent_id": "your-agent-key", "input_payload": { "agent_key": "your-kyb-agent-key", "check_id": "kyb.incorporation_document_verification", "payload": { "id": "inc-doc-check-001", "self_attested_data": { "registered_business_name": "Acme Corp, Inc.", "incorporation_date": "2023-03-29", "address_of_incorporation": { "street_1": "251 Little Falls Drive", "city": "Wilmington", "state": "Delaware", "postal_code": "19808", "country_code": "US" }, "incorporation_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/acme_incorporation_doc.pdf", "type": "Document", "file_name": "acme_incorporation_doc.pdf", "source_type": "gcs" } ] } }, "check_args": { "verify_incorporation_date": true, "verify_registration_number": true, "verify_address": true, "verify_no_high_risk_fraud": true, "verify_visual_verification_passed": true, "enable_visual_verification": true, "enable_fraud_check": true, }, "webhook_url": "https://your-webhook.com/check-updates" } } ``` ## Check Results For full details of the response structure, see the [Incorporation Document Verification Result](/api-reference/check-results/incorporation-document-verification) documentation. # Industry Activity Check Source: https://docs.parcha.ai/checks/industry-activity-check Verify business activity patterns and industry-specific compliance ## Overview The Industry Activity Check analyzes a business's operational patterns, industry-specific activities, and compliance with sector regulations. This check helps identify businesses that may be operating outside their stated industry or engaging in unusual activity patterns. ## What It Checks This check examines: * **Industry Classification**: Verifies the business operates within its stated industry * **Activity Patterns**: Analyzes typical business activities and transaction patterns * **Sector Compliance**: Checks for industry-specific regulatory compliance * **Business Operations**: Reviews operational indicators and business model consistency * **Market Presence**: Evaluates the business's presence and reputation within its industry ## Key Indicators ### Industry Alignment * Match between stated industry and actual operations * Consistency with typical industry business models * Presence in relevant industry directories and associations ### Activity Verification * Transaction patterns consistent with industry norms * Operational indicators match business type * Seasonal or cyclical patterns align with industry expectations ### Compliance Signals * Required licenses and permits for the industry * Adherence to industry-specific regulations * Membership in relevant trade organizations ## Risk Factors The check may flag concerns if: * Business operations don't match stated industry * Activity patterns are inconsistent with industry norms * Missing required industry-specific licenses or permits * No verifiable presence in industry networks or directories * Operations span multiple unrelated industries without explanation ## Data Sources This check may utilize: * Industry classification databases (NAICS, SIC codes) * Trade association memberships * Industry-specific regulatory databases * Business registration and licensing records * Market research and industry reports ## Use Cases Common applications include: * **Risk Assessment**: Identify businesses operating outside their stated purpose * **Compliance Verification**: Ensure industry-specific regulatory compliance * **Fraud Prevention**: Detect businesses misrepresenting their industry * **Due Diligence**: Verify legitimate business operations in stated sector * **Onboarding**: Screen new businesses for industry alignment ## Example Results ```json Low Risk theme={null} { "check_id": "industry_activity_check", "status": "completed", "risk_level": "low", "result": { "industry_alignment": "verified", "primary_industry": "Software Development", "naics_code": "541511", "activity_consistency": "high", "industry_indicators": [ { "indicator": "Software company registration", "status": "verified" }, { "indicator": "Tech industry association membership", "status": "verified" }, { "indicator": "Typical SaaS business model", "status": "confirmed" } ], "compliance_status": "compliant", "confidence_score": 95 } } ``` ```json Medium Risk theme={null} { "check_id": "industry_activity_check", "status": "completed", "risk_level": "medium", "result": { "industry_alignment": "partial", "primary_industry": "General Retail", "stated_industry": "Electronics Retail", "naics_code": "453998", "activity_consistency": "moderate", "concerns": [ { "type": "industry_mismatch", "description": "Business activities span multiple unrelated retail categories", "severity": "medium" }, { "type": "missing_verification", "description": "No trade association membership found", "severity": "low" } ], "compliance_status": "needs_review", "confidence_score": 65 } } ``` ```json High Risk theme={null} { "check_id": "industry_activity_check", "status": "completed", "risk_level": "high", "result": { "industry_alignment": "misaligned", "stated_industry": "Consulting Services", "detected_activities": ["Money services", "High-volume transactions"], "naics_code": "541618", "activity_consistency": "low", "concerns": [ { "type": "industry_mismatch", "description": "Operations inconsistent with stated consulting business", "severity": "high" }, { "type": "missing_licenses", "description": "No money services business license found", "severity": "high" }, { "type": "unusual_activity", "description": "Transaction patterns not typical for consulting", "severity": "high" } ], "compliance_status": "non_compliant", "confidence_score": 85 } } ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Best Practices When using this check: 1. **Combine with Other Checks**: Use alongside business profile and web presence checks for comprehensive verification 2. **Industry Context**: Consider industry-specific norms and variations 3. **Review Flags**: Investigate any industry misalignment or activity concerns 4. **Regular Updates**: Re-run periodically as business activities may evolve 5. **Documentation**: Maintain records of industry verification for compliance purposes ## Configuration This check can be configured with: * **Industry Focus**: Specify industries requiring additional scrutiny * **Compliance Requirements**: Define industry-specific compliance checks * **Risk Thresholds**: Customize risk scoring based on your requirements * **Data Sources**: Select preferred industry verification databases ## Related Checks * [Basic Business Profile Check](/checks/basic-business-profile-check) - Verify core business information * [High Risk Industry Check](/api-reference/check-results/high-risk-industry-check) - Screen for high-risk sectors * [Web Presence Check](/checks/web-presence-check) - Verify online business presence * [Business Reviews Check](/checks/business-reviews-check) - Analyze customer feedback and reputation # Adverse Media Screening (Individual) Source: https://docs.parcha.ai/checks/kyc-adverse-media-screening Screen individuals for negative news and media coverage The Individual Adverse Media Screening check searches for negative news articles, media coverage, and online content associated with an individual. This check helps identify reputational risks, criminal activities, and other adverse information. ## Overview The check examines: * Criminal convictions and charges * Fraud and financial crimes * Regulatory enforcement actions * Civil litigation * Corruption and bribery allegations * Money laundering connections * Terrorist financing links * Human rights violations ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYCAgentJob ``` **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. ### Request Parameters Your KYC agent key from the Parcha dashboard. This is unique to your organization and agent configuration. The individual information for screening using the [KYC Schema](/schemas/individual-schema). A unique identifier for this KYC case. Individual's first name. Individual's last name. Individual's middle name. Date of birth (YYYY-MM-DD format) for better matching. Country of residence (ISO 3166-1 alpha-2). Address information for context. Optional. To run only this specific check, include `["kyc.adverse_media_screening_check_v2"]`. If omitted, all checks configured in your agent will run. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYCAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyc-agent-key", "kyc_schema": { "id": "adverse-media-check-001", "self_attested_data": { "first_name": "John", "last_name": "Smith", "middle_name": "David", "date_of_birth": "1975-08-20", "country_of_residence": "US", "address": { "city": "Miami", "state": "FL", "country_code": "US" } } }, "check_ids": ["kyc.adverse_media_screening_check_v2"] }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYCAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyc-agent-key', # Replace with your actual agent key 'kyc_schema': { 'id': 'adverse-media-check-001', 'self_attested_data': { 'first_name': 'John', 'last_name': 'Smith', 'middle_name': 'David', 'date_of_birth': '1975-08-20', 'country_of_residence': 'US', 'address': { 'city': 'Miami', 'state': 'FL', 'country_code': 'US' } } }, 'check_ids': ['kyc.adverse_media_screening_check_v2'] # Optional: run only this check } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYCAgentJob'; const data = { agent_key: 'your-kyc-agent-key', // Replace with your actual agent key kyc_schema: { id: 'adverse-media-check-001', self_attested_data: { first_name: 'John', last_name: 'Smith', middle_name: 'David', date_of_birth: '1975-08-20', country_of_residence: 'US', address: { city: 'Miami', state: 'FL', country_code: 'US' } } }, check_ids: ['kyc.adverse_media_screening_check_v2'] // Optional: run only this check }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The adverse media screening check follows these steps: 1. **Media Search** * Searches news databases and archives * Queries legal and court records * Searches regulatory enforcement databases * Scans social media and online forums 2. **Content Analysis** * Identifies articles mentioning the individual * Analyzes context and severity * Categorizes adverse events * Filters out irrelevant or positive mentions 3. **Identity Verification** * Confirms the article refers to the screened individual * Cross-references location and dates * Evaluates name uniqueness * Reduces false positives 4. **Risk Assessment** * Categorizes findings by severity * Determines match confidence * Evaluates recency and relevance * Provides risk rating ## Check Results ### Response Structure ```typescript theme={null} { type: "AdverseMediaScreeningCheckResult"; passed: boolean; articles: Array; total_articles: number; summary: { high_severity_count: number; medium_severity_count: number; low_severity_count: number; categories: Array; }; screening_date: string; } type AdverseMediaArticle = { title: string; url?: string; publication_date: string; source: string; excerpt: string; match_rating: "strong_match" | "partial_match" | "weak_match" | "false_positive"; match_score: number; category: string; severity: "high" | "medium" | "low"; topics: Array; locations?: Array; individuals_mentioned?: Array; } ``` ### Adverse Media Categories * **Financial Crime**: Fraud, embezzlement, money laundering, tax evasion * **Violent Crime**: Assault, murder, terrorism * **Corruption**: Bribery, kickbacks, conflicts of interest * **Regulatory Action**: SEC enforcement, banking violations, licensing actions * **Civil Litigation**: Lawsuits, class actions, settlements * **Sanctions/Watchlists**: Sanctions violations, watchlist additions * **Cybercrime**: Hacking, data breaches, identity theft * **Human Rights**: Forced labor, human trafficking, rights violations * **Drug Trafficking**: Drug-related offenses and trafficking * **Organized Crime**: Gang activity, racketeering, organized criminal enterprises ### Example Results ```json Low Risk - No Adverse Media theme={null} { "type": "AdverseMediaScreeningCheckResult", "passed": true, "articles": [], "total_articles": 0, "summary": { "high_severity_count": 0, "medium_severity_count": 0, "low_severity_count": 0, "categories": [] }, "screening_date": "2024-02-15T10:30:00Z" } ``` ```json Medium Risk - Old Minor Offense theme={null} { "type": "AdverseMediaScreeningCheckResult", "passed": true, "articles": [ { "title": "Local Man Charged with DUI", "url": "https://example-news.com/article-123", "publication_date": "2015-06-12", "source": "Miami Herald", "excerpt": "John David Smith, 40, of Miami, was arrested last night on suspicion of driving under the influence...", "match_rating": "partial_match", "match_score": 78, "category": "Criminal Activity", "severity": "low", "topics": ["DUI", "Traffic Offense"], "locations": ["Miami, FL"], "individuals_mentioned": ["John David Smith"] } ], "total_articles": 1, "summary": { "high_severity_count": 0, "medium_severity_count": 0, "low_severity_count": 1, "categories": ["Criminal Activity"] }, "screening_date": "2024-02-15T10:30:00Z" } ``` ```json High Risk - Financial Crime theme={null} { "type": "AdverseMediaScreeningCheckResult", "passed": false, "articles": [ { "title": "Former Bank Executive Convicted of Fraud", "url": "https://example-news.com/article-456", "publication_date": "2023-11-08", "source": "Wall Street Journal", "excerpt": "John David Smith, 48, a former senior executive at Global Bank, was convicted today on 15 counts of wire fraud and money laundering in connection with a $50 million embezzlement scheme...", "match_rating": "strong_match", "match_score": 95, "category": "Financial Crime", "severity": "high", "topics": ["Fraud", "Money Laundering", "Embezzlement"], "locations": ["Miami, FL", "New York, NY"], "individuals_mentioned": ["John David Smith", "Global Bank"] }, { "title": "SEC Charges Smith with Securities Fraud", "url": "https://example-news.com/article-457", "publication_date": "2023-05-22", "source": "Reuters", "excerpt": "The Securities and Exchange Commission today charged John D. Smith with securities fraud for allegedly misleading investors...", "match_rating": "strong_match", "match_score": 92, "category": "Regulatory Action", "severity": "high", "topics": ["Securities Fraud", "SEC Enforcement"], "locations": ["Miami, FL"], "individuals_mentioned": ["John D. Smith"] } ], "total_articles": 2, "summary": { "high_severity_count": 2, "medium_severity_count": 0, "low_severity_count": 0, "categories": ["Financial Crime", "Regulatory Action"] }, "screening_date": "2024-02-15T10:30:00Z" } ``` ## Risk Factors The check may flag concerns if: * Recent financial crime convictions or charges * Money laundering or terrorist financing connections * Regulatory enforcement actions * Repeated patterns of adverse behavior * High-severity crimes (violent crimes, serious fraud) * Association with sanctioned entities or individuals * Involvement in corruption or bribery schemes ## Search Strategies The check can use multiple search strategies: * **OPOINT**: Premium adverse media database * **SERP\_GOOGLE\_NEWS**: Google News search * **SERP\_GOOGLE\_SEARCH**: General web search * **LEGAL\_DATABASES**: Court records and legal filings * **REGULATORY\_DATABASES**: SEC, FINRA, other regulatory sources ## Best Practices 1. **Use Complete Names**: Include middle name for better matching 2. **Provide Location**: Helps filter false positives 3. **Set Age Cutoff**: Focus on recent news (typically 2-5 years) 4. **Review Match Quality**: Verify articles refer to the correct person 5. **Consider Context**: Not all adverse media is disqualifying 6. **Combine Checks**: Use with sanctions and PEP screening 7. **Update Regularly**: Rescreen periodically as new articles appear ## Configuration Options * **article\_limit**: Maximum articles to analyze (default: 250) * **search\_strategies**: Select search methods * **age\_cutoff**: Years of historical data to search (default: 2) * **vendor**: Choose screening vendor * **filter\_non\_perpetrators**: Exclude articles where person is victim * **adverse\_media\_topic\_filter**: Filter by specific topics * **match\_addresses**: Cross-check addresses to improve accuracy * **include\_civil\_cases**: Include civil litigation ## Related Checks * [PEP Screening (Individual)](/checks/kyc-pep-screening-check) - Screen for PEP status * [Sanctions Screening (Individual)](/checks/kyc-sanctions-screening-check) - Screen sanctions lists * [Person Web Presence Check](/checks/kyc-person-web-presence-check) - Research online presence * [Adverse Media Screening (Business)](/checks/adverse-media-screening) - Screen associated businesses # PEP Screening Check (Individual) Source: https://docs.parcha.ai/checks/kyc-pep-screening-check Screen individuals for Politically Exposed Person (PEP) status The PEP Screening check identifies whether an individual is a Politically Exposed Person (PEP) or is associated with PEPs. PEPs are individuals who hold or have held prominent public positions and may present higher risk for corruption or bribery. ## Overview The check examines: * Current and former government officials * Senior political party members * High-ranking military officers * Senior executives of state-owned enterprises * Important judicial or regulatory figures * Close associates and family members of PEPs (RCAs) ## What is a PEP? According to FATF recommendations, a Politically Exposed Person is an individual who is or has been entrusted with a prominent public function. This includes: * **Domestic PEPs**: Prominent public functions in your own country * **Foreign PEPs**: Prominent public functions in a foreign country * **International Organization PEPs**: Senior positions in international organizations * **Relatives and Close Associates (RCAs)**: Family members or known close associates of PEPs ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYCAgentJob ``` **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. ### Request Parameters Your KYC agent key from the Parcha dashboard. This is unique to your organization and agent configuration. The individual information for screening using the [KYC Schema](/schemas/individual-schema). A unique identifier for this KYC case. Individual's first name. Individual's last name. Individual's middle name. Date of birth (YYYY-MM-DD format). Country of nationality (ISO 3166-1 alpha-2). Country of residence (ISO 3166-1 alpha-2). Residential address information. Optional. To run only this specific check, include `["kyc.pep_screening_check_v2"]`. If omitted, all checks configured in your agent will run. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYCAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyc-agent-key", "kyc_schema": { "id": "pep-check-001", "self_attested_data": { "first_name": "John", "last_name": "Smith", "middle_name": "Robert", "date_of_birth": "1975-06-15", "country_of_nationality": "US", "country_of_residence": "US", "address": { "city": "Washington", "state": "DC", "country_code": "US" } } }, "check_ids": ["kyc.pep_screening_check_v2"] }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYCAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyc-agent-key', # Replace with your actual agent key 'kyc_schema': { 'id': 'pep-check-001', 'self_attested_data': { 'first_name': 'John', 'last_name': 'Smith', 'middle_name': 'Robert', 'date_of_birth': '1975-06-15', 'country_of_nationality': 'US', 'country_of_residence': 'US', 'address': { 'city': 'Washington', 'state': 'DC', 'country_code': 'US' } } }, 'check_ids': ['kyc.pep_screening_check_v2'] # Optional: run only this check } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYCAgentJob'; const data = { agent_key: 'your-kyc-agent-key', // Replace with your actual agent key kyc_schema: { id: 'pep-check-001', self_attested_data: { first_name: 'John', last_name: 'Smith', middle_name: 'Robert', date_of_birth: '1975-06-15', country_of_nationality: 'US', country_of_residence: 'US', address: { city: 'Washington', state: 'DC', country_code: 'US' } } }, check_ids: ['kyc.pep_screening_check_v2'] // Optional: run only this check }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The PEP screening check follows these steps: 1. **Database Search** * Searches PEP databases from multiple vendors * Queries government watchlists * Checks historical PEP records * Includes RCA (Relatives and Close Associates) matching 2. **Match Analysis** * Evaluates name similarity * Compares date of birth (if available) * Analyzes location data * Reviews position and role information 3. **Classification** * Identifies PEP type (domestic, foreign, international org) * Determines current vs. former PEP status * Identifies RCA relationships * Assesses PEP tier (senior, mid-level, etc.) 4. **Risk Assessment** * Evaluates match confidence (strong, partial, weak) * Determines required action (deny, review, approve) * Considers jurisdiction risk * Factors in position sensitivity ## Check Results ### Response Structure ```typescript theme={null} { type: "PEPScreeningCheckResult"; passed: boolean; matches: Array; total_matches: number; screening_date: string; } type PEPMatch = { name: string; match_rating: "strong_match" | "partial_match" | "weak_match" | "false_positive"; match_score: number; pep_type: "domestic_pep" | "foreign_pep" | "international_org_pep" | "rca"; pep_status: "current" | "former"; position: string; date_of_birth?: string; country: string; organization?: string; start_date?: string; end_date?: string; pep_tier?: string; relationship_type?: string; related_pep?: string; source: string; last_updated?: string; } ``` ### Example Results ```json Low Risk - No PEP Matches theme={null} { "type": "PEPScreeningCheckResult", "passed": true, "matches": [], "total_matches": 0, "screening_date": "2024-02-15T10:30:00Z" } ``` ```json Medium Risk - Former PEP theme={null} { "type": "PEPScreeningCheckResult", "passed": true, "matches": [ { "name": "John Robert Smith", "match_rating": "partial_match", "match_score": 82, "pep_type": "domestic_pep", "pep_status": "former", "position": "State Senator", "date_of_birth": "1975-06-15", "country": "United States", "organization": "US State Legislature", "start_date": "2010-01-01", "end_date": "2018-12-31", "pep_tier": "tier_2", "source": "ComplyAdvantage" } ], "total_matches": 1, "screening_date": "2024-02-15T10:30:00Z" } ``` ```json High Risk - Current Senior PEP theme={null} { "type": "PEPScreeningCheckResult", "passed": false, "matches": [ { "name": "John Robert Smith", "match_rating": "strong_match", "match_score": 95, "pep_type": "foreign_pep", "pep_status": "current", "position": "Minister of Finance", "date_of_birth": "1975-06-15", "country": "United Kingdom", "organization": "UK Government", "start_date": "2022-01-15", "pep_tier": "tier_1", "source": "ComplyAdvantage", "last_updated": "2024-02-01" } ], "total_matches": 1, "screening_date": "2024-02-15T10:30:00Z" } ``` ```json High Risk - RCA (Relative/Close Associate) theme={null} { "type": "PEPScreeningCheckResult", "passed": false, "matches": [ { "name": "John Robert Smith", "match_rating": "strong_match", "match_score": 90, "pep_type": "rca", "pep_status": "current", "position": "Close Associate", "date_of_birth": "1975-06-15", "country": "United States", "relationship_type": "business_associate", "related_pep": "Jane Mary Doe - Secretary of State", "source": "ComplyAdvantage", "last_updated": "2024-01-20" } ], "total_matches": 1, "screening_date": "2024-02-15T10:30:00Z" } ``` ## PEP Categories ### Tier 1 - Senior PEPs (Highest Risk) * Heads of state or government * Senior politicians and government officials * Senior judicial or military officials * Senior executives of state-owned enterprises * Important political party officials ### Tier 2 - Mid-Level PEPs (Medium Risk) * Mid-ranking government officials * State or provincial politicians * Mid-level judicial or military officials * Local government executives ### Tier 3 - Lower-Level PEPs (Lower Risk) * Local officials * Lower judicial positions * Military officers below senior ranks ### RCAs - Relatives and Close Associates * Immediate family members (spouse, children, parents) * Known close associates * Business partners of PEPs ## Risk Factors The check may flag concerns if: * Current senior PEP (Tier 1) in high-risk jurisdiction * Current foreign PEP requiring enhanced due diligence * Close associate or family member of senior PEP * Former PEP from high-corruption country (less than 5 years) * Multiple PEP matches suggesting possible identity confusion * PEP from sanctioned country or regime ## Enhanced Due Diligence (EDD) PEP matches typically require: 1. **Source of Wealth Verification**: Document legitimate income sources 2. **Source of Funds**: Verify transaction fund origins 3. **Purpose of Relationship**: Understand business relationship purpose 4. **Ongoing Monitoring**: Enhanced transaction monitoring 5. **Senior Management Approval**: Elevated approval for onboarding ## Best Practices 1. **Risk-Based Approach**: Not all PEPs are high-risk (consider jurisdiction, position, tenure) 2. **Former PEPs**: Apply EDD for 3-5 years after leaving office 3. **RCA Verification**: Investigate RCA relationships carefully 4. **Update Regularly**: PEP status can change; rescreen periodically 5. **Document Decisions**: Keep clear records of PEP screening and risk assessments 6. **Combined Screening**: Use with sanctions and adverse media checks ## Configuration Options * **vendor**: Choose PEP database provider (ComplyAdvantage, Dow Jones, World-Check) * **profile\_limit**: Maximum PEP profiles to return * **match\_thresholds**: Customize match rating thresholds * **deny\_match\_ratings**: Auto-deny on strong matches * **review\_match\_ratings**: Flag for manual review * **extract\_pep\_metadata**: Extract detailed PEP information ## Related Checks * [Sanctions Screening (Individual)](/checks/kyc-sanctions-screening-check) - Screen for sanctions * [Adverse Media Screening (Individual)](/checks/kyc-adverse-media-screening) - Screen for negative news * [Person Web Presence Check](/checks/kyc-person-web-presence-check) - Research online presence * [Source of Funds Document Verification](/checks/source-of-funds-document-verification) - Verify fund sources # Person Web Presence Check Source: https://docs.parcha.ai/checks/kyc-person-web-presence-check Research and verify an individual's online presence and professional background The Person Web Presence check analyzes an individual's digital footprint across professional networks, social media, and public records. This check helps verify identity, employment history, and legitimacy through online research. ## Overview The check examines: * LinkedIn profiles and professional networks * Social media presence (Twitter, Facebook, etc.) * Company websites and team pages * Professional directories and associations * News articles and press mentions * Public records and registries ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYCAgentJob ``` **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. ### Request Parameters Your KYC agent key from the Parcha dashboard. This is unique to your organization and agent configuration. The individual information for research using the [KYC Schema](/schemas/individual-schema). A unique identifier for this KYC case. Individual's first name. Individual's last name. Individual's middle name. Job title or position. Current employer or business name. Email address for matching. Phone number for matching. Country of residence (ISO 3166-1 alpha-2). Address information for context. Optional. To run only this specific check, include `["kyc.person_web_presence_check"]`. If omitted, all checks configured in your agent will run. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYCAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyc-agent-key", "kyc_schema": { "id": "person-web-check-001", "self_attested_data": { "first_name": "Sarah", "last_name": "Johnson", "title": "Chief Technology Officer", "company_name": "TechStart Inc", "email_address": "sarah@techstart.example", "country_of_residence": "US", "address": { "city": "San Francisco", "state": "CA", "country_code": "US" } } }, "check_ids": ["kyc.person_web_presence_check"] }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYCAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyc-agent-key', # Replace with your actual agent key 'kyc_schema': { 'id': 'person-web-check-001', 'self_attested_data': { 'first_name': 'Sarah', 'last_name': 'Johnson', 'title': 'Chief Technology Officer', 'company_name': 'TechStart Inc', 'email_address': 'sarah@techstart.example', 'country_of_residence': 'US', 'address': { 'city': 'San Francisco', 'state': 'CA', 'country_code': 'US' } } }, 'check_ids': ['kyc.person_web_presence_check'] # Optional: run only this check } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYCAgentJob'; const data = { agent_key: 'your-kyc-agent-key', // Replace with your actual agent key kyc_schema: { id: 'person-web-check-001', self_attested_data: { first_name: 'Sarah', last_name: 'Johnson', title: 'Chief Technology Officer', company_name: 'TechStart Inc', email_address: 'sarah@techstart.example', country_of_residence: 'US', address: { city: 'San Francisco', state: 'CA', country_code: 'US' } } }, check_ids: ['kyc.person_web_presence_check'] // Optional: run only this check }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The person web presence check follows these steps: 1. **Online Research** * Searches LinkedIn for professional profiles * Queries social media platforms * Searches company websites and team pages * Reviews news articles and press releases 2. **Profile Matching** * Identifies potential profile matches * Evaluates match confidence based on: * Name similarity * Location alignment * Job title/company match * Email domain match * Filters out false positives 3. **Data Extraction** * Extracts employment history * Collects education background * Identifies professional skills and expertise * Gathers contact information (email, phone, addresses) 4. **Verification** * Cross-references self-attested data with findings * Validates current employment and title * Confirms location and contact details * Assesses profile completeness and activity ## Check Results ### Response Structure ```typescript theme={null} { type: "PersonWebPresenceCheckResult"; passed: boolean; profiles: Array; employment_history?: Array; education?: Array; contact_info?: { emails?: Array; phone_numbers?: Array; addresses?: Array; }; verification?: { name_verified: boolean; title_verified: boolean; company_verified: boolean; location_verified: boolean; }; confidence_score: number; } type OnlineProfile = { platform: "linkedin" | "twitter" | "facebook" | "company_website" | "other"; profile_url: string; name: string; title?: string; company?: string; location?: string; match_confidence: number; last_updated?: string; profile_summary?: string; } type Employment = { company: string; title: string; start_date?: string; end_date?: string; location?: string; description?: string; source: string; } type Education = { institution: string; degree?: string; field_of_study?: string; graduation_year?: string; source: string; } ``` ### Example Results ```json Low Risk - Strong Verification theme={null} { "type": "PersonWebPresenceCheckResult", "passed": true, "profiles": [ { "platform": "linkedin", "profile_url": "https://linkedin.com/in/sarah-johnson-cto", "name": "Sarah Johnson", "title": "Chief Technology Officer", "company": "TechStart Inc", "location": "San Francisco, CA", "match_confidence": 95, "last_updated": "2024-02-01", "profile_summary": "Experienced technology leader with 15+ years in software development..." }, { "platform": "company_website", "profile_url": "https://techstart.example/team/sarah-johnson", "name": "Sarah Johnson", "title": "CTO", "company": "TechStart Inc", "match_confidence": 92 } ], "employment_history": [ { "company": "TechStart Inc", "title": "Chief Technology Officer", "start_date": "2022-01", "location": "San Francisco, CA", "source": "LinkedIn" }, { "company": "BigTech Corp", "title": "Senior Engineering Manager", "start_date": "2018-03", "end_date": "2021-12", "location": "Mountain View, CA", "source": "LinkedIn" } ], "education": [ { "institution": "Stanford University", "degree": "MS", "field_of_study": "Computer Science", "graduation_year": "2010", "source": "LinkedIn" } ], "contact_info": { "emails": ["sarah@techstart.example"], "phone_numbers": ["+1-415-555-0123"], "addresses": ["San Francisco, CA"] }, "verification": { "name_verified": true, "title_verified": true, "company_verified": true, "location_verified": true }, "confidence_score": 94 } ``` ```json Medium Risk - Partial Verification theme={null} { "type": "PersonWebPresenceCheckResult", "passed": true, "profiles": [ { "platform": "linkedin", "profile_url": "https://linkedin.com/in/sarah-johnson-789", "name": "Sarah Johnson", "title": "Technology Consultant", "company": "Self-Employed", "location": "San Francisco, CA", "match_confidence": 72, "last_updated": "2023-08-15" } ], "employment_history": [ { "company": "Self-Employed", "title": "Technology Consultant", "start_date": "2020-06", "location": "San Francisco, CA", "source": "LinkedIn" } ], "verification": { "name_verified": true, "title_verified": false, "company_verified": false, "location_verified": true }, "confidence_score": 68 } ``` ```json High Risk - No Presence Found theme={null} { "type": "PersonWebPresenceCheckResult", "passed": false, "profiles": [], "employment_history": [], "education": [], "contact_info": {}, "verification": { "name_verified": false, "title_verified": false, "company_verified": false, "location_verified": false }, "confidence_score": 0 } ``` ## Risk Factors The check may flag concerns if: * No online presence found at all * Self-attested information doesn't match online profiles * Current employment cannot be verified * Profile activity is outdated or abandoned * Multiple conflicting profiles found * Limited professional history or credentials * Location discrepancies * Unusual career gaps or inconsistencies ## Use Cases Common applications include: * **KYC Verification**: Verify customer identity and employment * **UBO Identification**: Research beneficial owners * **Executive Verification**: Validate leadership credentials * **Employment Screening**: Verify employment history * **Professional Background Checks**: Confirm qualifications * **Fraud Prevention**: Detect synthetic identities or fabricated backgrounds ## Configuration Options * **min\_match\_confidence**: Minimum confidence score for profile matching (default: 0.8) * **analysis\_depth**: How deep to search (1-3, default: 2) * **platforms\_to\_search**: Select specific platforms * **enable\_pdl\_enrichment**: Use People Data Labs for enrichment ## Best Practices 1. **Provide Complete Information**: More data improves matching accuracy 2. **Verify Key Details**: Cross-check employment and title 3. **Consider Profile Age**: Check when profiles were last updated 4. **Look for Consistency**: Verify information matches across platforms 5. **Combine with Other Checks**: Use alongside AML screening 6. **Respect Privacy**: Only collect necessary information 7. **Document Sources**: Keep records of where information was found ## Data Sources This check may utilize: * LinkedIn and professional networks * Company websites and team pages * Social media platforms * Professional directories * News articles and press releases * People Data Labs and data enrichment services ## Related Checks * [Adverse Media Screening (Individual)](/checks/kyc-adverse-media-screening) - Screen for negative news * [PEP Screening (Individual)](/checks/kyc-pep-screening-check) - Screen for PEP status * [Sanctions Screening (Individual)](/checks/kyc-sanctions-screening-check) - Screen sanctions lists * [Business Owners Research](/checks/business-owners-check) - Verify business ownership # Individual (KYC) Proof of Address Document Verification Source: https://docs.parcha.ai/checks/kyc-proof-of-address-document-verification Learn how to run proof of address document verification checks to validate individual address information The Individual (KYC) Proof of Address Document Verification check helps verify the authenticity of individual proof of address documents and validates the physical address. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Check ID `kyc.proof_of_address_verification` ## Overview The check analyzes various aspects of proof of address documents: * Document authenticity and validity * Individual name verification * Physical address validation * Document type verification * Document date validation ## How the Check Works 1. **Document Analysis** * Extracts key information from proof of address documents * Validates document structure and format * Verifies document type is acceptable * Checks document authenticity 2. **Information Verification** * Cross-references extracted data with self-attested information * Validates individual's name matches * Confirms physical address * Verifies document dates are within validity period * Considers cultural variations in name representation, spelling, and order 3. **Address Validation** * Verifies address is a physical location * Validates address components * Checks address matches self-attested information ### Document Requirements The following information must be present in the proof of address documents for it to be considered valid: #### Bank Statement * Name and address of the account holder * Bank name and logo * Account number * Transaction details * Period of statement #### Utility Bill * Name and address of the account holder * Service provider's name and logo * Account number * Billing period #### Driver License * Name and address of the account holder * Document number * Issuing authority * Expiry date #### Credit Card Statement * Name and address of the account holder * Credit card provider's name and logo * Account number * Transaction details * Period of statement #### Insurance Policy * Name and address of the account holder * Insurance provider's name and logo * Account number * Period of insurance #### Tax Document * Name and address of the taxpayer * Tax authority's name and logo #### Tenancy/Lease Agreement * Name of the tenant * Address of the rented property * Landlord's name and contact details * Rental period * Lease end date (must be in the future) ## Check Configuration The check can be configured with the following parameters: Number of days within which the proof of address document should be valid. Whether to verify that the address in the document matches the self-attested address. Whether to enable visual verification of documents. Whether to enable document fraud detection. List of accepted document types. Available options: * "Bank statement" * "Utility bill" * "Driver License" * "Credit card statement" * "Insurance policy" * "Tax document" * "Tenancy agreement" * "Lease agreement" ### Example Configuration ```json theme={null} { "validity_period": 90, "verify_self_attested_address": true, "enable_visual_verification": true, "enable_fraud_check": true, "accepted_documents": [ "Bank statement", "Utility bill", "Driver License", "Credit card statement", "Insurance policy", "Tax document", "Tenancy agreement", "Lease agreement" ] } ``` ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYCAgentJob ``` **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. ### Request Parameters Your KYC agent key from the Parcha dashboard. This is unique to your organization and agent configuration. The individual information for verification using the [KYC Schema](/schemas/individual-schema). Optional. To run only this specific check, include `["kyc.proof_of_address_verification"]`. If omitted, all checks configured in your agent will run. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYCAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyc-agent-key", "kyc_schema": { "id": "kyc-poa-check-001", "self_attested_data": { "first_name": "John", "last_name": "Doe", "address": { "street_1": "746 4th Avenue", "city": "San Francisco", "state": "CA", "postal_code": "94118", "country_code": "US" }, "proof_of_address_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/John_proof_of_address.pdf", "file_name": "John_proof_of_address.pdf", "source_type": "file_url" } ] } }, "check_ids": ["kyc.proof_of_address_verification"], "webhook_url": "https://your-webhook.com/check-updates" }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYCAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyc-agent-key', # Replace with your actual agent key 'kyc_schema': { 'id': 'kyc-poa-check-001', 'self_attested_data': { 'first_name': 'John', 'last_name': 'Doe', 'address': { 'street_1': '746 4th Avenue', 'city': 'San Francisco', 'state': 'CA', 'postal_code': '94118', 'country_code': 'US' }, 'proof_of_address_documents': [ { 'url': 'https://storage.googleapis.com/parcha-ai-public-assets/John_proof_of_address.pdf', 'file_name': 'John_proof_of_address.pdf', 'source_type': 'file_url' } ] } }, 'check_ids': ['kyc.proof_of_address_verification'], # Optional: run only this check 'webhook_url': 'https://your-webhook.com/check-updates' } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYCAgentJob'; const data = { agent_key: 'your-kyc-agent-key', // Replace with your actual agent key kyc_schema: { id: 'kyc-poa-check-001', self_attested_data: { first_name: 'John', last_name: 'Doe', address: { street_1: '746 4th Avenue', city: 'San Francisco', state: 'CA', postal_code: '94118', country_code: 'US' }, proof_of_address_documents: [ { url: 'https://storage.googleapis.com/parcha-ai-public-assets/John_proof_of_address.pdf', file_name: 'John_proof_of_address.pdf', source_type: 'file_url' } ] } }, check_ids: ['kyc.proof_of_address_verification'], // Optional: run only this check webhook_url: 'https://your-webhook.com/check-updates' }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-kyc-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ### Example Response ```json theme={null} { "id": "check-12345-abcde", "status": "PENDING", "created_at": "2024-03-15T15:30:00Z", "updated_at": "2024-03-15T15:30:00Z", "agent_id": "your-kyc-agent-key", "input_payload": { "agent_key": "your-kyc-agent-key", "check_id": "kyc.proof_of_address_verification", "payload": { "id": "kyc-poa-check-001", "self_attested_data": { "full_name": "John Doe", "address": { "street_1": "746 4th Avenue", "city": "San Francisco", "state": "CA", "postal_code": "94118", "country_code": "US" }, "proof_of_address_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/John_proof_of_address.pdf", "type": "Document", "file_name": "John_proof_of_address.pdf", "source_type": "gcs" } ] } }, "check_args": { "validity_period": 90, "verify_self_attested_address": true, "accepted_documents": [ "Bank statement", "Utility bill", "Driver License", "Credit card statement", "Insurance policy", "Tax document", "Tenancy agreement", "Lease agreement" ], "enable_visual_verification": true, "enable_fraud_check": true }, "webhook_url": "https://your-webhook.com/check-updates" } } ``` ## Check Results The check returns a detailed analysis of the proof of address documents and verification results. For full details of the response structure, see the [Individual Proof of Address Document Verification Result](/api-reference/check-results/kyc-proof-of-address-document-verification) documentation. # Sanctions Screening Check (Individual) Source: https://docs.parcha.ai/checks/kyc-sanctions-screening-check Screen individuals against global sanctions lists and watchlists The Individual Sanctions Screening check verifies whether an individual appears on government sanctions lists, terrorist watchlists, or other regulatory enforcement databases. This is a mandatory compliance check for AML/CFT programs. ## Overview The check examines: * OFAC (Office of Foreign Assets Control) SDN list * UN Security Council sanctions * EU sanctions lists * UK HM Treasury sanctions * Interpol Red Notices * FBI Most Wanted lists * Country-specific terrorist lists ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYCAgentJob ``` **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. ### Request Parameters Your KYC agent key from the Parcha dashboard. This is unique to your organization and agent configuration. The individual information for screening using the [KYC Schema](/schemas/individual-schema). A unique identifier for this KYC case. Individual's first name. Individual's last name. Individual's middle name. Date of birth (YYYY-MM-DD format). Country of nationality (ISO 3166-1 alpha-2). Country of residence (ISO 3166-1 alpha-2). Residential address information for additional matching. Optional. To run only this specific check, include `["kyc.sanctions_screening_check_v2"]`. If omitted, all checks configured in your agent will run. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYCAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyc-agent-key", "kyc_schema": { "id": "sanctions-check-001", "self_attested_data": { "first_name": "John", "last_name": "Doe", "middle_name": "Michael", "date_of_birth": "1980-03-15", "country_of_nationality": "US", "country_of_residence": "US", "address": { "city": "New York", "state": "NY", "country_code": "US" } } }, "check_ids": ["kyc.sanctions_screening_check_v2"] }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYCAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyc-agent-key', # Replace with your actual agent key 'kyc_schema': { 'id': 'sanctions-check-001', 'self_attested_data': { 'first_name': 'John', 'last_name': 'Doe', 'middle_name': 'Michael', 'date_of_birth': '1980-03-15', 'country_of_nationality': 'US', 'country_of_residence': 'US', 'address': { 'city': 'New York', 'state': 'NY', 'country_code': 'US' } } }, 'check_ids': ['kyc.sanctions_screening_check_v2'] # Optional: run only this check } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYCAgentJob'; const data = { agent_key: 'your-kyc-agent-key', // Replace with your actual agent key kyc_schema: { id: 'sanctions-check-001', self_attested_data: { first_name: 'John', last_name: 'Doe', middle_name: 'Michael', date_of_birth: '1980-03-15', country_of_nationality: 'US', country_of_residence: 'US', address: { city: 'New York', state: 'NY', country_code: 'US' } } }, check_ids: ['kyc.sanctions_screening_check_v2'] // Optional: run only this check }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The sanctions screening check follows these steps: 1. **Name Normalization** * Standardizes name for matching * Handles name variations and transliterations * Processes nicknames and aliases 2. **Database Search** * Searches multiple sanctions databases * Queries terrorist watchlists * Checks law enforcement databases * Searches PEP-related sanctions 3. **Match Analysis** * Evaluates match quality (strong, partial, weak) * Compares date of birth if available * Analyzes location and nationality data * Reviews additional identifiers 4. **Risk Assessment** * Categorizes sanctions program severity * Evaluates geographic risk factors * Determines action required (deny, review, approve) ## Check Results ### Response Structure ```typescript theme={null} { type: "SanctionsScreeningCheckResult"; passed: boolean; matches: Array; total_matches: number; screening_date: string; databases_searched: Array; } type SanctionsMatch = { name: string; match_rating: "strong_match" | "partial_match" | "weak_match" | "false_positive"; match_score: number; list_type: "sanctions" | "terrorism" | "law_enforcement" | "other"; list_name: string; date_of_birth?: string; place_of_birth?: string; nationality?: Array; program?: string; listed_date?: string; addresses?: Array; aliases?: Array; identifiers?: { passport_numbers?: Array; national_ids?: Array; }; source_url?: string; } ``` ### Example Results ```json Low Risk - No Matches theme={null} { "type": "SanctionsScreeningCheckResult", "passed": true, "matches": [], "total_matches": 0, "screening_date": "2024-02-15T10:30:00Z", "databases_searched": [ "OFAC SDN", "UN Security Council", "EU Sanctions", "UK HM Treasury", "Interpol Red Notices" ] } ``` ```json Medium Risk - Weak Match (Likely False Positive) theme={null} { "type": "SanctionsScreeningCheckResult", "passed": true, "matches": [ { "name": "John Michael Doe", "match_rating": "weak_match", "match_score": 68, "list_type": "sanctions", "list_name": "OFAC SDN List", "date_of_birth": "1978-05-20", "nationality": ["Syria"], "program": "SYRIA", "listed_date": "2019-06-12", "addresses": [ "Damascus, Syria" ], "source_url": "https://sanctionssearch.ofac.treas.gov/" } ], "total_matches": 1, "screening_date": "2024-02-15T10:30:00Z", "databases_searched": [ "OFAC SDN", "UN Security Council", "EU Sanctions" ] } ``` ```json High Risk - Strong Match theme={null} { "type": "SanctionsScreeningCheckResult", "passed": false, "matches": [ { "name": "John Michael Doe", "match_rating": "strong_match", "match_score": 96, "list_type": "terrorism", "list_name": "OFAC SDN - Terrorism", "date_of_birth": "1980-03-15", "place_of_birth": "New York, United States", "nationality": ["United States"], "program": "SDGT", "listed_date": "2023-08-15", "addresses": [ "123 Main St, New York, NY, US" ], "aliases": [ "J. Doe", "Johnny Doe" ], "identifiers": { "passport_numbers": ["US123456789"] }, "source_url": "https://sanctionssearch.ofac.treas.gov/" } ], "total_matches": 1, "screening_date": "2024-02-15T10:30:00Z", "databases_searched": [ "OFAC SDN", "UN Security Council", "EU Sanctions", "FBI Most Wanted" ] } ``` ## Sanctions Lists Covered ### Primary Sanctions Lists * **OFAC SDN** - Specially Designated Nationals and Blocked Persons * **OFAC Non-SDN** - Consolidated sanctions lists * **UN Security Council** - Consolidated sanctions list * **EU Sanctions** - EU consolidated financial sanctions * **UK HM Treasury** - UK financial sanctions targets ### Law Enforcement & Terrorism Lists * **FBI Most Wanted** * **Interpol Red Notices** * **National terrorist lists** (US, UK, EU, etc.) * **DEA Most Wanted** ### Additional Lists * Country-specific sanctions (Canada, Australia, Japan, etc.) * Financial crimes watchlists * Proliferation financing lists ## Match Ratings Explained * **Strong Match**: High confidence the individual is sanctioned (DENY) * Name, DOB, and location all match * Multiple identifiers align * **Partial Match**: Some identifiers match, requires review * Name and location match but DOB differs * Similar name with matching location * **Weak Match**: Name similarity only, likely false positive * Common name with different location/DOB * Only surname matches * **False Positive**: Confirmed not the sanctioned individual (APPROVE) * After investigation, clearly different person ## Risk Factors The check may flag concerns if: * Name and DOB strongly match sanctioned individual * Individual from sanctioned jurisdiction * Multiple identifiers match (passport, address, etc.) * Recent addition to sanctions or terrorism lists * Close name match with known terrorist or criminal * Location matches known sanctioned individual ## Compliance Requirements Individual sanctions screening is required for: * Customer onboarding (KYC) * Beneficial owner identification * Transaction screening * Wire transfer compliance * Ongoing monitoring (periodic rescreening) * Regulatory compliance (AML/BSA/OFAC) ## Best Practices 1. **Screen All Individuals**: Screen customers, beneficial owners, signatories, and authorized persons 2. **Use Full Name and DOB**: Provide complete information for accurate matching 3. **Investigate Matches**: Review partial matches carefully before rejecting 4. **Document Thoroughly**: Keep detailed records of screening and decisions 5. **Rescreen Regularly**: Perform ongoing monitoring (monthly recommended) 6. **Escalate Strong Matches**: Immediately escalate strong matches to compliance 7. **File SARs When Required**: Report suspicious activity as mandated ## Legal Obligations **US Compliance**: OFAC requires immediate blocking of SDN assets and transactions. Violations can result in civil penalties up to $330,120 per violation or criminal penalties up to $1 million and 20 years imprisonment. **Global Compliance**: Most jurisdictions have similar requirements for sanctions compliance with severe penalties for violations. ## Configuration Options * **vendor**: Choose screening vendor (ComplyAdvantage, Dow Jones, etc.) * **match\_thresholds**: Customize match rating thresholds * **deny\_match\_ratings**: Auto-deny on specified match ratings (typically strong\_match) * **review\_match\_ratings**: Flag for manual review (typically partial\_match) * **databases\_to\_search**: Select specific sanctions lists ## Related Checks * [PEP Screening (Individual)](/checks/kyc-pep-screening-check) - Screen for PEP status * [Adverse Media Screening (Individual)](/checks/kyc-adverse-media-screening) - Screen for negative news * [Person Web Presence Check](/checks/kyc-person-web-presence-check) - Research online presence * [Sanctions Screening (Business)](/checks/sanctions-screening-check) - Screen associated businesses # MCC Code Check Source: https://docs.parcha.ai/checks/mcc-code-check Classify businesses with Merchant Category Codes (MCC) based on their activities and web presence The MCC Code Check (`kyb.mcc_code_check_v3`) analyzes a business's online presence, products, and services to determine the most appropriate Merchant Category Code (MCC) for payment processing and risk assessment. ## Overview Merchant Category Codes (MCCs) are four-digit numbers used by credit card networks to classify businesses. This check: * Analyzes business description and stated activities * Reviews website content and web presence data * Identifies products and services offered * Cross-references against the official MCC code database * Provides alternative MCC candidates with reasoning ## Check ID ``` kyb.mcc_code_check_v3 ``` ## Response Schema The check result payload uses the `MCCCodeCheckResultV2` schema: ### Primary Fields Always `"MCCCodeCheckResultV2"` - identifies the payload type. The determined 4-digit Merchant Category Code. **Example**: `"7372"` The official title for the MCC code. **Example**: `"Computer Programming Services"` Full description of what businesses typically fall under this MCC code. **Example**: `"Merchants classified with this MCC provide computer programming services, systems design, website design, data entry, and data processing services."` Optional sub-category for more specific classification (used when customer-specific MCC mappings are configured). **Example**: `"Butcher Shop"` Reference ID for the data source that supported this MCC determination. ### Candidate MCC Codes List of alternative MCC codes that were considered, with reasoning. The 4-digit MCC code. **Example**: `7372` The official title for this MCC code. **Example**: `"Computer Programming Services"` Brief explanation of why this MCC was considered a candidate. **Example**: `"Primary match - Business develops AI-powered software solutions involving computer programming, systems design, and data processing services."` Reference ID for the data source supporting this candidate. **Example**: `"owfzyz"` ## Example Response The check result includes a wrapper with metadata and the `payload` containing the MCC classification: ```json theme={null} { "command_id": "kyb.mcc_code_check_v3", "command_name": "MCC Code Check", "status": "complete", "passed": true, "recommendation": "7372", "explanation": "The analysis determined MCC 7372 (Computer Programming Services) as the most accurate classification based on the business's primary activities in software development and data processing...", "payload": { "type": "MCCCodeCheckResultV2", "mcc_code": "7372", "mcc_title": "Computer Programming Services", "mcc_code_description": "Merchants classified with this MCC provide computer programming services, systems design, website design, data entry, and data processing services.", "candidate_mcc_codes": [ { "code": 7372, "title": "Computer Programming Services", "short_reason": "Primary match - Business develops AI-powered software solutions involving computer programming, systems design, and data processing services.", "source_id": "owfzyz" }, { "code": 7379, "title": "Computer Related Services", "short_reason": "Secondary consideration - Could apply for consulting aspects but less specific than 7372 for their software development focus.", "source_id": "schjuw" } ], "sub_mcc_category": null, "source_id": "owfzyz" }, "alerts": {} } ``` ## Extracting MCC Data with JSONPath Use the `jsonpath_query` parameter with `getJobById` to extract specific MCC check data. ### Get Full MCC Check Result ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.mcc_code_check_v3")]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Get Just the MCC Code Payload ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.mcc_code_check_v3")].payload' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Example Response:** ```json theme={null} [ { "type": "MCCCodeCheckResultV2", "mcc_code": "7372", "mcc_title": "Computer Programming Services", "mcc_code_description": "Merchants classified with this MCC provide computer programming services...", "candidate_mcc_codes": [...], "sub_mcc_category": null, "source_id": "web_profile_1" } ] ``` ### Get MCC Code Only ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.mcc_code_check_v3")].payload.mcc_code' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` **Example Response:** ```json theme={null} ["7372"] ``` ### Get All Candidate MCC Codes ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.mcc_code_check_v3")].payload.candidate_mcc_codes[*]' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Python Example ```python theme={null} import requests from urllib.parse import quote api_key = 'YOUR_API_KEY' job_id = 'YOUR_JOB_ID' # Get MCC code payload using JSONPath jsonpath_query = '$.check_results[?(@.command_id=="kyb.mcc_code_check_v3")].payload' url = f'https://api.parcha.ai/api/v1/getJobById?job_id={job_id}&include_check_results=true&jsonpath_query={quote(jsonpath_query)}' headers = {'Authorization': f'Bearer {api_key}'} response = requests.get(url, headers=headers) mcc_result = response.json() if mcc_result: payload = mcc_result[0] print(f"MCC Code: {payload['mcc_code']}") print(f"Title: {payload['mcc_title']}") print(f"Description: {payload['mcc_code_description']}") ``` ## Running the Check ### Using startKYBAgentJob ```bash theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "public-bdd", "kyb_schema": { "id": "mcc-check-001", "self_attested_data": { "business_name": "CloudTech Solutions", "description": "We provide cloud-based software solutions for small businesses, including accounting software, CRM tools, and project management platforms delivered as SaaS", "website": "https://cloudtech.example", "industry": "Software as a Service" } } }' ``` ### Using runCheck (Single Check) ```bash theme={null} curl -X POST 'https://api.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": { "business_name": "TechInnovate Solutions", "description": "Providing cutting-edge software solutions for businesses", "website": "https://techinnovatesolutions.com" } }, "check_id": "kyb.mcc_code_check_v3", "webhook_url": "https://your-webhook-url.com/callback" }' ``` ## Input Parameters The check uses the following input fields: The legal or operating name of the business. A detailed description of the business's activities, products, and services. More detail leads to more accurate MCC classification. The primary business activity or use case. This field takes priority when determining the MCC code. The official website URL. The check will analyze website content for additional context. Self-attested industry or business category. Self-attested MCC code to verify. If provided, the check will compare against the determined MCC and note any discrepancies. ## Common MCC Codes | Code | Title | Description | | ---- | -------------------------------------------------------------------- | -------------------------------------------------------- | | 7372 | Computer Programming Services | Custom software development, web design, data processing | | 7371 | Computer Programming, Data Processing, and Integrated Systems Design | Systems integration, data processing services | | 7379 | Computer Maintenance, Repair and Services | IT consulting, maintenance, support services | | 5734 | Computer Software Stores | Software retail, SaaS products | | 5999 | Miscellaneous and Specialty Retail Stores | General e-commerce, online retail | | 7311 | Advertising Agencies | Digital marketing, advertising services | | 5812 | Eating Places and Restaurants | Restaurants, food service | | 5411 | Grocery Stores, Supermarkets | Food retail | ## High-Risk MCC Codes The following MCC codes are flagged as high-risk by default (configurable per agent): | Code | Title | Risk Factors | | ---- | --------------------------------------- | --------------------------------------------- | | 7995 | Gambling/Casino Services | Regulatory requirements, high chargeback risk | | 5993 | Tobacco Stores and Stands | Age restrictions, regulatory compliance | | 5963 | Door-To-Door Sales | High fraud and chargeback rates | | 4829 | Money Transfer Services | MSB licensing, AML requirements | | 6211 | Securities Brokers/Dealers | Financial services licensing | | 6051 | Non-Financial Institutions | Money services, currency exchange | | 6012 | Financial Institutions | Regulatory compliance, licensing | | 6540 | POI Funding Transactions | Prepaid card funding, AML concerns | | 7273 | Dating and Escort Services | Content policies, fraud risk | | 5967 | Direct Marketing - Inbound Teleservices | High chargeback risk | ## Check Outcomes ### Pass Conditions The check passes when: * Sufficient verification data is available to determine an MCC * A reasonable MCC classification can be made with confidence ### Fail Conditions The check fails when: * No verification data or search results are available * The data is too vague or limited to determine an MCC with confidence MCC discrepancies between self-attested and determined codes do **not** cause the check to fail. Discrepancies are reported as alerts while the check still passes with the determined MCC. ## Related Checks * [High Risk Industry Check](/checks/high-risk-industry-check) - Identify prohibited or restricted industries * [Basic Business Profile Check](/checks/basic-business-profile-check) - Verify business profile information * [Web Presence Check](/checks/web-presence-check) - Analyze online presence and website data # Proof of Address Document Verification Source: https://docs.parcha.ai/checks/proof-of-address-document-verification Learn how to run proof of address document verification checks to validate business address information The Proof of Address Document Verification check helps verify the authenticity of business proof of address documents and validates the physical business address. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Check ID `kyb.proof_of_address_verification` ## Overview The check analyzes various aspects of proof of address documents: * Document authenticity and validity * Business name verification * Physical address validation * Document type verification * Document date validation ## How the Check Works 1. **Document Analysis** * Extracts key information from proof of address documents * Validates document structure and format * Verifies document type is acceptable * Checks document authenticity 2. **Information Verification** * Cross-references extracted data with self-attested information * Validates business name matches * Confirms physical address (no P.O. Boxes) * Verifies document dates are within validity period 3. **Address Validation** * Verifies address is a physical location * Validates address components * Confirms address is not a P.O. Box or registered agent address * Checks address matches self-attested information ### Document Requirements The following information must be present in the proof of address documents for it to be considered valid: #### Bank Statement * Name and address of the account holder * Bank name and logo * Account number * Transaction details * Period of statement #### VAT Invoice * Name and address of the business * VAT number * Invoice number * Period of billing * Amount details #### Utility Bill * Name and address of the account holder * Service provider's name and logo * Account number * Billing period #### Tenancy/Lease Agreement * Name of the tenant or lessee * Address of the rented property * Landlord's name and contact details * Rental period * Lease end date (must be in the future) #### Tax Document * Name and address of the taxpayer * Tax authority's name and logo #### Mortgage Statement * Name and logo of the mortgage provider * Name and address of the account holder * Mortgage details #### Credit Card Statement * Name and address of the account holder * Credit card provider's name and logo * Account number * Transaction details * Period of statement #### Insurance Policy * Name and address of the account holder * Insurance provider's name and logo * Account number * Period of insurance #### Driver License * Name and address of the account holder * Document number * Issuing authority * Expiry date ## Check Configuration The check can be configured with the following parameters: Number of days within which the proof of address document should be valid. Whether to verify that the address in the document matches the self-attested address. Whether to include associated individuals in the verification (e.g. for LLCs, or for a sole proprietor). Whether to enable visual verification of documents. Whether to enable document fraud detection. List of accepted document types. Available options: * "Bank statement" * "VAT invoice" * "Utility bill" * "Tenancy agreement" * "Tax document" * "Mortgage statement" * "Credit card statement" * "Insurance policy" * "Lease agreement" * "Driver License" Whether P.O. Box addresses are allowed as valid proof of address. Whether residential addresses are allowed as valid proof of address. Whether registered agent addresses (e.g., Delaware registered agent address) are allowed as valid proof of address. ### Example Configuration ```json theme={null} { "validity_period": 90, "verify_self_attested_address": true, "include_associated_individuals": false, "enable_visual_verification": true, "enable_fraud_check": true, "accepted_documents": [ "Bank statement", "VAT invoice", "Utility bill", "Tenancy agreement", "Tax document", "Mortgage statement", "Credit card statement", "Insurance policy", "Lease agreement" ], "po_box_is_allowed": false, "residential_is_allowed": false, "registered_agent_address_is_allowed": false } ``` ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.proof_of_address_verification", "payload": { "id": "poa-check-001", "self_attested_data": { "business_name": "Acme Corp, Inc.", "address_of_operation": { "street_1": "251 Little Falls Drive", "city": "Wilmington", "state": "Delaware", "postal_code": "19808", "country_code": "US" }, "proof_of_address_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/acme_bank_statement.pdf", "type": "Document", "file_name": "acme_bank_statement.pdf", "source_type": "gcs" } ] } }, "check_args": { "validity_period": 90, "include_associated_individuals": false, "verify_self_attested_address": true, "accepted_documents": [ "Bank statement", "VAT invoice", "Utility bill", "Tenancy agreement", "Tax document", "Mortgage statement", "Credit card statement", "Insurance policy", "Lease agreement" ], "enable_visual_verification": true, "enable_fraud_check": true }, "webhook_url": "https://your-webhook.com/check-updates" }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.proof_of_address_verification', 'payload': { 'id': 'poa-check-001', 'self_attested_data': { 'business_name': 'Acme Corp, Inc.', 'address_of_operation': { 'street_1': '251 Little Falls Drive', 'city': 'Wilmington', 'state': 'Delaware', 'postal_code': '19808', 'country_code': 'US' }, 'proof_of_address_documents': [ { 'url': 'https://storage.googleapis.com/parcha-ai-public-assets/acme_bank_statement.pdf', 'type': 'Document', 'file_name': 'acme_bank_statement.pdf', 'source_type': 'gcs' } ] } }, 'check_args': { 'validity_period': 90, 'include_associated_individuals': False, 'verify_self_attested_address': True, 'accepted_documents': [ 'Bank statement', 'VAT invoice', 'Utility bill', 'Tenancy agreement', 'Tax document', 'Mortgage statement', 'Credit card statement', 'Insurance policy', 'Lease agreement' ], 'enable_visual_verification': True, 'enable_fraud_check': True }, 'webhook_url': 'https://your-webhook.com/check-updates' } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.proof_of_address_verification', payload: { id: 'poa-check-001', self_attested_data: { business_name: 'Acme Corp, Inc.', address_of_operation: { street_1: '251 Little Falls Drive', city: 'Wilmington', state: 'Delaware', postal_code: '19808', country_code: 'US' }, proof_of_address_documents: [ { url: 'https://storage.googleapis.com/parcha-ai-public-assets/acme_bank_statement.pdf', type: 'Document', file_name: 'acme_bank_statement.pdf', source_type: 'gcs' } ] } }, check_args: { validity_period: 90, include_associated_individuals: false, verify_self_attested_address: true, accepted_documents: [ 'Bank statement', 'VAT invoice', 'Utility bill', 'Tenancy agreement', 'Tax document', 'Mortgage statement', 'Credit card statement', 'Insurance policy', 'Lease agreement' ], enable_visual_verification: true, enable_fraud_check: true }, webhook_url: 'https://your-webhook.com/check-updates' }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ### Example Response ```json theme={null} { "id": "check-12345-abcde", "status": "PENDING", "created_at": "2024-03-15T15:30:00Z", "updated_at": "2024-03-15T15:30:00Z", "agent_id": "your-agent-key", "input_payload": { "agent_key": "your-kyb-agent-key", "check_id": "kyb.proof_of_address_verification", "payload": { "id": "poa-check-001", "self_attested_data": { "business_name": "Acme Corp, Inc.", "address_of_operation": { "street_1": "251 Little Falls Drive", "city": "Wilmington", "state": "Delaware", "postal_code": "19808", "country_code": "US" }, "proof_of_address_documents": [ { "url": "https://storage.googleapis.com/parcha-ai-public-assets/acme_bank_statement.pdf", "type": "Document", "file_name": "acme_bank_statement.pdf", "source_type": "gcs" } ] } }, "check_args": { "validity_period": 90, "include_associated_individuals": false, "verify_self_attested_address": true, "accepted_documents": [ "Bank statement", "VAT invoice", "Utility bill", "Tenancy agreement", "Tax document", "Mortgage statement", "Credit card statement", "Insurance policy", "Lease agreement" ], "enable_visual_verification": true, "enable_fraud_check": true }, "webhook_url": "https://your-webhook.com/check-updates" } } ``` ## Check Results The check returns a detailed analysis of the proof of address documents and verification results. For full details of the response structure, see the [Proof of Address Document Verification Result](/api-reference/check-results/proof-of-address-document-verification) documentation. # Sanctions Screening Check (Business) Source: https://docs.parcha.ai/checks/sanctions-screening-check Screen businesses against global sanctions lists and watchlists The Business Sanctions Screening check verifies whether a business appears on government sanctions lists, watchlists, or other regulatory enforcement databases. This is a critical compliance check for AML/CFT programs. ## Overview The check examines: * OFAC (Office of Foreign Assets Control) lists * UN Security Council sanctions * EU sanctions lists * UK HM Treasury sanctions * Other international sanctions programs * Enforcement actions and debarment lists ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.sanctions_screening_check_v2"` for business sanctions screening. The business information for screening. A unique identifier for this check case. The legal name of the business to screen. Alternative or registered business name. Country code (ISO 3166-1 alpha-2). City of incorporation. Operating address information. Date of incorporation (YYYY-MM-DD). ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.sanctions_screening_check_v2", "payload": { "id": "sanctions-check-001", "self_attested_data": { "business_name": "Global Trading LLC", "registered_business_name": "GLOBAL TRADING LIMITED LIABILITY COMPANY", "address_of_incorporation": { "country_code": "US", "city": "New York" }, "incorporation_date": "2019-03-15" } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.sanctions_screening_check_v2', 'payload': { 'id': 'sanctions-check-001', 'self_attested_data': { 'business_name': 'Global Trading LLC', 'registered_business_name': 'GLOBAL TRADING LIMITED LIABILITY COMPANY', 'address_of_incorporation': { 'country_code': 'US', 'city': 'New York' }, 'incorporation_date': '2019-03-15' } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.sanctions_screening_check_v2', payload: { id: 'sanctions-check-001', self_attested_data: { business_name: 'Global Trading LLC', registered_business_name: 'GLOBAL TRADING LIMITED LIABILITY COMPANY', address_of_incorporation: { country_code: 'US', city: 'New York' }, incorporation_date: '2019-03-15' } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The sanctions screening check follows these steps: 1. **Name Normalization** * Standardizes business name for matching * Handles name variations and transliterations * Processes aliases and trading names 2. **Database Search** * Searches multiple sanctions databases * Queries watchlists and enforcement lists * Checks subsidiary and affiliated entities 3. **Match Analysis** * Evaluates match quality (strong, partial, weak) * Considers name similarity * Analyzes location and entity type * Reviews additional identifiers 4. **Risk Assessment** * Categorizes sanctions list severity * Evaluates geographic risk factors * Determines action required (deny, review, approve) ## Check Results ### Response Structure ```typescript theme={null} { type: "SanctionsScreeningCheckResult"; passed: boolean; matches: Array; total_matches: number; screening_date: string; databases_searched: Array; } type SanctionsMatch = { entity_name: string; match_rating: "strong_match" | "partial_match" | "weak_match" | "false_positive"; match_score: number; list_type: string; list_name: string; country?: string; entity_type?: string; program?: string; listed_date?: string; addresses?: Array; identifiers?: { registration_numbers?: Array; other_names?: Array; }; source_url?: string; } ``` ### Example Results ```json Low Risk - No Matches theme={null} { "type": "SanctionsScreeningCheckResult", "passed": true, "matches": [], "total_matches": 0, "screening_date": "2024-02-15T10:30:00Z", "databases_searched": [ "OFAC SDN", "UN Security Council", "EU Sanctions", "UK HM Treasury" ] } ``` ```json Medium Risk - Possible False Positive theme={null} { "type": "SanctionsScreeningCheckResult", "passed": true, "matches": [ { "entity_name": "GLOBAL TRADING COMPANY", "match_rating": "weak_match", "match_score": 65, "list_type": "sanctions", "list_name": "OFAC SDN List", "country": "Iran", "entity_type": "Entity", "program": "IRAN", "listed_date": "2018-11-05", "addresses": [ "Tehran, Iran" ], "source_url": "https://sanctionssearch.ofac.treas.gov/" } ], "total_matches": 1, "screening_date": "2024-02-15T10:30:00Z", "databases_searched": [ "OFAC SDN", "UN Security Council", "EU Sanctions", "UK HM Treasury" ] } ``` ```json High Risk - Strong Match theme={null} { "type": "SanctionsScreeningCheckResult", "passed": false, "matches": [ { "entity_name": "GLOBAL TRADING LLC", "match_rating": "strong_match", "match_score": 95, "list_type": "sanctions", "list_name": "OFAC SDN List", "country": "Russia", "entity_type": "Entity", "program": "UKRAINE-EO13662", "listed_date": "2022-02-24", "addresses": [ "Moscow, Russia", "123 Tverskaya St, Moscow 125009" ], "identifiers": { "registration_numbers": ["1027700132195"], "other_names": ["Global Trading Limited"] }, "source_url": "https://sanctionssearch.ofac.treas.gov/" } ], "total_matches": 1, "screening_date": "2024-02-15T10:30:00Z", "databases_searched": [ "OFAC SDN", "UN Security Council", "EU Sanctions", "UK HM Treasury" ] } ``` ## Sanctions Lists Covered ### Primary Lists * **OFAC SDN** - Specially Designated Nationals * **OFAC Non-SDN** - Consolidated sanctions lists * **UN Security Council** - Consolidated list * **EU Sanctions** - EU consolidated list * **UK HM Treasury** - Financial sanctions targets ### Additional Lists * FBI Most Wanted * Interpol Red Notices * World Bank Debarment * DFAT Australia Sanctions * Various country-specific lists ## Match Ratings Explained * **Strong Match**: High confidence the entity is on sanctions list (DENY) * **Partial Match**: Some identifiers match, requires review * **Weak Match**: Name similarity only, likely false positive * **False Positive**: Confirmed not the sanctioned entity (APPROVE) ## Risk Factors The check may flag concerns if: * Business name strongly matches sanctioned entity * Located in sanctioned jurisdiction * Registration numbers match sanctioned entity * Recent addition to sanctions lists * Associated with sanctioned individuals or entities * Multiple weak matches across different lists ## Compliance Requirements Sanctions screening is typically required for: * Customer onboarding (KYB/KYC) * Ongoing monitoring and periodic rescreening * Transaction screening * Wire transfer compliance * Trade finance operations * Regulatory compliance (AML/BSA) ## Best Practices 1. **Screen at Onboarding**: Always screen before establishing business relationship 2. **Regular Rescreening**: Screen periodically (monthly or quarterly) 3. **Investigate Matches**: Don't auto-reject on weak matches 4. **Document Decisions**: Keep records of screening results and decisions 5. **Update Lists**: Use vendors with real-time list updates 6. **Cross-Reference**: Combine with web presence and adverse media checks ## Configuration Options * **vendor**: Choose screening vendor (ComplyAdvantage, Dow Jones, etc.) * **match\_thresholds**: Customize match rating thresholds * **lists\_to\_search**: Select specific sanctions lists * **ongoing\_monitoring**: Enable continuous monitoring ## Related Checks * [Adverse Media Screening](/checks/adverse-media-screening) - Screen for negative news * [High Risk Country Check](/checks/high-risk-country-check) - Assess geographic risk * [Business Registration Check](/checks/business-registration-check) - Verify legal entity * [Business Owners Check](/checks/business-owners-check) - Screen associated individuals # Source of Funds Document Verification Source: https://docs.parcha.ai/checks/source-of-funds-document-verification Learn how to run source of funds document verification checks to validate business funding information The Source of Funds Document Verification check helps verify the authenticity of business funding documents and validates the source of funds information. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Check ID `kyb.source_of_funds_document_check` ## Overview The check analyzes various aspects of source of funds documents: * Document authenticity and validity * Business name verification * Source of funds type and description validation * Funding amount verification * Document date validation * Document fraud detection ## How the Check Works 1. **Document Analysis** * Extracts key information from source of funds documents * Validates document structure and format * Verifies document authenticity * Identifies business name, funding source, and amount 2. **Information Verification** * Cross-references extracted data with self-attested information * Validates business name matches * Confirms funding source is consistent with self-attested data * Verifies funding amounts meet minimum requirements (if applicable) * Checks document recency against validity period 3. **Fraud Detection** (optional) * Analyzes documents for signs of tampering or manipulation * Identifies inconsistencies or suspicious elements * Flags potential document fraud indicators ## When to Use Use this check when you need to: * Verify the legitimacy of a business's declared funding sources * Validate the authenticity of funding documentation * Confirm funding amounts meet required thresholds * Ensure business name consistency across documentation * Detect potentially fraudulent or tampered documents ## Required Data To run this check, you need to provide: 1. **Source of Funds Documents** * Bank statements * Investment documents * Fundraising announcements * Loan agreements * Other financial documents demonstrating funding sources 2. **Self-Attested Information** * Business name * Declared source of funds 3. **External Validation Data** * Minimum amount to verify (optional) * Must be included in the `external_validation_data.source_of_funds` field * Type: `SourceOfFundsExternalData` * Example: `{ "minimum_amount_to_verify": { "currency": "USD", "amount": 1000 } }` ## Example KYB Schema Here's an example of how to structure your request with the required data: ```json theme={null} { "id": "business_123", "self_attested_data": { "business_name": "Example Corp", "source_of_funds": ["Investment", "Revenue"], "source_of_funds_documents": [ { "url": "https://storage.example.com/funding_doc.pdf", "file_name": "series_a_funding.pdf", "source_type": "file_url", "description": "Series A funding documentation" } ] }, "external_validation_data": { "source_of_funds": { "minimum_amount_to_verify": { "currency": "USD", "amount": 5000000.00 } } } } ``` ## Valid Document Types The following document types are supported for source of funds verification: 1. **Bank Statement** * A document showing the financial transactions and balances of a bank account * Examples: Checking account statement, Savings account statement 2. **Tax Return** * An annual statement filed with tax authorities reporting income, expenses, and other tax-related information * Examples: Form 1040 (U.S. Individual Income Tax Return), W-2 (Wage and Tax Statement) 3. **Funds Transfer Confirmation** * A document confirming the details of a funds transfer between financial accounts * Examples: Wire transfer confirmation, ACH transfer receipt 4. **Fundraising Document** * A document detailing an investment made as part of a fundraising round for a company * Examples: Series A funding agreement, Convertible note purchase agreement 5. **Investment Document** * A document confirming an individual's investment in a financial vehicle like stocks, bonds, or funds * Examples: Stock purchase agreement, Real estate investment contract, Mutual fund statement, Brokerage account statement 6. **Loan Agreement** * A contract detailing the terms of a loan between a lender and borrower * Examples: Personal loan agreement, Mortgage loan documents 7. **Invoice** * A document detailing a transaction between a buyer and seller * Examples: Vendor invoice, Client bill 8. **Fundraising Announcement** * A public announcement detailing a company's successful fundraising round * Examples: Press release, SEC Form D filing, Crunchbase funding round announcement 9. **Capitalization Table** * A table showing the equity ownership breakdown of a company's shareholders * Examples: Cap table spreadsheet, Equity ownership summary 10. **Other** * Any other document that provides a detailed explanation of a business's source of funds * Examples: Notarized affidavit, Certified letter from accountant or attorney Note: Screenshots of financial documents are not accepted as valid source of funds documentation. ## Request Schema ```json theme={null} { "id": "business_123", "self_attested_data": { "business_name": "Example Corp", "source_of_funds": ["Investment", "Revenue"], "source_of_funds_documents": [ { "url": "https://storage.example.com/funding_doc.pdf", "file_name": "series_a_funding.pdf", "source_type": "file_url", "description": "Series A funding documentation" } ] }, "external_validation_data": { "source_of_funds": { "minimum_amount_to_verify": { "currency": "USD", "amount": 5000000.00 } } } } ``` ## Configuration Options The check can be configured with the following parameters: 1. **Validity Period** * Number of days a document is considered valid from its issue date * Default: 365 days 2. **Minimum Amount Verification** * Whether to enforce minimum funding amount requirements * Default: false 3. **Fraud Detection** * Whether to enable document fraud detection * Default: false ## Response Interpretation The check response includes: 1. **Valid Documents** * Documents that passed all verification checks * Extracted information from each valid document 2. **Invalid Documents** * Documents that failed one or more verification checks * Reasons for failure and missing information 3. **Verified Information** * Confirmed business name * Verified source of funds * Verified funding amount * Document date 4. **Overall Result** * Whether the check passed or failed * Detailed explanation of verification results * Any alerts or issues detected ## Common Alerts The check may generate the following alerts: 1. **Invalid Document** * Document is not a valid source of funds document * Missing critical information or improper format 2. **Missing Information** * Document is missing required fields * Specific missing elements are identified 3. **Tampered Document** * Document shows signs of manipulation or tampering * Specific fraud indicators detected 4. **Information Mismatch** * Document information does not match self-attested data * Discrepancies between document and declared information 5. **Validity Period Expired** * Document is outside the configured validity period * Document is too old to be considered valid 6. **Minimum Amount Not Met** * Funding amount is less than the required minimum * Specific shortfall is identified ## Example Request ```json theme={null} { "id": "business_123", "self_attested_data": { "business_name": "Example Corp", "source_of_funds": ["Investment", "Revenue"], "source_of_funds_documents": [ { "url": "https://storage.example.com/funding_doc.pdf", "file_name": "series_a_funding.pdf", "source_type": "file_url", "description": "Series A funding documentation" } ] }, "external_validation_data": { "source_of_funds": { "minimum_amount_to_verify": { "currency": "USD", "amount": 5000000.00 } } } } ``` ## Example Response ```json theme={null} { "passed": true, "explanation": "The source of funds document verification was successful. The document shows Series A venture capital funding of $5,000,000 for Parcha Labs, Inc., which matches the self-attested source of funds and exceeds the minimum amount requirement.", "payload": { "type": "KYBSourceOfFundsDocumentVerificationResult", "valid_documents": [ { "extraction_data": { "is_valid_document": true, "analysis": "This is a valid fundraising announcement showing the business's source of funds.", "summary": "Series A funding announcement for Parcha Labs, Inc.", "date": "2024-02-01", "business_name": "Parcha Labs, Inc.", "document_type": "fundraising_announcement", "source_of_funds": "Series A venture capital funding", "amount": 5000000.00 }, "document": { "url": "https://storage.googleapis.com/example-bucket/funding_document.pdf", "file_name": "series_a_funding.pdf", "source_type": "file_url", "description": "Series A funding documentation" } } ], "invalid_documents": [], "verified_business_name": "Parcha Labs, Inc.", "verified_source_of_funds": "Series A venture capital funding", "verified_amount": 5000000.00, "verified_date": "2024-02-01" } } ``` # Web Presence Check Source: https://docs.parcha.ai/checks/web-presence-check Learn how to run web presence checks to verify a business's online presence and digital footprint The Web Presence check helps verify a business's legitimacy by analyzing its online presence, including official websites, social media profiles, and digital footprint. This guide explains how to run the check, what data to provide, and how to interpret the results. ## Overview The check analyzes various aspects of a business's web presence: * Official website verification * Domain registration and history * Social media presence * Business directory listings * Online activity patterns ## Running the Check ### API Endpoint ```bash theme={null} POST https://api.parcha.ai/api/v1/startKYBAgentJob ``` ### Request Parameters **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. Use `"kyb.web_presence_check"` for web presence verification. The business information for verification. A unique identifier for this check case. The legal name of the business to verify. The official website URL of the business. A description of the business's activities. The country code where the business is located (ISO 3166-1 alpha-2). The state or region where the business is located. The city where the business is located. The business's contact email address. The business's contact phone number. ### Example Request ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "check_id": "kyb.web_presence_check", "payload": { "id": "web-presence-check-001", "self_attested_data": { "business_name": "Parcha Labs Inc", "website": "https://parcha.ai", "business_description": "Business verification and compliance platform", "address": { "country_code": "US", "state": "CA", "city": "San Francisco" }, "contact_email_address": "support@parcha.ai", "contact_phone_number": "+1 (555) 123-4567" } } }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'agent_key': 'your-kyb-agent-key', # Replace with your actual agent key 'check_id': 'kyb.web_presence_check', 'payload': { 'id': 'web-presence-check-001', 'self_attested_data': { 'business_name': 'Parcha Labs Inc', 'website': 'https://parcha.ai', 'business_description': 'Business verification and compliance platform', 'address': { 'country_code': 'US', 'state': 'CA', 'city': 'San Francisco' }, 'contact_email_address': 'support@parcha.ai', 'contact_phone_number': '+1 (555) 123-4567' } } } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'; const data = { agent_key: 'your-kyb-agent-key', // Replace with your actual agent key check_id: 'kyb.web_presence_check', payload: { id: 'web-presence-check-001', self_attested_data: { business_name: 'Parcha Labs Inc', website: 'https://parcha.ai', business_description: 'Business verification and compliance platform', address: { country_code: 'US', state: 'CA', city: 'San Francisco' }, contact_email_address: 'support@parcha.ai', contact_phone_number: '+1 (555) 123-4567' } } }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Initial Response ```json theme={null} { "id": "job-abc123", "status": "PENDING", "created_at": "2024-02-15T10:30:00Z", "updated_at": "2024-02-15T10:30:00Z", "agent_id": "your-agent-key", "input_payload": { // Original request payload } } ``` ## Retrieving Check Results Once the job is complete, retrieve the results using the job ID with the `getJobByID` endpoint. Make sure to include the `include_check_results=true` parameter to get the full check results. ```bash theme={null} GET https://api.parcha.ai/api/v1/getJobByID?job_id=job-abc123&include_check_results=true ``` ## Check Process The web presence check follows these steps: 1. **Website Verification** * Validates domain ownership and registration * Analyzes website content and structure * Verifies business information consistency 2. **Digital Footprint Analysis** * Evaluates presence on business directories * Assesses social media profiles * Reviews online engagement and activity 3. **Risk Assessment** * Checks for domain registration issues * Identifies website content concerns * Evaluates information consistency * Assesses online presence legitimacy ## Check Results Once the check is complete, you can retrieve the results using the check ID. The results will include: ### Response Structure ```typescript theme={null} { type: "WebPresenceCheckResult"; passed: boolean; official_website_match: OfficialWebsiteMatch | null; other_webpages_matches: Array | null; } type OfficialWebsiteMatch = { url: string; title: string; visual_summary: string; screenshot_url?: string; domain_registration?: { registration_date: string; expiration_date: string; registrar: string; }; content_analysis?: { last_updated: string; business_info_present: boolean; contact_info_present: boolean; }; } ``` # null Source: https://docs.parcha.ai/concepts/anatomy-of-a-parcha-agent Welcome to the exciting world of Parcha agents! In this guide, we'll walk you through creating your first agent and watch it come to life. Buckle up, because you're about to supercharge your KYB process! ## The Anatomy of an Agent 🧠 Let's start by looking at a sample agent configuration. This is where the magic begins: ```toml theme={null} agent_key = "your-unique-agent-key" # This is your unique agent identifier created_at = "2024-08-01" agent_name = "My Business Due Diligence Agent" agent_type = "kyb" agent_description = "This agent is responsible for performing BDD tasks." [[steps]] step_name="Web Presence Check" command_type="tool" instructions="Verify if the business has a website." command_id="kyb.web_presence_check" data_loader_id="kyb.web_presence_data_loader" [[steps]] step_name="Adverse Media Check" command_type="tool" instructions='''Verify that the individual doesn't have any adverse media related to the following: * Fraud * Bribery * Illegal Activities * Terrorism * Crime * Counterfeit * Corruption * Political Involvement * Financing * Tax Evasion * Mining * Money Laundering * Human Smuggling * Human Trafficking * Interpol * OFAC ''' command_id="kyb.screening.adverse_media_tool" data_loader_id="kyb.adverse_media_webcheck" [steps.data_loader_args] prerequisite_loader_id = "kyb.web_presence_data_loader" [[steps]] step_name="High Risk Country Check" command_type="tool" instructions="Verify that the customer does not operate in prohibited / high risk countries." command_id="kyb.high_risk_country_tool" data_loader_id = "kyb.countries_data_loader" [[steps]] step_name="High Risk Industry Check" command_type="tool" instructions="Verify that the customer does not operate in prohibited / high risk industries." command_id="kyb.high_risk_industry_tool_v2" data_loader_id = "kyb.industries_data_loader" ``` This configuration defines the agent's identity, purpose, and the steps it will take to perform its due diligence tasks. It's like giving your agent a brain and a to-do list all at once! ## The Journey of Your Agent 🌟 Now, let's visualize what happens when you trigger the `/startKYBAgentJob` endpoint. Brace yourself for an epic adventure! ```mermaid theme={null} flowchart TD A[Start] --> B{Schema & Agent Validation} B -->|Valid| C[Queue Job in Async AI Engine] B -->|Invalid| Z[Return Error] C --> D[Run Data Loaders] D --> E[Run Checks in Parallel] E --> F[Generate Final Assessment] F --> G{Webhook Provided?} G -->|Yes| H[Trigger Webhook with Job Object] G -->|No| I[End] H --> I Z --> I ``` Here's what's happening behind the scenes: 1. **Validation Checkpoint**: The schema and agents undergo a validation process. If any issues are detected, an error message is returned. 2. **Job Queuing**: Upon successful validation, the job is queued in the asynchronous AI engine. 3. **Data Loaders Execution**: The data loaders are executed to gather necessary information. 4. **Parallel Checks Execution**: Checks are run in parallel to ensure efficiency. 5. **Final Assessment Generation**: A final assessment is generated based on the results of the checks. 6. **Webhook Notification**: If a webhook is provided, it is triggered with the job object to notify the user of the job completion. ## Bringing Your Agent to Life 🎭 To set your agent in motion, you'll use the `/startKYBAgentJob` endpoint. This is where the rubber meets the road, and your agent springs into action! Stay tuned for our next section, where we'll dive deep into the `/startKYBAgentJob` endpoint and all its powerful fields. You'll learn how to communicate with your agent and set it on its mission to revolutionize your KYB process. Remember, with Parcha agents, you're not just doing due diligence – you're embarking on an AI-powered adventure in compliance and risk management! 🚀🔍💼 # null Source: https://docs.parcha.ai/concepts/case-schema Welcome to the Parcha Case Schema Documentation. This guide is designed to help you understand and effectively use Parcha's API for case management in financial and regulatory compliance contexts. Parcha's case management system is built on three main schemas, each tailored to handle different types of entities: 1. Business Schema (KYB - Know Your Business) 2. Individual Schema (KYC - Know Your Customer) 3. Associated Entity Schema (AE) These schemas are designed to be flexible and adaptable to various use cases, from comprehensive due diligence to simpler categorization tasks. While our schemas support a wide range of fields to accommodate complex scenarios, many fields are optional. This allows you to provide only the information relevant to your specific use case. ## Schema Details For detailed information about each schema, please refer to the following resources: Learn about the fields and structure of the Business Schema used for Know Your Business (KYB) processes. Explore the Individual Schema used for Know Your Customer (KYC) processes and understand its components. Understand how to structure information about entities associated with the main business or individual. ## Example Use Cases Below are examples of how these schemas can be used in different scenarios: ### Simple Example: Industry Categorization For simpler use cases, such as industry categorization, you might only need to provide minimal information. Here's an example of how a request for industry categorization might look: ```json theme={null} { "id": "example-industry-cat-1", "self_attested_data": { "website": "https://example.com" } } ``` In this case, we're only providing the case ID and the business website, which is often sufficient for basic industry categorization tasks. ### Simple KYC Example: Adverse Media Check For individual-focused tasks like adverse media checks, you might need just a few key pieces of information about an individual. Here's an example of a simple KYC case for an adverse media check: ```json theme={null} { "id": "example-kyc-adverse-media-1", "associated_individuals": [ { "id": "individual-1", "self_attested_data": { "first_name": "John", "last_name": "Doe", "date_of_birth": "YYYY-MM-DD", "country_of_residence": "US" } } ] } ``` This example provides just enough information to perform an adverse media check on an individual: their name, date of birth, and country of residence. ### Comprehensive Example For more complex use cases, such as full KYB/KYC processes, you might need to provide more detailed information. Below is an example of a more comprehensive case schema: ```json theme={null} { "id": "example-agent-group-test", "self_attested_data": { "business_name": "Example Corp", "registered_business_name": "Example Corporation Inc.", "address_of_operation": { "street_1": "123 Main St", "street_2": "Suite 100", "city": "Anytown", "state": "ST", "country_code": "US", "postal_code": "12345" }, "address_of_incorporation": { "street_1": "456 Business Ave", "city": "Corporateville", "state": "ST", "country_code": "US", "postal_code": "67890" }, "website": "https://example.com", "business_purpose": "B2B Software as a Service", "description": "AI-powered software solutions for business automation.", "industry": "Technology", "tin_number": "XX-XXXXXXX", "incorporation_date": "YYYY-MM-DD", "partners": [ "Partner Ventures" ], "customers": [ "Customer Inc" ], "source_of_funds": [ "Investment", "Revenue" ] }, "associated_individuals": [ { "id": "example-kyc-test-1", "self_attested_data": { "first_name": "John", "middle_name": "Michael", "last_name": "Doe", "date_of_birth": "YYYY-MM-DD", "address": { "street_1": "789 Residential St", "city": "Hometown", "state": "ST", "country_code": "US", "postal_code": "54321" }, "country_of_nationality": "US", "country_of_residence": "US", "place_of_birth": "Birthtown, State", "sex": "Male", "email": "john@example.com", "phone": "+1234567890", "title": "CEO", "is_applicant": true, "is_business_owner": true, "business_ownership_percentage": 50 } }, { "id": "example-kyc-test-2", "self_attested_data": { "first_name": "Jane", "middle_name": "Elizabeth", "last_name": "Smith", "date_of_birth": "YYYY-MM-DD", "address": { "street_1": "101 Home Ave", "city": "Villagetown", "state": "ST", "country_code": "US", "postal_code": "98765" }, "country_of_nationality": "US", "country_of_residence": "US", "place_of_birth": "Origintown, State", "sex": "Female", "email": "jane@example.com", "phone": "+0987654321", "title": "Chief Technology Officer", "is_applicant": false, "is_business_owner": true, "business_ownership_percentage": 50 } } ], "associated_entities": [ { "id": "example-ubo-test-1", "self_attested_data": { "business_name": "Partner Ventures", "is_trust": false, "address": { "street_1": "202 Investor Blvd", "street_2": "Floor 10", "city": "Metropolis", "state": "ST", "country_code": "US", "postal_code": "13579" }, "industry": "Venture Capital", "tin_number": null, "business_ownership_percentage": 10, "country_code": "US", "website": "www.partnerventures.com", "description": "Partner Ventures is a venture capital firm based in Metropolis, State. The firm invests in various technology-based sectors including artificial intelligence, blockchain, and software as a service." } } ] } ``` This comprehensive example showcases how you can provide detailed information about a business, its associated individuals, and related entities when needed for more complex compliance and due diligence processes. ## Next Steps Now that you understand the structure of our case schemas, explore these resources to make the most of the Parcha API: Learn about the components and structure of a Parcha Agent. Dive into our comprehensive API documentation to understand all available endpoints and features. Explore example KYB and KYC workflows to see how Parcha can enhance your compliance processes. # How to Run a KYB Agent Source: https://docs.parcha.ai/how-to-run-kyb-agent Learn how to run a Know Your Business (KYB) agent with step-by-step instructions 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 for authentication. See [Authentication](/authentication) for how to generate one. 2. **Agent Key**: Your KYB agent key from the Parcha dashboard. This is unique to your organization and agent configuration. **Important**: You must use your own agent key, not a default or public agent key. Your agent key can be found in the Parcha dashboard under your agent's settings, or in the "Test API Integration" dialog. 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 ```mermaid theme={null} sequenceDiagram participant Client participant API participant KYB Agent participant Check Services Client->>API: 1. Start KYB Agent Job API->>KYB Agent: 2. Initialize Job KYB Agent->>API: 3. Return Job ID Note over KYB Agent: 4. Run Required Checks loop For each check KYB Agent->>Check Services: 5. Run Check Check Services-->>KYB Agent: 6. Check Results KYB Agent->>API: 7. Update Job Status end KYB Agent->>API: 8. Mark Job Complete API-->>Client: 9. Job Complete ``` ## Step-by-Step Guide ### 1. Prepare the Business Schema First, prepare your business schema following the [Business Schema documentation](/schemas/business-schema). 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](/schemas/business-schema#check-requirements) table for details. ### 2. Start the KYB Agent Job Use the `/startKYBAgentJob` endpoint to start a new KYB job: ```bash theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "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: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/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: ```bash theme={null} curl -X GET 'https://api.parcha.ai/api/v1/getJobsByCaseId?case_id=YOUR_CASE_ID&agent_key=your-kyb-agent-key&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: ```python theme={null} import requests import time def run_kyb_workflow(api_key, agent_key, business_schema): # 1. Start KYB Job response = requests.post( 'https://api.parcha.ai/api/v1/startKYBAgentJob', headers={'Authorization': f'Bearer {api_key}'}, json={ 'agent_key': agent_key, # Use your own agent key from the Parcha dashboard '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/api/v1/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 ``` View the complete API documentation for all endpoints and features. # Getting Started Source: https://docs.parcha.ai/introduction How to get started using the Parcha API Hero Light Hero Dark ## Introduction Parcha's API makes it easy to integrate your existing onboarding workflows with our AI compliance review system. Our API supports the ability to send a full KYB or KYC review or just run a single check. We offer flexibility between using our integrations and data sources for verifying customers or applying our intelligence to your own data integrations. ## Key Features Send complete Know Your Business or Know Your Customer reviews through our API Run individual compliance checks as needed Use our data sources or apply our AI to your existing integrations Leverage our intelligent system for accurate and efficient reviews ## Getting Started To begin using the Parcha API, follow these steps: 1. Sign up for a Parcha account 2. Obtain your API credentials 3. Choose your integration method 4. Start sending requests to our API endpoints For detailed instructions and API reference, explore the following sections of our documentation. # Quickstart Source: https://docs.parcha.ai/quickstart Start using the Parcha API in under 5 minutes ## Get Started with Parcha API Follow these simple steps to begin integrating Parcha's AI-powered compliance review system into your workflows. To start using the Parcha API, you first need to become a tenant. * Contact your Parcha representative, or * Email [founders@parcha.ai](mailto:founders@parcha.ai) to request access to the platform. Once your request is processed, you'll receive a welcome email with further instructions. After receiving your welcome email: 1. Log in to the Parcha web portal (URL provided in the welcome email) 2. Navigate to the API Keys section 3. Click on "Create New API Key" 4. Name your key and set any necessary permissions 5. Copy and securely store your new API key Keep your API key confidential. Do not share it or expose it in client-side code. With your API key in hand, you're all set to initiate your first Parcha KYB (Know Your Business) or KYC (Know Your Customer) workflow. Check out our [API Reference](/api-reference) for detailed information on available endpoints and how to structure your requests. ## Next Steps Now that you're set up, explore these resources to make the most of the Parcha API: Understand the input schema and details about each field that you need to provide for a case. Create your first agent and enhance your KYB process. Dive into our comprehensive API documentation to understand all available endpoints and features. Explore example KYB and KYC workflows to see how Parcha can enhance your compliance processes. # Business Schema Source: https://docs.parcha.ai/schemas/business-schema The Business Schema contains information about a business entity. It is used for Know Your Business (KYB) processes in Parcha's case management system. The Business Schema contains information about a business entity. It is used for Know Your Business (KYB) processes in Parcha's case management system. This schema is crucial for maintaining accurate and comprehensive business records in our system. ## How to Prepare Your Schema Follow these steps to prepare your business schema based on the checks you want to run: ### Step 1: Identify Required Schema Fields for Checks First, determine which checks you need to run. Common check types include. The following sections detail which attributes are required (✓) for each check: Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `website` or `address_of_operation` (city, state, country) or `address_of_incorporation` (city, state, country) Optional attributes: * ✓ `description` * ✓ `industry` * ✓ `address_of_operation` * ✓ `address_of_incorporation` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `address_of_incorporation` and/or `address_of_operation` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `website` Optional attributes: * ✓ `description` * ✓ `industry` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `website` and/or `address_of_incorporation` and/or `address_of_operation` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `address_of_operation` and/or `address_of_incorporation` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `website` and/or `address_of_operation` and/or `address_of_incorporation` Optional attributes: * ✓ `business_purpose` * ✓ `industry` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `business_ownership_documents` * ✓ `associated_entities` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `incorporation_documents` Optional attributes: * ✓ `incorporation_date` * ✓ `business_registration_number` * ✓ `address_of_incorporation` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `proof_of_address_documents` * ✓ `address_of_operation` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `tin_number` * ✓ `ein_documents` Required attributes: * ✓ `business_name` and/or `registered_business_name` * ✓ `source_of_funds_documents` * ✓ `external_validation_data.source_of_funds` While some attributes are marked as optional, providing them can improve the accuracy and comprehensiveness of the check results. ### Step 2: Gather Required Information For each required field: 1. **Basic Information** * Business name (max 64 characters) * Website URL (if available) * Business description (max 512 characters) * Industry classification * Tax ID number (if required) 2. **Address Information** * Operating address * Incorporation address (if different) * Include all required address fields (street, city, state, postal code, country) 3. **Documents** * Prepare URLs for required documents * Ensure documents are accessible * Use proper file names and source types 4. **Associated Data** * List of partners and customers * Source of funds information * Associated individuals and entities ### Step 3: Validate Your Data Before submitting: 1. **Check Field Requirements** * Verify all required fields are present * Ensure field lengths are within limits * Validate URL formats * Check date formats (YYYY-MM-DD) 2. **Document Accessibility** * Test all document URLs * Verify document permissions * Check file formats 3. **Data Completeness** * Review the [Check Requirements](#check-requirements) table * Ensure all required fields for your checks are included * Consider adding optional fields for better results #### Validation Rules * `business_name` is required and is truncated to 64 characters if longer * `description` is truncated to 512 characters if longer * If `website` is provided, it must be a valid URL * `incorporation_date` must be in YYYY-MM-DD format if provided #### Validation Process When submitting data for the Business Schema, the system performs several validation checks: 1. Required fields are checked for presence 2. Field formats are validated (e.g., date formats, URL formats) 3. Field lengths are checked and truncated if necessary 4. Associated individuals and entities are processed and validated If any validation errors occur, the system will return a `SchemaValidationError` with details about the specific fields that failed validation. ### Step 4: Structure Your Schema Follow this template structure: ```json theme={null} { "id": "your-case-id", "self_attested_data": { // Required fields based on your checks "business_name": "Your Business Name", "website": "https://your-website.com", // ... other fields } } ``` While some fields are optional, providing them can improve the accuracy and comprehensiveness of the check results. * All URLs must be accessible * Document URLs must be direct download links * Dates must be in YYYY-MM-DD format * Country codes must be ISO 3166-1 alpha-2 format ### Step 5: Use the Schema in API Calls When using this schema in API calls: 1. Ensure all required fields are provided 2. Follow the specified formats for dates, URLs, and other structured data 3. Be prepared to handle validation errors and adjust your data accordingly Dive into our comprehensive API documentation to understand all available endpoints and features. # null Source: https://docs.parcha.ai/schemas/individual-schema The Individual Schema contains information about a person. It is used for Know Your Customer (KYC) processes in Parcha's case management system. ## Example ```json Example theme={null} { "id": "parcha-kyc-test-2", "self_attested_data": { "first_name": "John", "middle_name": "Michael", "last_name": "Doe", "date_of_birth": "YYYY-MM-DD", "address": { "street_1": "123 Main Street", "city": "Anytown", "state": "ST", "country_code": "US", "postal_code": "12345" }, "associated_addresses": [ { "street_1": "456 Secondary Street", "city": "Othertown", "state": "ST", "country_code": "US", "postal_code": "67890" } ], "country_of_nationality": "US", "country_of_residence": "US", "place_of_birth": "Anytown, State", "sex": "Male", "email": "email@example.com", "phone": "+1234567890", "title": "Chief Technology Officer", "is_applicant": false, "is_business_owner": true, "business_ownership_percentage": 50 } } ``` ## Field Descriptions ### Case ID Unique identifier for the case. Used to tie cases together when running workflows and can be used to link back to internal case management systems. ### Self Attested Data The first name of the individual The middle name of the individual The last name of the individual The date of birth of the individual, format YYYY-MM-DD The address of the individual The associated addresses of the individual The country of nationality of the individual The country of residence of the individual The place of birth of the individual The sex of the individual The email of the individual The phone number of the individual The title of the individual Whether the individual is an applicant Whether the individual is a business owner The percentage of ownership of the individual The description of the source of funds for the individual ### Document Fields The following fields are lists of `Document` objects: * proof\_of\_address\_documents * source\_of\_funds\_documents ## Address Object Primary street address Secondary street address City name State or province Postal or ZIP code Two-letter country code ## Document Object Type of the document Name of the document file URL to access the document ## Validation Rules * `first_name` and `last_name` are required fields. * `date_of_birth`, if provided, must be in the format YYYY-MM-DD. * `email`, if provided, must be a valid email address format. * `business_ownership_percentage`, if provided, must be a number between 0 and 100. ## Validation Process When submitting data for the Individual Schema, the system performs several validation checks: 1. Required fields are checked for presence. 2. Field formats are validated (e.g., date formats, email formats). 3. Field values are checked for validity (e.g., ownership percentage range). 4. Associated documents are processed and validated. If any validation errors occur, the system will return a `SchemaValidationError` with details about the specific fields that failed validation. ## Usage in API When using this schema in API calls: 1. Ensure all required fields are provided. 2. Follow the specified formats for dates, email addresses, and other structured data. 3. Be prepared to handle validation errors and adjust your data accordingly. Dive into our comprehensive API documentation to understand all available endpoints and features. # null Source: https://docs.parcha.ai/use-cases/AML-screening ## 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 ```typescript theme={null} 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 ```typescript theme={null} { "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) ```typescript:KYCSelfAttestedData theme={null} { // 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) ```typescript:KYBSelfAttestedData theme={null} { // 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 ```typescript:PEPVendorData theme={null} { "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 ```typescript:VendorAdverseMediaEventData theme={null} { "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 ```typescript:SanctionsData theme={null} { "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 ```typescript theme={null} { "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 ```typescript theme={null} { "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 ```typescript theme={null} { "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 ```typescript theme={null} { "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 ``` 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: 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 API key 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: * Technical Documentation: [docs.parcha.ai](https://docs.parcha.ai) * API Status: [status.parcha.ai](https://status.parcha.ai) * Email Support: [support@parcha.ai](mailto:support@parcha.ai) # Document Verification Source: https://docs.parcha.ai/use-cases/document-verification Complete guide to document verification with Parcha API This guide covers how to verify business documents using the Parcha API. We'll use **incorporation document verification** as our canonical example to demonstrate the three main approaches. ## Choosing the Right Approach Parcha offers three ways to verify documents, each optimized for different use cases: ```mermaid theme={null} flowchart TD Start{Document Verification Need} --> Q1{Part of a full
KYB/KYC review?} Q1 -->|Yes| Agent[1. Full Agent Job
startKYBAgentJob] Q1 -->|No| Q2{Quick type check
or thorough verification?} Q2 -->|Quick check| PreVal[2. Prevalidation
runCheck with flags disabled] Q2 -->|Thorough| FullVal[3. Full Verification
runCheck with flags enabled] style Start fill:#5D5FEF,stroke:#333,stroke-width:2px,color:#fff style Agent fill:#10b981,stroke:#333,stroke-width:2px,color:#fff style PreVal fill:#f59e0b,stroke:#333,stroke-width:2px,color:#fff style FullVal fill:#6366f1,stroke:#333,stroke-width:2px,color:#fff ``` ### Quick Comparison | Approach | Endpoint | Speed | Use Case | | ------------------------ | ------------------ | -------- | ------------------------------------------------------------------------------ | | **1. Full Agent Job** | `startKYBAgentJob` | Varies | Document verification as part of comprehensive KYB review with multiple checks | | **2. Prevalidation** | `runCheck` | Fast | Quick document type validation before full review | | **3. Full Verification** | `runCheck` | Thorough | Complete verification with visual analysis and fraud detection | *** ## Incorporation Document Example We'll demonstrate all three approaches using incorporation document verification. The same patterns apply to other document types (proof of address, EIN documents, etc.). ### Sample Business Data ```python theme={null} business_data = { "registered_business_name": "Example Business Inc.", "incorporation_date": "2023-01-01", "address_of_incorporation": { "street_1": "123 Main St", "city": "Wilmington", "state": "DE", "country_code": "US", "postal_code": "19801" } } ``` *** ## Approach 1: Full Agent Job Use Agent Jobs when you need to run **multiple checks** together as part of a unified compliance workflow with custom pass/fail criteria. **When to use:** * Running a full KYB review with multiple checks (web presence + sanctions + document verification) * You have an agent configured with specific pass/fail logic * You need unified case view and risk scoring across all checks **How it works:** ```mermaid theme={null} sequenceDiagram participant Client participant API participant Agent participant Checks Client->>API: POST /startKYBAgentJob API-->>Client: job_id (immediate) Agent->>Checks: Web Presence Check Agent->>Checks: Sanctions Screening Agent->>Checks: Incorporation Doc Verification Checks-->>Agent: Results Agent->>Agent: Apply pass/fail logic Agent-->>Client: Webhook notification ``` ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_key": "your-kyb-agent-key", "kyb_schema": { "id": "case-001", "self_attested_data": { "registered_business_name": "Example Business Inc.", "website": "https://example.com", "incorporation_date": "2023-01-01", "address_of_incorporation": { "street_1": "123 Main St", "city": "Wilmington", "state": "DE", "country_code": "US", "postal_code": "19801" }, "incorporation_documents": [ { "file_name": "certificate_of_incorporation.pdf", "b64_document": "BASE64_ENCODED_DOCUMENT" } ] } }, "webhook_url": "https://your-webhook.com/callback" }' ``` ```python Python theme={null} import requests import base64 api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/startKYBAgentJob' with open('certificate_of_incorporation.pdf', 'rb') as file: b64_document = base64.b64encode(file.read()).decode('utf-8') data = { "agent_key": "your-kyb-agent-key", "kyb_schema": { "id": "case-001", "self_attested_data": { "registered_business_name": "Example Business Inc.", "website": "https://example.com", "incorporation_date": "2023-01-01", "address_of_incorporation": { "street_1": "123 Main St", "city": "Wilmington", "state": "DE", "country_code": "US", "postal_code": "19801" }, "incorporation_documents": [ { "file_name": "certificate_of_incorporation.pdf", "b64_document": b64_document } ] } }, "webhook_url": "https://your-webhook.com/callback" } response = requests.post(url, json=data, headers={ 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' }) job_id = response.json()['job_id'] print(f"Agent job started: {job_id}") ``` **Agent configuration matters:** Your agent key determines which checks run and the pass/fail criteria. Work with Parcha to configure agents that match your compliance policies. *** ## Approach 2: Prevalidation (Quick Check) Use Prevalidation for **fast document type checking** without running full verification. Perfect for inline validation during user uploads. **When to use:** * Real-time document upload flows where users expect quick feedback * Pre-screening documents before committing to full verification * Validating document type before user submits their application **How it works:** ```mermaid theme={null} sequenceDiagram participant User participant App participant API participant Check User->>App: Upload document App->>API: POST /runCheck (flags disabled + webhook_url) API-->>App: job_id API->>Check: Quick type validation only Note over Check: Skip visual verification
Skip fraud check
Skip field verification Check-->>API: Is valid document type? API-->>App: Webhook: {is_valid_document: true/false} App-->>User: Show quick feedback ``` Set all verification flags to `false` to skip visual verification and fraud checks. The system will only validate that the document is a valid type. Use a webhook to receive the result quickly. ```bash cURL theme={null} curl -X POST 'https://api.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.incorporation_document_verification", "kyb_schema": { "id": "case-001", "self_attested_data": { "registered_business_name": "Example Business Inc.", "incorporation_date": "2023-01-01", "incorporation_documents": [ { "file_name": "certificate_of_incorporation.pdf", "b64_document": "BASE64_ENCODED_DOCUMENT" } ] } }, "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 }, "webhook_url": "https://your-webhook.com/prevalidation-callback" }' ``` ```python Python theme={null} import requests import base64 api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/runCheck' with open('certificate_of_incorporation.pdf', 'rb') as file: b64_document = base64.b64encode(file.read()).decode('utf-8') # Prevalidation mode - all verification flags disabled data = { "agent_key": "your-agent-key", "check_id": "kyb.incorporation_document_verification", "kyb_schema": { "id": "case-001", "self_attested_data": { "registered_business_name": "Example Business Inc.", "incorporation_date": "2023-01-01", "incorporation_documents": [ { "file_name": "certificate_of_incorporation.pdf", "b64_document": b64_document } ] } }, "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 }, "webhook_url": "https://your-webhook.com/prevalidation-callback" } response = requests.post(url, json=data, headers={ 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' }) job_id = response.json()['id'] print(f"Prevalidation job started: {job_id}") ``` **Webhook or Poll?** Provide a `webhook_url` (recommended) to receive results automatically as soon as prevalidation completes, or poll the `/getJobById` endpoint if webhooks aren't feasible for your setup. *** ## Approach 3: Full Verification Use Full Verification for **complete document analysis** including visual verification, fraud detection, and data extraction. **When to use:** * Final verification before approving a business application * When you need visual element analysis (seals, signatures) * When fraud detection is required * When you need to verify specific data fields (dates, addresses) **How it works:** ```mermaid theme={null} sequenceDiagram participant App participant API participant Check participant Vision participant Fraud App->>API: POST /runCheck (flags enabled) API-->>App: job_id API->>Check: Start verification Check->>Check: OCR & text extraction Check->>Vision: Visual verification Note over Vision: Analyze seals, signatures
Check visual authenticity Vision-->>Check: Visual result Check->>Fraud: Fraud analysis Note over Fraud: Metadata analysis
Tampering detection Fraud-->>Check: Fraud result Check->>Check: Verify fields (date, address, etc.) Check-->>API: Complete result API-->>App: Webhook or poll result ``` Enable the verification options you need. Each adds additional analysis capabilities: ```bash cURL theme={null} curl -X POST 'https://api.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.incorporation_document_verification", "kyb_schema": { "id": "case-001", "self_attested_data": { "registered_business_name": "Example Business Inc.", "incorporation_date": "2023-01-01", "address_of_incorporation": { "street_1": "123 Main St", "city": "Wilmington", "state": "DE", "country_code": "US", "postal_code": "19801" }, "incorporation_documents": [ { "file_name": "certificate_of_incorporation.pdf", "b64_document": "BASE64_ENCODED_DOCUMENT" } ] } }, "check_args": { "enable_visual_verification": true, "enable_fraud_check": true, "verify_incorporation_date": true, "verify_registration_number": true, "verify_address": true, "verify_no_high_risk_fraud": true }, "webhook_url": "https://your-webhook.com/callback" }' ``` ```python Python theme={null} import requests import base64 api_key = 'YOUR_API_KEY' url = 'https://api.parcha.ai/api/v1/runCheck' with open('certificate_of_incorporation.pdf', 'rb') as file: b64_document = base64.b64encode(file.read()).decode('utf-8') # Full verification mode - all checks enabled data = { "agent_key": "your-agent-key", "check_id": "kyb.incorporation_document_verification", "kyb_schema": { "id": "case-001", "self_attested_data": { "registered_business_name": "Example Business Inc.", "incorporation_date": "2023-01-01", "address_of_incorporation": { "street_1": "123 Main St", "city": "Wilmington", "state": "DE", "country_code": "US", "postal_code": "19801" }, "incorporation_documents": [ { "file_name": "certificate_of_incorporation.pdf", "b64_document": b64_document } ] } }, "check_args": { "enable_visual_verification": True, "enable_fraud_check": True, "verify_incorporation_date": True, "verify_registration_number": True, "verify_address": True, "verify_no_high_risk_fraud": True }, "webhook_url": "https://your-webhook.com/callback" } response = requests.post(url, json=data, headers={ 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' }) job_id = response.json()['id'] print(f"Full verification job started: {job_id}") ``` *** ## Verification Options Reference **Latency vs. Thoroughness Trade-off:** Each verification option adds scrutiny but increases processing time. Choose based on your risk tolerance and UX requirements. | Option | Default | Description | Latency Impact | | ---------------------------- | ------- | --------------------------------------------------------------- | -------------- | | `enable_visual_verification` | `true` | Uses vision model to analyze seals, signatures, visual elements | +15-30 seconds | | `enable_fraud_check` | `false` | Sophisticated fraud and tampering analysis on document metadata | +1-2 minutes | | `verify_incorporation_date` | `true` | Fail if incorporation date has significant discrepancies | Minimal | | `verify_registration_number` | `false` | Fail if registration number has significant discrepancies | Minimal | | `verify_address` | `false` | Fail if address has significant discrepancies | Minimal | | `verify_no_high_risk_fraud` | `false` | Fail if HIGH\_RISK fraud indicators detected | Minimal | By default (without explicit options), the system performs OCR-based analysis using LLMs to extract and analyze text from the document. *** ## Polling for Results After starting a job, poll for completion: ```bash cURL theme={null} curl 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```python Python theme={null} import requests import time api_key = 'YOUR_API_KEY' job_id = 'YOUR_JOB_ID' while True: response = requests.get( 'https://api.parcha.ai/api/v1/getJobById', headers={'Authorization': f'Bearer {api_key}'}, params={'job_id': job_id, 'include_check_results': 'true'} ) job_data = response.json() if job_data['status'].lower() == 'complete': check_result = job_data['check_results'][0] if check_result['passed']: print("✓ Document verified successfully") payload = check_result['payload'] print(f" Company: {payload.get('company_name')}") print(f" Incorporation Date: {payload.get('incorporation_date')}") else: print(f"✗ Verification failed: {check_result.get('answer')}") break elif job_data['status'].lower() == 'failed': print("Job failed!") break time.sleep(5) ``` *** ## Using Webhooks Instead of polling, configure a webhook to receive results automatically: ```javascript theme={null} 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 incorpCheck = jobData.check_results.find( check => check.command_id === 'kyb.incorporation_document_verification' ); if (incorpCheck) { if (incorpCheck.passed) { console.log('✓ Document verified'); console.log('Company:', incorpCheck.payload.company_name); } else { console.log('✗ Verification failed:', incorpCheck.answer); } } } res.sendStatus(200); }); app.listen(3000); ``` For more details, see the [Webhooks documentation](/api-reference/webhooks). *** ## Decision Guide **Use: Approach 1 - Full Agent Job (`startKYBAgentJob`)** Include documents in your `kyb_schema` and let the agent handle document verification alongside web presence, sanctions screening, and other checks. You get unified pass/fail logic across all verification types. **Use: Approach 2 - Prevalidation (`runCheck` with flags disabled)** Set all verification flags to `false` for fast document type validation. Show users immediate feedback on whether their document is the right type before they submit. **Use: Approach 3 - Full Verification (`runCheck` with flags enabled)** Enable `enable_visual_verification` and `enable_fraud_check` for comprehensive analysis. Use this for final verification before approving applications. **Combine Approaches 2 and 3** 1. Run prevalidation during upload for quick feedback 2. Run full verification when user submits their complete application This gives users fast feedback while ensuring thorough verification before approval. *** ## Document Upload Options When submitting documents for verification, you have two options for how to include the document data: ### Option A: Inline Base64 (Single Request) Include the base64-encoded document directly in your verification request. This is the simplest approach for most use cases. **How it works:** ```mermaid theme={null} sequenceDiagram participant App participant API App->>App: Read file & base64 encode App->>API: POST /runCheck with b64_document Note over API: Document uploaded & verification started
in single request API-->>App: job_id ``` **When to use:** * Most common approach * Documents under 10MB * When you want simplicity ```python theme={null} import base64 with open('document.pdf', 'rb') as file: b64_document = base64.b64encode(file.read()).decode('utf-8') data = { "agent_key": "your-agent-key", "check_id": "kyb.incorporation_document_verification", "kyb_schema": { "id": "case-001", "self_attested_data": { "registered_business_name": "Example Business Inc.", "incorporation_documents": [ { "file_name": "certificate.pdf", "b64_document": b64_document # Document included inline } ] } }, "check_args": {...} } ``` *** ### Option B: Pre-upload (Two-Step) Upload the document first to get a URL, then reference that URL in your verification request. Useful when you need to manage documents separately. **How it works:** ```mermaid theme={null} sequenceDiagram participant App participant API participant Storage App->>API: POST /uploadB64Document API->>Storage: Store document Storage-->>API: document_url API-->>App: document_url App->>API: POST /runCheck with file_url API-->>App: job_id ``` **When to use:** * Large documents * When you need to reuse the same document across multiple checks * When you want to manage document storage separately **Step 1: Upload the document** ```bash cURL theme={null} curl -X POST 'https://api.parcha.ai/api/v1/uploadB64Document' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "b64_document": "BASE64_ENCODED_CONTENT", "document_name": "certificate_of_incorporation.pdf" }' ``` ```python Python theme={null} import requests import base64 api_key = 'YOUR_API_KEY' with open('certificate_of_incorporation.pdf', 'rb') as file: b64_document = base64.b64encode(file.read()).decode('utf-8') response = requests.post( 'https://api.parcha.ai/api/v1/uploadB64Document', headers={ 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' }, json={ 'b64_document': b64_document, 'document_name': 'certificate_of_incorporation.pdf' } ) document_url = response.json()['url'] print(f"Document uploaded: {document_url}") ``` **Step 2: Run verification with the URL** ```python theme={null} data = { "agent_key": "your-agent-key", "check_id": "kyb.incorporation_document_verification", "kyb_schema": { "id": "case-001", "self_attested_data": { "registered_business_name": "Example Business Inc.", "incorporation_documents": [ { "file_name": "certificate_of_incorporation.pdf", "url": document_url # Reference the uploaded document } ] } }, "check_args": {...} } response = requests.post( 'https://api.parcha.ai/api/v1/runCheck', headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'}, json=data ) ``` *** ### Comparison | Option | Requests | Best For | | -------------------- | -------- | -------------------------------------------------------- | | **A: Inline Base64** | 1 | Simple integration, most use cases | | **B: Pre-upload** | 2 | Large files, document reuse, separate storage management | *** ## Other Document Types The same three approaches work for all document verification checks: | Document Type | Check ID | Document Field | | ------------------------- | ---------------------------------------------- | ------------------------------ | | Incorporation Certificate | `kyb.incorporation_document_verification` | `incorporation_documents` | | Proof of Address | `kyb.proof_of_address_verification` | `proof_of_address_documents` | | EIN Document | `kyb.ein_document_verification` | `ein_documents` | | Business Ownership | `kyb.business_ownership_document_verification` | `business_ownership_documents` | | Source of Funds | `kyb.source_of_funds_document_verification` | `source_of_funds_documents` | Simply swap the `check_id` and document field in your requests. # null Source: https://docs.parcha.ai/use-cases/merchant-code-categorization Merchant Category Code (MCC) verification is another important aspect of KYB processes. This example demonstrates how to use the Parcha API to verify a business's MCC code based on its basic information. ```mermaid theme={null} graph TD A[Start] --> B[Prepare Business Data] B --> C[Run MCC Code Verification] C --> D[Poll for Job Status] D --> E{Check Result} E -->|Complete| F[Process Results] E -->|In Progress| D F --> G[End] style A fill:#f9d71c,stroke:#333,stroke-width:2px style B fill:#91c2e8,stroke:#333,stroke-width:2px style C fill:#91c2e8,stroke:#333,stroke-width:2px style D fill:#91c2e8,stroke:#333,stroke-width:2px style E fill:#f9d71c,stroke:#333,stroke-width:2px style F fill:#91c2e8,stroke:#333,stroke-width:2px style G fill:#f9d71c,stroke:#333,stroke-width:2px ``` ### Step 1: Prepare Business Data and Run MCC Code Verification Use the `runCheck` endpoint to initiate the MCC code verification process. ```bash cURL theme={null} 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": { "business_name": "TechInnovate Solutions", "description": "Providing cutting-edge software solutions for businesses", "website": "https://techinnovatesolutions.com", "country_code": "US" } }, "check_id": "kyb.mcc_code_check_v3", "webhook_url": "https://your-webhook-url.com/callback" }' ``` ```python Python theme={null} import requests api_key = 'YOUR_API_KEY' url = 'https://demo.parcha.ai/api/v1/runCheck' data = { "agent_key": "your-agent-key", "kyb_schema": { "id": "unique-case-id", "self_attested_data": { "business_name": "TechInnovate Solutions", "description": "Providing cutting-edge software solutions for businesses", "website": "https://techinnovatesolutions.com", "country_code": "US" } }, "check_id": "kyb.mcc_code_check_v3", "webhook_url": "https://your-webhook-url.com/callback" } headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://demo.parcha.ai/api/v1/runCheck'; const data = { agent_key: "your-agent-key", kyb_schema: { id: "unique-case-id", self_attested_data: { business_name: "TechInnovate Solutions", description: "Providing cutting-edge software solutions for businesses", website: "https://techinnovatesolutions.com", country_code: "US" } }, check_id: "kyb.mcc_code_check", webhook_url: "https://your-webhook-url.com/callback" }; axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }) .then(response => console.log(response.data)) .catch(error => console.error('Error:', error)); ``` ### Step 2: Poll for Job Status (Optional if using webhook) If you're not using a webhook, you can poll for the job status using the `getJobById` endpoint. ```bash cURL theme={null} curl 'https://demo.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```python Python theme={null} import requests import time api_key = 'YOUR_API_KEY' job_id = 'YOUR_JOB_ID' url = f'https://demo.parcha.ai/api/v1/getJobById?job_id={job_id}&include_check_results=true' headers = { 'Authorization': f'Bearer {api_key}' } while True: response = requests.get(url, headers=headers) job_data = response.json() if job_data['status'] == 'complete': print("Job completed!") print(job_data) break else: print("Job still in progress. Waiting...") time.sleep(5) # Wait for 5 seconds before checking again ``` ```typescript TypeScript theme={null} import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const jobId = 'YOUR_JOB_ID'; const url = `https://demo.parcha.ai/api/v1/getJobById?job_id=${jobId}&include_check_results=true`; function pollJobStatus() { axios.get(url, { headers: { 'Authorization': `Bearer ${apiKey}` } }) .then(response => { const jobData = response.data; if (jobData.status === 'complete') { console.log("Job completed!"); console.log(jobData); } else { console.log("Job still in progress. Waiting..."); setTimeout(pollJobStatus, 5000); // Check again after 5 seconds } }) .catch(error => console.error('Error:', error)); } pollJobStatus(); ``` ### Step 3: Process the Results Once the job is completed, examine the results to retrieve the MCC code and its description. ```python Python theme={null} if job_data['status'] == 'complete': mcc_check_result = next( (result for result in job_data['check_results'] if result['command_id'] == 'kyb.mcc_code_check_v3'), None ) if mcc_check_result: payload = mcc_check_result['payload'] mcc_code = payload.get('mcc_code') mcc_title = payload.get('mcc_title') mcc_description = payload.get('mcc_code_description') print(f"MCC Code: {mcc_code}") print(f"Title: {mcc_title}") print(f"Description: {mcc_description}") else: print("MCC code check result not found.") ``` Or use JSONPath for cleaner extraction: ```python Python theme={null} from urllib.parse import quote jsonpath_query = '$.check_results[?(@.command_id=="kyb.mcc_code_check_v3")].payload' url = f'https://demo.parcha.ai/api/v1/getJobById?job_id={job_id}&include_check_results=true&jsonpath_query={quote(jsonpath_query)}' response = requests.get(url, headers=headers) mcc_payload = response.json()[0] print(f"MCC Code: {mcc_payload['mcc_code']}") print(f"Title: {mcc_payload['mcc_title']}") print(f"Description: {mcc_payload['mcc_code_description']}") ``` ### Conclusion This MCC code verification process demonstrates a straightforward use of the Parcha API: 1. It requires minimal input (basic business information). 2. It can be executed with a single API call to `runCheck`. 3. Results can be retrieved either through a webhook or by polling the job status. This approach is efficient for quick verifications that don't require document uploads or complex multi-step processes. Always ensure that the business information provided is accurate to get the most reliable MCC code verification results.