openapi: 3.1.0
info:
  title: Xceptor Document Upload Authentication Templates API
  description: API for uploading and processing documents through Xceptor's data extraction engine. Supports intelligent document processing using NLP, OCR, and generative AI to transform unstructured documents including PDFs, emails, spreadsheets, and handwritten forms into structured, trusted data. The API handles document ingestion, classification, field and table extraction, and confidence-scored output for financial services use cases such as trade confirmations, tax documents, loan notices, and client onboarding materials.
  version: '1.0'
  contact:
    name: Xceptor API Support
    url: https://www.xceptor.com/support
    email: api-support@xceptor.com
  termsOfService: https://www.xceptor.com/legal-tcs
servers:
- url: https://api.xceptor.com/v1
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Templates
  description: Operations for managing extraction templates that define the fields and tables to extract from specific document types.
paths:
  /templates:
    get:
      operationId: listTemplates
      summary: Xceptor List extraction templates
      description: Retrieves a list of available extraction templates. Templates define the fields and tables to extract from specific document types, along with validation rules and confidence thresholds.
      tags:
      - Templates
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      - name: document_type
        in: query
        description: Filter templates by document type
        schema:
          type: string
      responses:
        '200':
          description: A list of extraction templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /templates/{templateId}:
    get:
      operationId: getTemplate
      summary: Xceptor Get template details
      description: Retrieves the full definition of an extraction template, including its field definitions, table definitions, validation rules, and confidence thresholds.
      tags:
      - Templates
      parameters:
      - $ref: '#/components/parameters/TemplateIdParam'
      responses:
        '200':
          description: Template details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TableDefinition:
      type: object
      description: A table definition within an extraction template
      properties:
        name:
          type: string
          description: The name of the table to extract
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: The column name
              data_type:
                type: string
                description: The expected data type of the column
                enum:
                - string
                - number
                - date
                - currency
                - boolean
          description: The expected columns in the table
    Pagination:
      type: object
      description: Pagination information for list responses
      properties:
        page:
          type: integer
          description: The current page number
        page_size:
          type: integer
          description: The number of items per page
        total_items:
          type: integer
          description: The total number of items across all pages
        total_pages:
          type: integer
          description: The total number of pages
    Template:
      type: object
      description: An extraction template that defines the fields and tables to extract from a specific document type, along with validation rules and confidence thresholds.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the template
        name:
          type: string
          description: The display name of the template
        description:
          type: string
          description: A description of the document type this template handles
        document_type:
          type: string
          description: The document type classification this template is designed for
        field_definitions:
          type: array
          items:
            $ref: '#/components/schemas/FieldDefinition'
          description: The fields to extract from documents
        table_definitions:
          type: array
          items:
            $ref: '#/components/schemas/TableDefinition'
          description: The tables to extract from documents
        confidence_threshold:
          type: number
          description: The minimum confidence score for accepting extracted values without manual review (0.0 to 1.0)
          minimum: 0.0
          maximum: 1.0
          default: 0.85
        created_at:
          type: string
          format: date-time
          description: The date and time the template was created
        updated_at:
          type: string
          format: date-time
          description: The date and time the template was last updated
    TemplateList:
      type: object
      description: A paginated list of extraction templates
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Template'
          description: The list of templates for the current page
        pagination:
          $ref: '#/components/schemas/Pagination'
    Error:
      type: object
      description: An error response from the Xceptor API
      properties:
        code:
          type: string
          description: A machine-readable error code
        message:
          type: string
          description: A human-readable description of the error
        details:
          type: object
          description: Additional error details when available
          additionalProperties: true
    FieldDefinition:
      type: object
      description: A field definition within an extraction template
      properties:
        name:
          type: string
          description: The name of the field to extract
        data_type:
          type: string
          description: The expected data type of the field
          enum:
          - string
          - number
          - date
          - currency
          - boolean
        required:
          type: boolean
          description: Whether the field is required in the extraction output
        validation_pattern:
          type: string
          description: A regular expression pattern for validating extracted values
  parameters:
    PageParam:
      name: page
      in: query
      description: The page number for pagination (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
    TemplateIdParam:
      name: templateId
      in: path
      required: true
      description: The unique identifier of the extraction template
      schema:
        type: string
        format: uuid
    PageSizeParam:
      name: page_size
      in: query
      description: The number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth2 access token obtained via the client credentials flow. Include as a Bearer token in the Authorization header.
externalDocs:
  description: Xceptor Document Upload API Documentation
  url: https://docs.xceptor.com/api/documents