> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parcha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start KYC Agent Job

> Initiate a Know Your Customer (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

<ParamField body="agent_key" type="string" required>
  Your KYC agent key from the Parcha dashboard. This is unique to your organization and agent configuration.
</ParamField>

<Warning>
  **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.
</Warning>

<ParamField body="kyc_schema" type="object" required>
  The KYC schema containing the individual's information.

  <Expandable title="KYC Schema Properties">
    <ParamField body="id" type="string" required>
      A unique identifier for this KYC case.
    </ParamField>

    <ParamField body="self_attested_data" type="object" required>
      Self-attested information about the individual.

      <Expandable title="Common Object Types">
        <ParamField body="Address Object" type="object">
          Standard address format used throughout the schema.

          <Expandable title="Address Properties">
            <ParamField body="street_1" type="string" required>
              Primary street address line
            </ParamField>

            <ParamField body="street_2" type="string">
              Secondary street address line (optional)
            </ParamField>

            <ParamField body="city" type="string" required>
              City name
            </ParamField>

            <ParamField body="state" type="string" required>
              State/province code
            </ParamField>

            <ParamField body="country_code" type="string" required>
              Two-letter ISO country code (e.g., "US", "GB")
            </ParamField>

            <ParamField body="postal_code" type="string" required>
              Postal/ZIP code
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="Document Object" type="object">
          Standard document format used throughout the schema.

          <Expandable title="Document Properties">
            <ParamField body="url" type="string">
              URL to access the document. Required if b64\_document is not provided.
            </ParamField>

            <ParamField body="file_name" type="string" required>
              Name of the file including extension
            </ParamField>

            <ParamField body="source_type" type="string" required>
              Type of document source. Currently supported: "file\_url"
            </ParamField>

            <ParamField body="b64_document" type="string">
              Base64 encoded document content. Required if url is not provided.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>

      <Expandable title="Self Attested Data Properties">
        <ParamField body="first_name" type="string" required>
          The individual's first name
        </ParamField>

        <ParamField body="middle_name" type="string">
          The individual's middle name
        </ParamField>

        <ParamField body="last_name" type="string" required>
          The individual's last name
        </ParamField>

        <ParamField body="date_of_birth" type="string">
          The individual's date of birth in YYYY-MM-DD format
        </ParamField>

        <ParamField body="address" type="object">
          The individual's address.
          Uses the Address Object format defined above.
        </ParamField>

        <ParamField body="associated_addresses" type="array">
          Array of associated addresses for the individual.
          Each item uses the Address Object format defined above.
        </ParamField>

        <ParamField body="country_of_nationality" type="string">
          Two-letter ISO country code of nationality
        </ParamField>

        <ParamField body="country_of_residence" type="string">
          Two-letter ISO country code of residence
        </ParamField>

        <ParamField body="place_of_birth" type="string">
          Place of birth (city, country)
        </ParamField>

        <ParamField body="sex" type="string">
          Individual's sex
        </ParamField>

        <ParamField body="email" type="string">
          Email address
        </ParamField>

        <ParamField body="phone" type="string">
          Phone number
        </ParamField>

        <ParamField body="proof_of_address_documents" type="array">
          Array of address proof document objects.
          Each item uses the Document Object format defined above.
        </ParamField>

        <ParamField body="government_id_check" type="object">
          Government ID verification data.

          <Expandable title="Government ID Properties">
            <ParamField body="data" type="object">
              <Expandable title="ID Data Properties">
                <ParamField body="id_first_name" type="string">
                  First name as shown on ID
                </ParamField>

                <ParamField body="id_last_name" type="string">
                  Last name as shown on ID
                </ParamField>

                <ParamField body="id_middle_names" type="string">
                  Middle names as shown on ID
                </ParamField>

                <ParamField body="id_date_of_birth" type="string">
                  Date of birth in YYYY-MM-DD format
                </ParamField>

                <ParamField body="id_type" type="string">
                  Type of ID document (e.g., "Driver's License", "Passport")
                </ParamField>

                <ParamField body="id_number" type="string">
                  ID document number
                </ParamField>

                <ParamField body="id_address" type="object">
                  Address shown on ID.
                  Uses the Address Object format defined above.
                </ParamField>

                <ParamField body="id_country" type="string">
                  Country that issued the ID
                </ParamField>

                <ParamField body="id_phone" type="string">
                  Phone number on ID
                </ParamField>

                <ParamField body="id_front_image_url" type="string">
                  URL to front image of ID
                </ParamField>

                <ParamField body="id_back_image_url" type="string">
                  URL to back image of ID
                </ParamField>

                <ParamField body="id_face_match_image_url" type="string">
                  URL to face match image
                </ParamField>

                <ParamField body="id_face_match_video_url" type="string">
                  URL to face match video
                </ParamField>

                <ParamField body="id_verification_vendor" type="string">
                  Name of ID verification vendor
                </ParamField>

                <ParamField body="vendor_verification_url" type="string">
                  URL to vendor's verification page
                </ParamField>

                <ParamField body="vendor_validated_document" type="boolean">
                  Whether vendor validated the document
                </ParamField>

                <ParamField body="vendor_id_verification_data" type="object">
                  Vendor-specific verification data
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="sanctions_watchlist_screening_check" type="object">
          Sanctions and watchlist screening results.

          <Expandable title="Screening Properties">
            <ParamField body="data" type="object">
              <ParamField body="sanctions_data" type="array">
                Array of sanctions matches
              </ParamField>
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="pep_screening_check" type="object">
          Politically Exposed Person (PEP) screening results.

          <Expandable title="PEP Screening Properties">
            <ParamField body="data" type="object">
              <ParamField body="pep_data" type="array">
                Array of PEP matches
              </ParamField>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook_url" type="string">
  An optional URL to receive webhook notifications about the job status.
</ParamField>

<ParamField body="slack_webhook_url" type="string">
  An optional Slack webhook URL to receive notifications about the job status.
</ParamField>

<ParamField body="check_ids" type="array">
  An optional array of specific check IDs to run. If not provided, all checks will be run.
</ParamField>

<ParamField body="job_id" type="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.
</ParamField>

## Response

<ResponseField name="status" type="string">
  The status of the job creation request. Will be "ok" if successful.
</ResponseField>

<ResponseField name="job_id" type="string">
  The unique identifier for the created job.
</ResponseField>

<ResponseField name="message" type="string">
  A message indicating the result of the job creation request.
</ResponseField>

<ResponseField name="job" type="object">
  Details about the created job.

  <Expandable title="Job Properties">
    <ResponseField name="id" type="string">
      The unique identifier of the job.
    </ResponseField>

    <ResponseField name="status" type="string">
      The current status of the job (e.g., "PENDING", "RUNNING", "COMPLETE", "FAILED", "RETRIED").
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The timestamp when the job was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The timestamp when the job was last updated.
    </ResponseField>

    <ResponseField name="agent_id" type="string">
      The ID of the agent used for this job.
    </ResponseField>

    <ResponseField name="input_payload" type="object">
      The input payload provided for the job.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }
  }'
  ```

  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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);
      }
  });
  ```
