Skip to main content
POST
/
startKYCAgentJob
Start a KYC agent job
curl --request POST \
  --url https://api.parcha.ai/api/v1/startKYCAgentJob \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_key": "<string>",
  "check_ids": [
    "<string>"
  ],
  "kyc_schema": {
    "id": "<string>",
    "self_attested_data": {
      "first_name": "<string>",
      "middle_name": "<string>",
      "last_name": "<string>",
      "name_prefix": "<string>",
      "name_suffix": "<string>",
      "date_of_birth": "2023-12-25",
      "address": {
        "street_1": "<string>",
        "street_2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country_code": "<string>",
        "postal_code": "<string>"
      },
      "associated_addresses": [
        {
          "street_1": "<string>",
          "street_2": "<string>",
          "city": "<string>",
          "state": "<string>",
          "country_code": "<string>",
          "postal_code": "<string>"
        }
      ],
      "country_of_nationality": "<string>",
      "country_of_residence": "<string>",
      "place_of_birth": "<string>",
      "sex": "<string>",
      "email": "[email protected]",
      "phone": "<string>",
      "title": "<string>",
      "is_applicant": true,
      "is_business_owner": true,
      "business_ownership_percentage": 123,
      "proof_of_address_documents": [
        {
          "b64_document": "<string>",
          "file_name": "<string>",
          "source_type": "<string>"
        }
      ],
      "source_of_funds_documents": [
        {
          "b64_document": "<string>",
          "file_name": "<string>",
          "source_type": "<string>"
        }
      ]
    }
  }
}
'
{
  "status": "ok",
  "job_id": "<string>",
  "message": "<string>",
  "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.
​
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.

​
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

Response

Job started successfully

​
status
enum<string>
Available options:
ok,
failed,
mock_success
​
job_id
string | null
​
message
string
​
job
object