> ## 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 KYB Agent Job

> Initiate a Know Your Business (KYB) agent job

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

<ParamField body="agent_key" type="string" required>
  Your KYB 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="kyb_schema" type="object" required>
  The KYB schema containing the business information.

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

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

      <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="business_name" type="string">
          The name of the business. Required if website is not provided.
        </ParamField>

        <ParamField body="registered_business_name" type="string">
          The registered name of the business. Required if website is not provided and business\_name is not set.
        </ParamField>

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

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

        <ParamField body="website" type="string">
          The website of the business. Required if business\_name or registered\_business\_name is not provided.
        </ParamField>

        <ParamField body="business_purpose" type="string">
          The primary purpose or activity of the business.
        </ParamField>

        <ParamField body="description" type="string">
          A brief description of the business. Maximum 512 characters.
        </ParamField>

        <ParamField body="industry" type="string">
          The industry sector the business operates in.
        </ParamField>

        <ParamField body="tin_number" type="string">
          Tax Identification Number or Employer Identification Number (EIN).
        </ParamField>

        <ParamField body="incorporation_date" type="string">
          Date of incorporation in YYYY-MM-DD format.
        </ParamField>

        <ParamField body="partners" type="array">
          Array of business partner names.
        </ParamField>

        <ParamField body="customers" type="array">
          Array of customer names.
        </ParamField>

        <ParamField body="source_of_funds" type="array">
          Array of funding sources (e.g., \["Investment", "Revenue"]).
        </ParamField>

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

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

        <ParamField body="promo_marketing_documents" type="array">
          Array of promotional/marketing document objects.
          Each item uses the Document Object format defined above.
        </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="ein_documents" type="array">
          Array of EIN document objects.
          Each item uses the Document Object format defined above.
        </ParamField>

        <ParamField body="source_of_funds_documents" type="array">
          Array of funding source document objects.
          Each item uses the Document Object format defined above.
        </ParamField>

        <ParamField body="associated_individuals" type="array">
          Array of individuals associated with the business.

          <Expandable title="Associated Individual Properties">
            <ParamField body="id" type="string" required>
              Unique identifier for the individual.
            </ParamField>

            <ParamField body="self_attested_data" type="object" required>
              <Expandable title="Individual Data Properties">
                <ParamField body="first_name" type="string" required>
                  Individual's first name
                </ParamField>

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

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

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

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

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

                <ParamField body="country_of_residence" type="string" required>
                  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" required>
                  Email address
                </ParamField>

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

                <ParamField body="title" type="string" required>
                  Job title or position
                </ParamField>

                <ParamField body="is_applicant" type="boolean" required>
                  Whether this individual is the applicant
                </ParamField>

                <ParamField body="is_business_owner" type="boolean" required>
                  Whether this individual is a business owner
                </ParamField>

                <ParamField body="business_ownership_percentage" type="number">
                  Percentage of business ownership
                </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>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="associated_entities" type="array">
          Array of entities associated with the business.

          <Expandable title="Associated Entity Properties">
            <ParamField body="id" type="string" required>
              Unique identifier for the entity
            </ParamField>

            <ParamField body="self_attested_data" type="object" required>
              <Expandable title="Entity Data Properties">
                <ParamField body="business_name" type="string" required>
                  Name of the associated business
                </ParamField>

                <ParamField body="is_trust" type="boolean" required>
                  Whether the entity is a trust
                </ParamField>

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

                <ParamField body="industry" type="string">
                  Industry sector
                </ParamField>

                <ParamField body="tin_number" type="string">
                  Tax Identification Number
                </ParamField>

                <ParamField body="business_ownership_percentage" type="number" required>
                  Percentage of business ownership
                </ParamField>

                <ParamField body="country_code" type="string" required>
                  Two-letter ISO country code
                </ParamField>

                <ParamField body="website" type="string">
                  Entity's website
                </ParamField>

                <ParamField body="description" type="string">
                  Description of the entity
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</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>

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

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

  ```python Python theme={null}
  import requests

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

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

  data = {
      'agent_key': 'your-kyb-agent-key',  # Replace with your actual 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'
          }
      }
  }

  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/startKYBAgentJob';

  const data = {
    agent_key: 'your-kyb-agent-key',  // Replace with your actual 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'
      }
    }
  };

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

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


## OpenAPI

````yaml POST /startKYBAgentJob
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:
  /startKYBAgentJob:
    post:
      summary: Start a KYB agent job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentJobInputKYB'
      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:
    AgentJobInputKYB:
      allOf:
        - $ref: '#/components/schemas/AgentJobInput'
        - type: object
          properties:
            kyb_schema:
              $ref: '#/components/schemas/ParchaKYBSchema'
    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)
    ParchaKYBSchema:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: A unique id specific to the account being analyzed
        self_attested_data:
          $ref: '#/components/schemas/SelfAttestedData'
        external_validation_data:
          type: object
          description: External validation data for the business
        research_data:
          type: object
          description: Web research data for the business
        associated_individuals:
          type: array
          items:
            $ref: '#/components/schemas/ParchaKYCSchema'
          description: List of associated individuals
        associated_entities:
          type: array
          items:
            type: object
            properties:
              self_attested_data:
                type: object
                properties:
                  business_name:
                    type: string
                  business_ownership_percentage:
                    type: number
                  is_business_owner:
                    type: boolean
          description: List of associated entities
    SelfAttestedData:
      type: object
      properties:
        business_name:
          type: string
          description: The name of the business
          maxLength: 64
        registered_business_name:
          type: string
          description: The registered name of the business
          maxLength: 64
        address_of_incorporation:
          $ref: '#/components/schemas/Address'
        address_of_operation:
          $ref: '#/components/schemas/Address'
        website:
          type: string
          description: The business website URL
        business_purpose:
          type: string
          description: The purpose of the business
        description:
          type: string
          description: Business description
          maxLength: 512
        industry:
          type: string
          description: The industry the business operates in
        tin_number:
          type: string
          description: Tax Identification Number
        incorporation_date:
          type: string
          format: date
          description: Date of incorporation
        partners:
          type: array
          items:
            type: string
          description: List of business partners
        customers:
          type: array
          items:
            type: string
          description: List of customers
        source_of_funds:
          type: array
          items:
            type: string
          description: List of funding sources
        incorporation_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
        business_ownership_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
        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
        ein_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
        cannabis_license_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
    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'
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key obtained from your Parcha account settings. Include as Bearer
        token in the Authorization header.

````