Run Check - Parcha API Documentation

This endpoint allows you to run a specific check for either Know Your Business (KYB) or Know Your Customer (KYC) processes.

API Endpoint

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

Request Body

agent_key

string

required

The unique identifier for the agent to be used for the check.

check_id

string

required

The identifier of the specific check you want to run.

job_id

string

Optional. A unique identifier (UUID) that you can provide for this check 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 check job’s status and results using an appropriate endpoint (e.g., /getJobById or a check-specific status endpoint if available). If not provided, a new unique ID will be automatically generated for the check job.

kyb_schema

object

The KYB schema containing the information for business verification checks.

Show Common Object Types

Address Object

object

Standard address format used throughout the schema.

Show Address Properties

street_1

string

required

Primary street address line

street_2

string

Secondary street address line (optional)

city

string

required

City name

state

string

required

State/province code

country_code

string

required

Two-letter ISO country code (e.g., “US”, “GB”)

postal_code

string

required

Postal/ZIP code

Document Object

object

Standard document format used throughout the schema.

Show Document Properties

url

string

URL to access the document. Required if b64_document is not provided.

file_name

string

required

Name of the file including extension

description

string

Description of the document

source_type

string

required

Type of document source. One of: “file_url”, “gdrive”, “dropbox”, etc.

b64_document

string

Base64 encoded document content. Required if url is not provided.

num_pages

integer

Number of pages in the document

Show KYB Schema Properties

string

required

A unique identifier for this check case.

business_name

string

required

The name of the business

registered_business_name

string

The registered name of the business

address_of_incorporation

object

The address where the business is incorporated. Uses the Address Object format defined above.

address_of_operation

object

The address of primary business operations. Uses the Address Object format defined above.

website

string | array

The website(s) of the business

business_purpose

string

The business purpose

description

string

Description of the business

industry

string

The industry of the business

tin_number

string

The tax identification number

partners

string | array

Business partners that should be screened

customers

string | array

Customers that should be screened

source_of_funds

string | array

The source of funds for the business

customer_countries

array

List of countries where the business has customers

incorporation_date

string

The incorporation date in YYYY-MM-DD format

business_registration_number

string

The business registration number

cannabis_license_number

string

The cannabis license number (if applicable)

mcc_code

string

The MCC code of the business

contact_email_address

string

The contact email for the business

contact_phone_number

string

The contact phone number for the business

incorporation_documents

array

List of incorporation documents. Each item uses the Document Object format defined above.

business_ownership_documents

array

List of business ownership documents. Each item uses the Document Object format defined above.

List of promotional/marketing documents. Each item uses the Document Object format defined above.

proof_of_address_documents

array

List of proof of address documents. Each item uses the Document Object format defined above.

source_of_funds_documents

array

List of source of funds documents. Each item uses the Document Object format defined above.

ein_documents

array

List of EIN documents. Each item uses the Document Object format defined above.

cannabis_license_documents

array

List of cannabis license documents. Each item uses the Document Object format defined above.

bank_check_documents

array

List of bank check documents. Each item uses the Document Object format defined above.

kyc_schema

object

The KYC schema containing the information for individual verification checks.

Show Common Object Types

Address Object

object

Standard address format used throughout the schema.

Show Address Properties

street_1

string

required

Primary street address line

street_2

string

Secondary street address line (optional)

city

string

required

City name

state

string

required

State/province code

country_code

string

required

Two-letter ISO country code (e.g., “US”, “GB”)

postal_code

string

required

Postal/ZIP code

Document Object

object

Standard document format used throughout the schema.

Show Document Properties

url

string

URL to access the document. Required if b64_document is not provided.

file_name

string

required

Name of the file including extension

description

string

Description of the document

source_type

string

required

Type of document source. One of: “file_url”, “gdrive”, “dropbox”, etc.

b64_document

string

Base64 encoded document content. Required if url is not provided.

num_pages

integer

Number of pages in the document

Show KYC Schema Properties

string

required

A unique identifier for this check case.

first_name

string

required

The first name of the individual

middle_name

string

The middle name of the individual

last_name

string

required

The last name of the individual

name_prefix

string

The prefix of the individual (e.g., “Mr.”, “Mrs.”, “Dr.”)

name_suffix

string

The suffix of the individual (e.g., “Jr.”, “Sr.”, “III”)

date_of_birth

string

The date of birth of the individual in YYYY-MM-DD format

address

object

The address of the individual. Uses the Address Object format defined above.

country_of_nationality

string

The country of nationality of the individual

country_of_residence

string

The country of residence of the individual

place_of_birth

string

The place of birth of the individual

sex

string

The sex of the individual

string

The email address of the individual

phone

string

The phone number of the individual

title

string

The job title of the individual

linkedin_profile_url

