Run Check

Run a check

curl --request POST \
  --url https://api.parcha.ai/api/v1/runCheck \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_key": "<string>",
  "check_id": "<string>",
  "case_id": "<string>",
  "check_args": {}
}
'

import requests

url = "https://api.parcha.ai/api/v1/runCheck"

payload = {
    "agent_key": "<string>",
    "check_id": "<string>",
    "case_id": "<string>",
    "check_args": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_key: '<string>',
    check_id: '<string>',
    case_id: '<string>',
    check_args: {}
  })
};

fetch('https://api.parcha.ai/api/v1/runCheck', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.parcha.ai/api/v1/runCheck",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_key' => '<string>',
    'check_id' => '<string>',
    'case_id' => '<string>',
    'check_args' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.parcha.ai/api/v1/runCheck"

	payload := strings.NewReader("{\n  \"agent_key\": \"<string>\",\n  \"check_id\": \"<string>\",\n  \"case_id\": \"<string>\",\n  \"check_args\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.parcha.ai/api/v1/runCheck")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_key\": \"<string>\",\n  \"check_id\": \"<string>\",\n  \"case_id\": \"<string>\",\n  \"check_args\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.parcha.ai/api/v1/runCheck")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_key\": \"<string>\",\n  \"check_id\": \"<string>\",\n  \"case_id\": \"<string>\",\n  \"check_args\": {}\n}"

response = http.request(request)
puts response.read_body

POST

runCheck

Run a check

curl --request POST \
  --url https://api.parcha.ai/api/v1/runCheck \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_key": "<string>",
  "check_id": "<string>",
  "case_id": "<string>",
  "check_args": {}
}
'

import requests

url = "https://api.parcha.ai/api/v1/runCheck"

payload = {
    "agent_key": "<string>",
    "check_id": "<string>",
    "case_id": "<string>",
    "check_args": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_key: '<string>',
    check_id: '<string>',
    case_id: '<string>',
    check_args: {}
  })
};

fetch('https://api.parcha.ai/api/v1/runCheck', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.parcha.ai/api/v1/runCheck",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_key' => '<string>',
    'check_id' => '<string>',
    'case_id' => '<string>',
    'check_args' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.parcha.ai/api/v1/runCheck"

	payload := strings.NewReader("{\n  \"agent_key\": \"<string>\",\n  \"check_id\": \"<string>\",\n  \"case_id\": \"<string>\",\n  \"check_args\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.parcha.ai/api/v1/runCheck")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_key\": \"<string>\",\n  \"check_id\": \"<string>\",\n  \"case_id\": \"<string>\",\n  \"check_args\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.parcha.ai/api/v1/runCheck")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_key\": \"<string>\",\n  \"check_id\": \"<string>\",\n  \"case_id\": \"<string>\",\n  \"check_args\": {}\n}"

response = http.request(request)
puts response.read_body

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

string

required

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

string

required

The identifier of the specific check you want to run.

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.

object

The KYB schema containing the information for business verification checks.

Show Common Object Types

object

Standard address format used throughout the schema.

Show Address Properties

string

required

Primary street address line

string

Secondary street address line (optional)

string

required

City name

string

required

State/province code

string

required

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

string

required

Postal/ZIP code

object

Standard document format used throughout the schema.

Show Document Properties

string

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

string

required

Name of the file including extension

string

Description of the document

string

required

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

string

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

integer

Number of pages in the document

Show KYB Schema Properties

string

required

A unique identifier for this check case.

string

required

The name of the business

string

The registered name of the business

object

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

object

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

string | array

The website(s) of the business

string

The business purpose

string

Description of the business

string

The industry of the business

string

The tax identification number

string | array

Business partners that should be screened

string | array

Customers that should be screened

string | array

The source of funds for the business

array

List of countries where the business has customers

string

The incorporation date in YYYY-MM-DD format

string

The business registration number

string

The cannabis license number (if applicable)

string

The MCC code of the business

string

The contact email for the business

string

The contact phone number for the business

array

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

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.

array

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

array

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

array

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

array

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

array

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

object

The KYC schema containing the information for individual verification checks.

Show Common Object Types

object

Standard address format used throughout the schema.

Show Address Properties

string

required

Primary street address line

string

Secondary street address line (optional)

string

required

City name

string

required

State/province code

string

required

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

string

required

Postal/ZIP code

object

Standard document format used throughout the schema.

Show Document Properties

string

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

string

required

Name of the file including extension

string

Description of the document

string

required

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

string

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

integer

Number of pages in the document

Show KYC Schema Properties

string

required

A unique identifier for this check case.

string

required

The first name of the individual

string

The middle name of the individual

string

required

The last name of the individual

string

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

string

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

string

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

object

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

string

The country of nationality of the individual

string

The country of residence of the individual

string

The place of birth of the individual

string

The sex of the individual

string

The email address of the individual

string

The phone number of the individual

string

The job title of the individual

string

The LinkedIn profile URL of the individual

string

The current employer of the individual

string

The industry of the current employer

boolean

Whether the individual is an applicant

boolean

Whether the individual is a business owner

number

The percentage of business ownership (if applicable)

string

Description of the source of funds

array

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

array

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

string

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

object

Optional arguments specific to the check being run.

Response

string

The unique identifier for the created check job.

string

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

string

The timestamp when the check job was created.

string

The timestamp when the check job was last updated.

string

The ID of the agent used for this check.

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

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())

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);
    }
});

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

Getting Started

Checks Results

API Reference

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

Authorizations

Body

Response

API Endpoint

Request Body

Response

Example Request

Example Response

Implementation Details

Available Checks

Best Practices