> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parcha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Check

> Execute a specific check for KYB or KYC processes

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

<ParamField body="agent_key" type="string" required>
  The unique identifier for the agent to be used for the check.
</ParamField>

<ParamField body="check_id" type="string" required>
  The identifier of the specific check you want to run.
</ParamField>

<ParamField body="job_id" type="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.
</ParamField>

<ParamField body="kyb_schema" type="object">
  The KYB schema containing the information for business verification checks.

  <Expandable title="Common Object Types">
    <ParamField body="Address Object" type="object">
      Standard address format used throughout the schema.

      <Expandable title="Address Properties">
        <ParamField body="street_1" type="string" required>
          Primary street address line
        </ParamField>

        <ParamField body="street_2" type="string">
          Secondary street address line (optional)
        </ParamField>

        <ParamField body="city" type="string" required>
          City name
        </ParamField>

        <ParamField body="state" type="string" required>
          State/province code
        </ParamField>

        <ParamField body="country_code" type="string" required>
          Two-letter ISO country code (e.g., "US", "GB")
        </ParamField>

        <ParamField body="postal_code" type="string" required>
          Postal/ZIP code
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="Document Object" type="object">
      Standard document format used throughout the schema.

      <Expandable title="Document Properties">
        <ParamField body="url" type="string">
          URL to access the document. Required if b64\_document is not provided.
        </ParamField>

        <ParamField body="file_name" type="string" required>
          Name of the file including extension
        </ParamField>

        <ParamField body="description" type="string">
          Description of the document
        </ParamField>

        <ParamField body="source_type" type="string" required>
          Type of document source. One of: "file\_url", "gdrive", "dropbox", etc.
        </ParamField>

        <ParamField body="b64_document" type="string">
          Base64 encoded document content. Required if url is not provided.
        </ParamField>

        <ParamField body="num_pages" type="integer">
          Number of pages in the document
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>

  <Expandable title="KYB Schema Properties">
    <ParamField body="id" type="string" required>
      A unique identifier for this check case.
    </ParamField>

    <ParamField body="business_name" type="string" required>
      The name of the business
    </ParamField>

    <ParamField body="registered_business_name" type="string">
      The registered name of the business
    </ParamField>

    <ParamField body="address_of_incorporation" type="object">
      The address where the business is incorporated. Uses the Address Object format defined above.
    </ParamField>

    <ParamField body="address_of_operation" type="object">
      The address of primary business operations. Uses the Address Object format defined above.
    </ParamField>

    <ParamField body="website" type="string | array">
      The website(s) of the business
    </ParamField>

    <ParamField body="business_purpose" type="string">
      The business purpose
    </ParamField>

    <ParamField body="description" type="string">
      Description of the business
    </ParamField>

    <ParamField body="industry" type="string">
      The industry of the business
    </ParamField>

    <ParamField body="tin_number" type="string">
      The tax identification number
    </ParamField>

    <ParamField body="partners" type="string | array">
      Business partners that should be screened
    </ParamField>

    <ParamField body="customers" type="string | array">
      Customers that should be screened
    </ParamField>

    <ParamField body="source_of_funds" type="string | array">
      The source of funds for the business
    </ParamField>

    <ParamField body="customer_countries" type="array">
      List of countries where the business has customers
    </ParamField>

    <ParamField body="incorporation_date" type="string">
      The incorporation date in YYYY-MM-DD format
    </ParamField>

    <ParamField body="business_registration_number" type="string">
      The business registration number
    </ParamField>

    <ParamField body="cannabis_license_number" type="string">
      The cannabis license number (if applicable)
    </ParamField>

    <ParamField body="mcc_code" type="string">
      The MCC code of the business
    </ParamField>

    <ParamField body="contact_email_address" type="string">
      The contact email for the business
    </ParamField>

    <ParamField body="contact_phone_number" type="string">
      The contact phone number for the business
    </ParamField>

    <ParamField body="incorporation_documents" type="array">
      List of incorporation documents. Each item uses the Document Object format defined above.
    </ParamField>

    <ParamField body="business_ownership_documents" type="array">
      List of business ownership documents. Each item uses the Document Object format defined above.
    </ParamField>

    <ParamField body="promo_marketing_documents" type="array">
      List of promotional/marketing documents. Each item uses the Document Object format defined above.
    </ParamField>

    <ParamField body="proof_of_address_documents" type="array">
      List of proof of address documents. Each item uses the Document Object format defined above.
    </ParamField>

    <ParamField body="source_of_funds_documents" type="array">
      List of source of funds documents. Each item uses the Document Object format defined above.
    </ParamField>

    <ParamField body="ein_documents" type="array">
      List of EIN documents. Each item uses the Document Object format defined above.
    </ParamField>

    <ParamField body="cannabis_license_documents" type="array">
      List of cannabis license documents. Each item uses the Document Object format defined above.
    </ParamField>

    <ParamField body="bank_check_documents" type="array">
      List of bank check documents. Each item uses the Document Object format defined above.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="kyc_schema" type="object">
  The KYC schema containing the information for individual verification checks.

  <Expandable title="Common Object Types">
    <ParamField body="Address Object" type="object">
      Standard address format used throughout the schema.

      <Expandable title="Address Properties">
        <ParamField body="street_1" type="string" required>
          Primary street address line
        </ParamField>

        <ParamField body="street_2" type="string">
          Secondary street address line (optional)
        </ParamField>

        <ParamField body="city" type="string" required>
          City name
        </ParamField>

        <ParamField body="state" type="string" required>
          State/province code
        </ParamField>

        <ParamField body="country_code" type="string" required>
          Two-letter ISO country code (e.g., "US", "GB")
        </ParamField>

        <ParamField body="postal_code" type="string" required>
          Postal/ZIP code
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="Document Object" type="object">
      Standard document format used throughout the schema.

      <Expandable title="Document Properties">
        <ParamField body="url" type="string">
          URL to access the document. Required if b64\_document is not provided.
        </ParamField>

        <ParamField body="file_name" type="string" required>
          Name of the file including extension
        </ParamField>

        <ParamField body="description" type="string">
          Description of the document
        </ParamField>

        <ParamField body="source_type" type="string" required>
          Type of document source. One of: "file\_url", "gdrive", "dropbox", etc.
        </ParamField>

        <ParamField body="b64_document" type="string">
          Base64 encoded document content. Required if url is not provided.
        </ParamField>

        <ParamField body="num_pages" type="integer">
          Number of pages in the document
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>

  <Expandable title="KYC Schema Properties">
    <ParamField body="id" type="string" required>
      A unique identifier for this check case.
    </ParamField>

    <ParamField body="first_name" type="string" required>
      The first name of the individual
    </ParamField>

    <ParamField body="middle_name" type="string">
      The middle name of the individual
    </ParamField>

    <ParamField body="last_name" type="string" required>
      The last name of the individual
    </ParamField>

    <ParamField body="name_prefix" type="string">
      The prefix of the individual (e.g., "Mr.", "Mrs.", "Dr.")
    </ParamField>

    <ParamField body="name_suffix" type="string">
      The suffix of the individual (e.g., "Jr.", "Sr.", "III")
    </ParamField>

    <ParamField body="date_of_birth" type="string">
      The date of birth of the individual in YYYY-MM-DD format
    </ParamField>

    <ParamField body="address" type="object">
      The address of the individual. Uses the Address Object format defined above.
    </ParamField>

    <ParamField body="country_of_nationality" type="string">
      The country of nationality of the individual
    </ParamField>

    <ParamField body="country_of_residence" type="string">
      The country of residence of the individual
    </ParamField>

    <ParamField body="place_of_birth" type="string">
      The place of birth of the individual
    </ParamField>

    <ParamField body="sex" type="string">
      The sex of the individual
    </ParamField>

    <ParamField body="email" type="string">
      The email address of the individual
    </ParamField>

    <ParamField body="phone" type="string">
      The phone number of the individual
    </ParamField>

    <ParamField body="title" type="string">
      The job title of the individual
    </ParamField>

    <ParamField body="linkedin_profile_url" type="string">
      The LinkedIn profile URL of the individual
    </ParamField>

    <ParamField body="current_employer" type="string">
      The current employer of the individual
    </ParamField>

    <ParamField body="employer_industry" type="string">
      The industry of the current employer
    </ParamField>

    <ParamField body="is_applicant" type="boolean">
      Whether the individual is an applicant
    </ParamField>

    <ParamField body="is_business_owner" type="boolean">
      Whether the individual is a business owner
    </ParamField>

    <ParamField body="business_ownership_percentage" type="number">
      The percentage of business ownership (if applicable)
    </ParamField>

    <ParamField body="source_of_funds_description" type="string">
      Description of the source of funds
    </ParamField>

    <ParamField body="source_of_funds_documents" type="array">
      List of source of funds documents. Each item uses the Document Object format defined above.
    </ParamField>

    <ParamField body="proof_of_address_documents" type="array">
      List of proof of address documents. Each item uses the Document Object format defined above.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook_url" type="string">
  An optional URL to receive webhook notifications about the check status.