string

The LinkedIn profile URL of the individual

current_employer

string

The current employer of the individual

employer_industry

string

The industry of the current employer

is_applicant

boolean

Whether the individual is an applicant

is_business_owner

boolean

Whether the individual is a business owner

business_ownership_percentage

number

The percentage of business ownership (if applicable)

source_of_funds_description

string

Description of the source of funds

source_of_funds_documents

array

List of source of funds documents. Each item uses the Document Object format defined above.

proof_of_address_documents

array

List of proof of address documents. Each item uses the Document Object format defined above.

webhook_url

string

An optional URL to receive webhook notifications about the check status.

check_args

object

Optional arguments specific to the check being run.

Response

string

The unique identifier for the created check job.

status

string

The current status of the check job (e.g., “PENDING”, “RUNNING”, “COMPLETE”).

created_at

string

The timestamp when the check job was created.

updated_at

string

The timestamp when the check job was last updated.

agent_id

string

The ID of the agent used for this check.

input_payload

object

The input payload provided for the check job.

Example Request

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-kyb-agent-key",
  "check_id": "kyb.web_presence_check",
  "job_id": "your-custom-job-id-123e4567-e89b-12d3-a456-426614174000",
  "kyb_schema": {
    "id": "parcha-single-check-001",
    "business_name": "Acme Corp",
    "website": "https://www.acmecorp.com"
  },
  "webhook_url": "https://your-webhook.com/check-updates"
}'

Example Response

Successful creation (200 OK):

{
  "id": "check-12345-abcde",
  "status": "PENDING",
  "created_at": "2023-06-15T15:30:00Z",
  "updated_at": "2023-06-15T15:30:00Z",
  "agent_id": "your-agent-key",
  "input_payload": {
    "agent_key": "your-kyb-agent-key",
    "check_id": "kyb.web_presence_check",
    "job_id": "your-custom-job-id-123e4567-e89b-12d3-a456-426614174000",
    "kyb_schema": {
      "id": "parcha-single-check-001",
      "business_name": "Acme Corp",
      "website": "https://www.acmecorp.com"
    },
    "webhook_url": "https://your-webhook.com/check-updates"
  }
}

Conflict (409 Conflict) if job_id already exists:

{
  "error": "Job with the provided ID already exists.",
  "job_id": "your-custom-job-id-123e4567-e89b-12d3-a456-426614174000"
}

This endpoint runs a specific check with the provided parameters. The response includes a check job ID that can be used to track the progress and retrieve results of the check.

Implementation Details

The runCheck endpoint is implemented in the shared_router.py file. Here’s a brief overview of the implementation:

The endpoint uses the get_check_schema dependency to parse and validate the incoming request data.
It then calls the celery_enqueue_run_check function, which handles the logic for running a single check.
The function checks if the user has access to the requested agent and validates the check configuration.
If everything is valid, it enqueues the check job using Celery.
Finally, it returns a JSON response with the check job details.

For more detailed information about the implementation, you can refer to the shared_router.py file in the Parcha backend codebase.

Available Checks

Here are some of the available checks that can be run using this endpoint:

kyb.web_presence_check: Verifies the online presence of a business.
kyb.business_registration_check: Checks the registration status of a business.
kyc.identity_verification: Verifies the identity of an individual.
kyc.adverse_media_check: Searches for any negative media coverage related to an individual.

The available checks may vary depending on your subscription level and the specific agent you’re using. Consult the Parcha documentation or contact support for a complete list of checks available to you.

Best Practices

Choose the right check: Make sure you’re using the appropriate check for your use case (KYB or KYC).
Provide comprehensive data: The more details you provide in the payload, the more thorough and accurate the check can be.
Use webhooks: Setting up a webhook_url allows you to receive real-time updates about your check progress.
Handle errors gracefully: Be prepared to handle potential errors or edge cases in your application.
Respect rate limits: Be mindful of any rate limits on the API to ensure smooth operation of your integration.

By following these guidelines, you can effectively use the runCheck endpoint to perform specific checks as part of your KYB or KYC processes.

Authorizations

Authorization

string

header

required

API key obtained from your Parcha account settings. Include as Bearer token in the Authorization header.

Body

application/json

agent_key

string

required

The unique identifier for the agent

check_id

string

required

The ID of the check to run

case_id

string

required

The ID of the case

case_type

enum<string>

required

The type of case

Available options:

kyb,

kyc,

entity

check_args

object

Additional arguments for the check

Response

Check started successfully

​API Endpoint

​Request Body

​Response

​Example Request

​Example Response

​Implementation Details

​Available Checks

​Best Practices

Authorizations

Body

Response

API Endpoint

Request Body

Response

Example Request

Example Response

Implementation Details

Available Checks

Best Practices