Start KYB Agent Job - Parcha API Documentation

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

agent_key

string

required

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.

kyb_schema

object

required

The KYB schema containing the business information.

Show KYB Schema Properties

string

required

A unique identifier for this KYB case.

self_attested_data

object

required

Self-attested information about the business.

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

source_type

string

required

Type of document source. Currently supported: “file_url”

b64_document

string

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

Show Self Attested Data Properties

business_name

string

The name of the business. Required if website is not provided.

registered_business_name

string

The registered name of the business. Required if website is not provided and business_name is not set.

address_of_operation

object

The business’s operational address. Uses the Address Object format defined above.

address_of_incorporation

object

The business’s incorporation address. Uses the Address Object format defined above.

website

string

The website of the business. Required if business_name or registered_business_name is not provided.

business_purpose

string

The primary purpose or activity of the business.

description

string

A brief description of the business. Maximum 512 characters.

industry

string

The industry sector the business operates in.

tin_number

string

Tax Identification Number or Employer Identification Number (EIN).

incorporation_date

string

Date of incorporation in YYYY-MM-DD format.

partners

array

Array of business partner names.

customers

array

Array of customer names.

source_of_funds

array

Array of funding sources (e.g., [“Investment”, “Revenue”]).

incorporation_documents

array

Array of incorporation document objects. Each item uses the Document Object format defined above.

business_ownership_documents

array

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.

proof_of_address_documents

array

Array of address proof document objects. Each item uses the Document Object format defined above.

ein_documents

array

Array of EIN document objects. Each item uses the Document Object format defined above.

source_of_funds_documents

array

Array of funding source document objects. Each item uses the Document Object format defined above.

associated_individuals

array

Array of individuals associated with the business.

Show Associated Individual Properties

string

required

Unique identifier for the individual.

self_attested_data

object

required

Show Individual Data Properties

first_name

string

required

Individual’s first name

middle_name

string

Individual’s middle name

last_name

string

required

Individual’s last name

date_of_birth

string

required

Date of birth in YYYY-MM-DD format

address

object

required

Individual’s address. Uses the Address Object format defined above.

country_of_nationality

string

required

Two-letter ISO country code of nationality

country_of_residence

string

required

Two-letter ISO country code of residence

place_of_birth

string

Place of birth (city, country)

sex

string

Individual’s sex

string

required

Email address

phone

string

required

Phone number

title

string

required

Job title or position

is_applicant

boolean

required

Whether this individual is the applicant

is_business_owner

boolean

required

Whether this individual is a business owner

business_ownership_percentage

number

Percentage of business ownership

proof_of_address_documents

array

Array of address proof document objects. Each item uses the Document Object format defined above.

associated_entities

array

Array of entities associated with the business.

Show Associated Entity Properties

string

required

Unique identifier for the entity

self_attested_data

object

required

Show Entity Data Properties

business_name

string

required

Name of the associated business

is_trust

boolean

required

Whether the entity is a trust

address

object

required

Entity’s address. Uses the Address Object format defined above.

industry

string

Industry sector

tin_number

string

Tax Identification Number

business_ownership_percentage

number

required

Percentage of business ownership

country_code

string

required

Two-letter ISO country code

website

string

Entity’s website

description

string

Description of the entity

job_id

string

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.

webhook_url

string

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

slack_webhook_url

string

An optional Slack webhook URL to receive notifications about the job status.

check_ids

array

An optional array of specific check IDs to run. If not provided, all checks will be run.

Response

status

string

The status of the job creation request. Will be “ok” if successful.

job_id

string

The unique identifier for the created job.

message

string

A message indicating the result of the job creation request.

job

object

Details about the created job.

Show Job Properties

string

The unique identifier of the job.

status

string

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

created_at

string

The timestamp when the job was created.

updated_at

string

The timestamp when the job was last updated.

agent_id

string

The ID of the agent used for this job.

input_payload

object

The input payload provided for the job.

Example Request

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

Example Response

Successful creation (200 OK):

{
  "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:

{
  "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.

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_ids

string[]

The check IDs to run (runs all checks in agent configuration if not provided)

kyb_schema

object

Show child attributes

Response

Job started successfully

status

enum<string>

Available options:

ok,

failed,

mock_success

job_id

string | null

message

string

job

object

​API Endpoint

​Request Body

​Response

​Example Request

​Example Response

Authorizations

Body

Response

API Endpoint

Request Body

Response

Example Request

Example Response