</ParamField>

<ParamField body="check_args" type="object">
  Optional arguments specific to the check being run.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The unique identifier for the created check job.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the check job (e.g., "PENDING", "RUNNING", "COMPLETE").
</ResponseField>

<ResponseField name="created_at" type="string">
  The timestamp when the check job was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  The timestamp when the check job was last updated.
</ResponseField>

<ResponseField name="agent_id" type="string">
  The ID of the agent used for this check.
</ResponseField>

<ResponseField name="input_payload" type="object">
  The input payload provided for the check job.
</ResponseField>

## Example Request

<CodeGroup>
  ```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-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"
  }'
  ```

  ```python Python theme={null}
  import requests

  api_key = 'YOUR_API_KEY'
  url = 'https://api.parcha.ai/api/v1/runCheck'

  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',
      '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'
  }

  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...")
      # Add logic here to call getJobById or equivalent with data.get('job_id')
      # 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())
  else:
      print(response.json())
  ```

  ```typescript TypeScript theme={null}
  import axios from 'axios';

  const apiKey = 'YOUR_API_KEY';
  const url = 'https://api.parcha.ai/api/v1/runCheck';

  const data = {
    agent_key: 'your-kyb-agent-key',  // Replace with your actual 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'
  };

  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...`);
          // Add logic here to call getJobById or equivalent with data.job_id
          // 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:', error);
      }
  });
  ```
</CodeGroup>

## Example Response

Successful creation (200 OK):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

1. The endpoint uses the `get_check_schema` dependency to parse and validate the incoming request data.
2. It then calls the `celery_enqueue_run_check` function, which handles the logic for running a single check.
3. The function checks if the user has access to the requested agent and validates the check configuration.
4. If everything is valid, it enqueues the check job using Celery.
5. 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.

<Note>
  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.
</Note>

## Best Practices

1. **Choose the right check**: Make sure you're using the appropriate check for your use case (KYB or KYC).
2. **Provide comprehensive data**: The more details you provide in the payload, the more thorough and accurate the check can be.
3. **Use webhooks**: Setting up a `webhook_url` allows you to receive real-time updates about your check progress.
4. **Handle errors gracefully**: Be prepared to handle potential errors or edge cases in your application.
5. **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.


## OpenAPI

````yaml POST /runCheck
openapi: 3.0.0
info:
  title: Parcha API
  version: 1.0.0
  description: API for managing Parcha jobs and checks
servers:
  - url: https://api.parcha.ai/api/v1
    description: Agent Hub API server
  - url: https://demo.parcha.ai/api/v1
    description: Sandbox API server
  - url: https://us1.parcha.ai/api/v1
    description: Legacy API server
  - url: http://{your-company-domain}.parcha.ai/api/v1
    description: Custom Enterpris server (your company's API server)
security:
  - bearerAuth: []
paths:
  /runCheck:
    post:
      summary: Run a check
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckJobInput'
      responses:
        '200':
          description: Check started successfully
        '401':
          description: Unauthorized
      security:
        - bearerAuth: []
components:
  schemas:
    CheckJobInput:
      type: object
      required:
        - agent_key
        - check_id
        - case_id
        - case_type
      properties:
        agent_key:
          type: string
          description: The unique identifier for the agent
        check_id:
          type: string
          description: The ID of the check to run
        case_id:
          type: string
          description: The ID of the case
        case_type:
          type: string
          enum:
            - kyb
            - kyc
            - entity
          description: The type of case
        check_args:
          type: object
          description: Additional arguments for the check
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key obtained from your Parcha account settings. Include as Bearer
        token in the Authorization header.

````