Parcha document-requests API

openapi: 3.0.0
info:
  title: Parcha Admin document-requests 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: []
tags:
- name: document-requests
paths:
  /api/v1/document-requests/create:
    post:
      tags:
      - document-requests
      summary: Create Document Request
      operationId: create_document_request_api_v1_document_requests_create_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRequestCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequest'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/document-requests/update-request:
    put:
      tags:
      - document-requests
      summary: Update Document Request
      operationId: update_document_request_api_v1_document_requests_update_request_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDocumentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequest'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/document-requests/update-case:
    put:
      tags:
      - document-requests
      summary: Update Document Request Case
      operationId: update_document_request_case_api_v1_document_requests_update_case_put
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequest'
      security:
      - HTTPBearer: []
  /api/v1/document-requests/get-request:
    get:
      tags:
      - document-requests
      summary: Get Document Request
      operationId: get_document_request_api_v1_document_requests_get_request_get
      security:
      - HTTPBearer: []
      parameters:
      - name: request_id
        in: query
        required: true
        schema:
          type: string
          title: Request Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequestWithCase'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/document-requests/list-requests:
    get:
      tags:
      - document-requests
      summary: List Document Requests
      operationId: list_document_requests_api_v1_document_requests_list_requests_get
      security:
      - HTTPBearer: []
      parameters:
      - name: owner_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Owner Id
      - name: applicant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Applicant Id
      - name: agent_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Key
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/DocumentRequestState'
          - type: 'null'
          title: State
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentRequestWithCase'
                title: Response List Document Requests Api V1 Document Requests List Requests Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/document-requests/examples:
    get:
      tags:
      - document-requests
      summary: Get Examples
      operationId: get_examples_api_v1_document_requests_examples_get
      security:
      - HTTPBearer: []
      parameters:
      - name: document_type
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/DocumentRequestDocumentType'
      - name: document_request_args
        in: query
        required: true
        schema:
          type: string
          description: URL-encoded JSON string
          title: Document Request Args
        description: URL-encoded JSON string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BusinessCaseSchema:
      properties:
        business_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Name
        registered_business_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Registered Business Name
        website:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - type: 'null'
          title: Website
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
        business_purpose:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Purpose
        business_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Description
        tin_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Tin Number
        partners:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - type: 'null'
          title: Partners
        customers:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - type: 'null'
          title: Customers
        source_of_funds:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - type: 'null'
          title: Source Of Funds
        customer_countries:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Customer Countries
        incorporation_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Incorporation Date
        contact_email_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Email Address
        contact_phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Phone Number
        business_registration_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Registration Number
        case_type:
          $ref: '#/components/schemas/CaseType'
        applicant_id:
          type: string
          title: Applicant Id
        id:
          type: string
          format: uuid
          title: Id
        documents:
          anyOf:
          - items:
              $ref: '#/components/schemas/Document'
            type: array
          - type: 'null'
          title: Documents
        addresses:
          anyOf:
          - items:
              $ref: '#/components/schemas/parcha_backend__entities__Address'
            type: array
          - type: 'null'
          title: Addresses
        job:
          anyOf:
          - $ref: '#/components/schemas/Job'
          - type: 'null'
      type: object
      required:
      - case_type
      - applicant_id
      - id
      title: BusinessCaseSchema
      description: 'unified schema to use in business logic

        need to add back fields we backpopulate'
    IndividualCaseSchema:
      properties:
        first_name:
          type: string
          title: First Name
        middle_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Middle Name
        last_name:
          type: string
          title: Last Name
        date_of_birth:
          anyOf:
          - type: string
          - type: 'null'
          title: Date Of Birth
        country_of_nationality:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Of Nationality
        country_of_residence:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Of Residence
        place_of_birth:
          anyOf:
          - type: string
          - type: 'null'
          title: Place Of Birth
        gender:
          anyOf:
          - type: string
          - type: 'null'
          title: Gender
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        aliases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Aliases
        is_applicant:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Applicant
          default: false
        is_business_owner:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Business Owner
          default: false
        business_ownership_percentage:
          anyOf:
          - type: number
          - type: 'null'
          title: Business Ownership Percentage
        case_type:
          $ref: '#/components/schemas/CaseType'
        applicant_id:
          type: string
          title: Applicant Id
        id:
          type: string
          format: uuid
          title: Id
        documents:
          anyOf:
          - items:
              $ref: '#/components/schemas/Document'
            type: array
          - type: 'null'
          title: Documents
        addresses:
          anyOf:
          - items:
              $ref: '#/components/schemas/parcha_backend__entities__Address'
            type: array
          - type: 'null'
          title: Addresses
        job:
          anyOf:
          - $ref: '#/components/schemas/Job'
          - type: 'null'
      type: object
      required:
      - first_name
      - last_name
      - case_type
      - applicant_id
      - id
      title: IndividualCaseSchema
      description: 'unified schema to use in business logic

        need to add back fields we backpopulate'
    DocumentSourceType:
      type: string
      enum:
      - s3
      - gcs
      - gdrive
      - dropbox
      - onedrive
      - box
      - file_url
      title: DocumentSourceType
      description: Document source type
    Document:
      properties:
        type:
          type: string
          title: Type
          description: The type of the model
          exclude_from_llm: true
        url:
          type: string
          title: Url
          description: The url of the file
          examples:
          - https://www.example.com/file.pdf
        file_name:
          anyOf:
          - type: string
          - type: 'null'
          title: File Name
          description: The name of the file containing the document
          examples:
          - file.pdf
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The description of the document
          examples:
          - Incorporation doc
        source_type:
          $ref: '#/components/schemas/DocumentSourceType'
          description: The source of the document
          default: file_url
          examples:
          - gdrive
        num_pages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Pages
          description: The number of pages in the document
          examples:
          - 10
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        id:
          type: string
          format: uuid
          title: Id
        case_id:
          type: string
          format: uuid
          title: Case Id
        document_type:
          $ref: '#/components/schemas/CaseDocumentType'
      type: object
      required:
      - type
      - case_id
      title: Document
    DocumentRequestState:
      type: string
      enum:
      - draft
      - waiting_for_response
      - approved
      - discarded
      - review
      - expired
      title: DocumentRequestState
    DocumentRequestDocumentType:
      type: string
      enum:
      - business_registration
      const: business_registration
      title: DocumentRequestDocumentType
    Job:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        id:
          type: string
          format: uuid
          title: Id
        celery_task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Celery Task Id
        agent_id:
          type: string
          title: Agent Id
        agent_version_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Agent Version Id
        owner_id:
          type: string
          title: Owner Id
        descope_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Descope User Id
        status:
          $ref: '#/components/schemas/AgentJobStatus'
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
        new_job_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: New Job Id
        original_job_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Original Job Id
        progress:
          anyOf:
          - type: number
          - type: 'null'
          title: Progress
        recommendation:
          anyOf:
          - type: string
          - type: 'null'
          title: Recommendation
        queued_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Queued At
        tenant_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tenant Id
        input_payload:
          anyOf:
          - type: object
          - type: 'null'
          title: Input Payload
        raw_input_payload:
          anyOf:
          - type: string
          - type: 'null'
          title: Raw Input Payload
        batch_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Batch Id
        job_type:
          anyOf:
          - $ref: '#/components/schemas/JobType'
          - type: 'null'
        case_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Case Id
        job_args:
          anyOf:
          - type: object
          - type: 'null'
          title: Job Args
      type: object
      required:
      - agent_id
      - owner_id
      - status
      title: Job
    CaseType:
      type: string
      enum:
      - business
      - individual
      - entity
      title: CaseType
    JobType:
      type: string
      enum:
      - run_agent
      - run_flash_check
      - run_check
      - eval_or_test
      title: JobType
    UpdateDocumentRequest:
      properties:
        request_id:
          type: string
          title: Request Id
        update_data:
          type: object
          title: Update Data
      type: object
      required:
      - request_id
      - update_data
      title: UpdateDocumentRequest
    DocumentRequestType:
      type: string
      enum:
      - kyb
      - kyc
      title: DocumentRequestType
    parcha_backend__entities__Address:
      properties:
        type:
          type: string
          title: Type
          description: The type of the model
          exclude_from_llm: true
        street_1:
          anyOf:
          - type: string
          - type: 'null'
          title: Street 1
          description: The first line of the street address
          examples:
          - 123 Main St
        street_2:
          anyOf:
          - type: string
          - type: 'null'
          title: Street 2
          description: The second line of the street address
          examples:
          - Apt 4B
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
          description: The city of the address
          examples:
          - Anytown
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
          description: The state of the address
          examples:
          - AnyState
        country_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Code
          description: The country of the address as 2-letter code (ISO 3166-1 alpha-2)
          examples:
          - US
        postal_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Postal Code
          description: The postal code of the address
          examples:
          - '54321'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        id:
          type: string
          format: uuid
          title: Id
        case_id:
          type: string
          format: uuid
          title: Case Id
        address_type:
          $ref: '#/components/schemas/AddressType'
      type: object
      required:
      - type
      - case_id
      - address_type
      title: Address
    DocumentRequestWithCase:
      properties:
        document_request:
          $ref: '#/components/schemas/DocumentRequest'
        case:
          anyOf:
          - $ref: '#/components/schemas/BusinessCaseSchema'
          - $ref: '#/components/schemas/IndividualCaseSchema'
          - type: 'null'
          title: Case
      type: object
      required:
      - document_request
      - case
      title: DocumentRequestWithCase
    AgentJobStatus:
      type: string
      enum:
      - submitted
      - queued
      - in progress
      - complete
      - error
      - failed
      - deleted
      - retried
      title: AgentJobStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DocumentRequestCreate:
      properties:
        agent_key:
          type: string
          title: Agent Key
        check_id:
          type: string
          title: Check Id
        applicant_id:
          type: string
          title: Applicant Id
        request_type:
          $ref: '#/components/schemas/DocumentRequestType'
          default: kyb
        check_args:
          anyOf:
          - type: object
          - type: 'null'
          title: Check Args
        state:
          $ref: '#/components/schemas/DocumentRequestState'
          default: draft
      type: object
      required:
      - agent_key
      - check_id
      title: DocumentRequestCreate
    CaseDocumentType:
      type: string
      enum:
      - incorporation
      - business_ownership
      - promo_marketing
      - proof_of_address
      title: CaseDocumentType
    AddressType:
      type: string
      enum:
      - incorporation
      - operations
      - individual
      - individual_associated
      - ubo
      - other
      title: AddressType
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DocumentRequest:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        agent_key:
          type: string
          title: Agent Key
        check_id:
          type: string
          title: Check Id
        applicant_id:
          type: string
          title: Applicant Id
        request_type:
          $ref: '#/components/schemas/DocumentRequestType'
          default: kyb
        check_args:
          anyOf:
          - type: object
          - type: 'null'
          title: Check Args
        state:
          $ref: '#/components/schemas/DocumentRequestState'
          default: draft
        id:
          type: string
          title: Id
        requester_tenant_id:
          type: string
          title: Requester Tenant Id
        requester_owner_id:
          type: string
          title: Requester Owner Id
        expiration_time:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expiration Time
      type: object
      required:
      - agent_key
      - check_id
      - requester_tenant_id
      - requester_owner_id
      title: DocumentRequest
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from your Parcha account settings. Include as Bearer token in the Authorization header.