</CodeGroup>

## Example Response

Successful creation (200 OK):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.


## OpenAPI

````yaml POST /startKYCAgentJob
openapi: 3.0.0
info:
  title: Parcha API
  version: 1.0.0
  description: API for managing Parcha jobs and checks
servers:
  - url: https://api.parcha.ai/api/v1
    description: Agent Hub API server
  - url: https://demo.parcha.ai/api/v1
    description: Sandbox API server
  - url: https://us1.parcha.ai/api/v1
    description: Legacy API server
  - url: http://{your-company-domain}.parcha.ai/api/v1
    description: Custom Enterpris server (your company's API server)
security:
  - bearerAuth: []
paths:
  /startKYCAgentJob:
    post:
      summary: Start a KYC agent job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentJobInputKYC'
      responses:
        '200':
          description: Job started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobIdResponse'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
      security:
        - bearerAuth: []
components:
  schemas:
    AgentJobInputKYC:
      allOf:
        - $ref: '#/components/schemas/AgentJobInput'
        - type: object
          properties:
            kyc_schema:
              $ref: '#/components/schemas/ParchaKYCSchema'
    JobIdResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - failed
            - mock_success
        job_id:
          type: string
          nullable: true
        message:
          type: string
        job:
          type: object
          nullable: true
    AgentJobInput:
      type: object
      required:
        - agent_key
        - payload
      properties:
        agent_key:
          type: string
          description: The unique identifier for the agent
        check_ids:
          type: array
          items:
            type: string
          description: >-
            The check IDs to run (runs all checks in agent configuration if not
            provided)
    ParchaKYCSchema:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: A unique id specific to the account being analyzed
        self_attested_data:
          $ref: '#/components/schemas/KYCSelfAttestedData'
    KYCSelfAttestedData:
      type: object
      properties:
        first_name:
          type: string
          description: The first name of the individual
        middle_name:
          type: string
          description: The middle name of the individual
        last_name:
          type: string
          description: The last name of the individual
        name_prefix:
          type: string
          description: The prefix of the individual
        name_suffix:
          type: string
          description: The suffix of the individual
        date_of_birth:
          type: string
          format: date
          description: The date of birth of the individual, format YYYY-MM-DD
        address:
          $ref: '#/components/schemas/Address'
        associated_addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          description: The associated addresses of the individual
        country_of_nationality:
          type: string
          description: The country of nationality of the individual
        country_of_residence:
          type: string
          description: The country of residence of the individual
        place_of_birth:
          type: string
          description: The place of birth of the individual
        sex:
          type: string
          description: The sex of the individual
        email:
          type: string
          format: email
          description: The email of the individual
        phone:
          type: string
          description: The phone number of the individual
        title:
          type: string
          description: The title of the individual
        is_applicant:
          type: boolean
          description: Whether this individual is the applicant
        is_business_owner:
          type: boolean
          description: Whether this individual is a business owner
        business_ownership_percentage:
          type: number
          description: The percentage of business ownership
        proof_of_address_documents:
          type: array
          items:
            type: object
            properties:
              b64_document:
                type: string
                description: Base64 encoded document content
              file_name:
                type: string
                description: Name of the document file
              source_type:
                type: string
                description: Source type of the document
        source_of_funds_documents:
          type: array
          items:
            type: object
            properties:
              b64_document:
                type: string
                description: Base64 encoded document content
              file_name:
                type: string
                description: Name of the document file
              source_type:
                type: string
                description: Source type of the document
    Address:
      type: object
      properties:
        street_1:
          type: string
          description: Primary street address line
        street_2:
          type: string
          description: Secondary street address line (optional)
        city:
          type: string
          description: City name
        state:
          type: string
          description: State/province code
        country_code:
          type: string
          description: Two-letter ISO country code (e.g., "US", "GB")
        postal_code:
          type: string
          description: Postal/ZIP code
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key obtained from your Parcha account settings. Include as Bearer
        token in the Authorization header.

````