Start KYC Agent Job

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

import requests

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

payload = {
    "agent_key": "<string>",
    "check_ids": ["<string>"]
}
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_ids: ['<string>']})
};

fetch('https://api.parcha.ai/api/v1/startKYCAgentJob', 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/startKYCAgentJob",
  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_ids' => [
        '<string>'
    ]
  ]),
  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/startKYCAgentJob"

	payload := strings.NewReader("{\n  \"agent_key\": \"<string>\",\n  \"check_ids\": [\n    \"<string>\"\n  ]\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/startKYCAgentJob")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_key\": \"<string>\",\n  \"check_ids\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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_ids\": [\n    \"<string>\"\n  ]\n}"

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

{
  "job_id": "<string>",
  "message": "<string>",
  "job": {}
}

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

import requests

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

payload = {
    "agent_key": "<string>",
    "check_ids": ["<string>"]
}
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_ids: ['<string>']})
};

fetch('https://api.parcha.ai/api/v1/startKYCAgentJob', 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/startKYCAgentJob",
  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_ids' => [
        '<string>'
    ]
  ]),
  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/startKYCAgentJob"

	payload := strings.NewReader("{\n  \"agent_key\": \"<string>\",\n  \"check_ids\": [\n    \"<string>\"\n  ]\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/startKYCAgentJob")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_key\": \"<string>\",\n  \"check_ids\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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_ids\": [\n    \"<string>\"\n  ]\n}"

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

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

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.

object

required

The KYC schema containing the individual’s information.

Show KYC Schema Properties

string

required

A unique identifier for this KYC case.

object

required

Self-attested information about the individual.

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

required

Type of document source. Currently supported: “file_url”

string

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

Show Self Attested Data Properties

string

required

The individual’s first name

string

The individual’s middle name

string

required

The individual’s last name

string

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

object

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

array

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

string

Two-letter ISO country code of nationality

string

Two-letter ISO country code of residence

string

Place of birth (city, country)

string

Individual’s sex

string

Email address

string

Phone number

array

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

object

Government ID verification data.

Show Government ID Properties

object

Show ID Data Properties

string

First name as shown on ID

string

Last name as shown on ID

string

Middle names as shown on ID

string

Date of birth in YYYY-MM-DD format

string

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

string

ID document number

object

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

string

Country that issued the ID

string

Phone number on ID

string

URL to front image of ID

string

URL to back image of ID

string

URL to face match image

string

URL to face match video

string

Name of ID verification vendor

string

URL to vendor’s verification page

boolean

Whether vendor validated the document

object

Vendor-specific verification data

object

Sanctions and watchlist screening results.

Show Screening Properties

object

array

Array of sanctions matches

object

Politically Exposed Person (PEP) screening results.

Show PEP Screening Properties

object

array

Array of PEP matches

string

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

string

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

array

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

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

string

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

string

The unique identifier for the created job.

string

A message indicating the result of the job creation request.

object

Details about the created job.

Show Job Properties

string

The unique identifier of the job.

string

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

string

The timestamp when the job was created.

string

The timestamp when the job was last updated.

string

The ID of the agent used for this job.

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

import requests

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

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

data = {
    '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'
        }
    }
}

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...")
    # 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())
elif response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

import axios from 'axios';

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

const data = {
  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'
    }
  }
};

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...`);
        // 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 starting job:', error.response ? error.response.data : error.message);
    }
});

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 | null

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

Authorizations

Body

Response

API Endpoint

Request Body

Response

Example Request

Example Response