Start 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

agent_key

string

required

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.

kyc_schema

object

required

The KYC schema containing the individual’s information.

Show KYC Schema Properties

string

required

A unique identifier for this KYC case.

self_attested_data

object

required

Self-attested information about the individual.

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

first_name

string

required

The individual’s first name

middle_name

string

The individual’s middle name

last_name

string

required

The individual’s last name

date_of_birth

string

The individual’s date of birth in YYYY-MM-DD format

address

object

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

associated_addresses

array

Array of associated addresses for the individual. Each item uses the Address Object format defined above.

country_of_nationality

string

Two-letter ISO country code of nationality

country_of_residence

string

Two-letter ISO country code of residence

place_of_birth

string

Place of birth (city, country)

sex

string

Individual’s sex

string

Email address

phone

string

Phone number

proof_of_address_documents

array

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

government_id_check

object

Government ID verification data.

Show Government ID Properties

data

object

Show ID Data Properties

id_first_name

string

First name as shown on ID

id_last_name

string

Last name as shown on ID

id_middle_names

string

Middle names as shown on ID

id_date_of_birth

string

Date of birth in YYYY-MM-DD format

id_type

string

Type of ID document (e.g., “Driver’s License”, “Passport”)

id_number

string

ID document number

id_address

object

Address shown on ID. Uses the Address Object format defined above.

id_country

string

Country that issued the ID

id_phone

string

Phone number on ID

id_front_image_url

string

URL to front image of ID

id_back_image_url

string

URL to back image of ID

id_face_match_image_url

string

URL to face match image

id_face_match_video_url

string

URL to face match video

id_verification_vendor

string

Name of ID verification vendor

vendor_verification_url

string

URL to vendor’s verification page

vendor_validated_document

boolean

Whether vendor validated the document

vendor_id_verification_data

object

Vendor-specific verification data

sanctions_watchlist_screening_check

object

Sanctions and watchlist screening results.

Show Screening Properties

data

object

sanctions_data

array

Array of sanctions matches

pep_screening_check

object

Politically Exposed Person (PEP) screening results.

Show PEP Screening Properties

data

object

pep_data

array

Array of PEP matches

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.

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.

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

Example Response

Successful creation (200 OK):

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

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

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)

kyc_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

Getting Started

Checks Results

API Reference

API Endpoint

Request Body

Response

Example Request

Example Response

Authorizations

Body

Response

Getting Started

Checks Results

API Reference

​API Endpoint

​Request Body

​Response

​Example Request

​Example Response

Authorizations

Body

Response

API Endpoint

Request Body

Response

Example Request

Example Response