openapi: 3.0.0
info:
  title: Integration API
  description: |
    ## Introduction
    This API provides a RESTful interface to interact with Paperbox objects. 
    The integration API is hosted on the domain https://integration.{ENV}.paperbox.ai, where ENV can be either acc for our Acceptance environment or prd for our Production environment.

    ## Authentication
    Paperbox provisions a certificate to the API consumer which is used to sign secure JSON Web Tokens (JWT) on the consumer side, which are then sent in the requests to our API. 
    This approach is further described [here](https://cloud.google.com/endpoints/docs/openapi/service-account-authentication).

    As an additional layer of security, our API also requires an API key, which we provision for each consumer.

    #### OpenAPI Specification
    You can download the raw OpenAPI specification file for this API:
    - [Download OpenAPI v3 specification](/openapi.yaml)

  version: v3
servers:
  - url: https://integration.prd.paperbox.ai/v3
    description: Production Endpoint
tags:
  - name: documents
    x-displayName: Documents
    description: Operations on documents
  - name: masterdata
    x-displayName: Masterdata
    description: Operations on masterdata
  - name: datasources
    x-displayName: Datasources
    description: Operations on datasources
  - name: inboxes
    x-displayName: Inboxes
    description: Operations on inboxes
  - name: health
    x-displayName: Health
    description: health endpoint
x-tagGroups:
  - name: Operational
    tags:
      - documents
      - masterdata
      - inboxes
      - datasources
  - name: General
    tags:
      - health
paths:
  /health:
    get:
      tags:
        - health
      operationId: app.flask.v3.routes.Health.get
      summary: Health check
      description: Check if the API is healthy
      responses:
        200:
          description: healthy
  /documents:
    post:
      tags:
        - documents
      summary: Create a document within a tenant
      description: Provision a document within a tenant by providing an inbox ID
      operationId: app.flask.v3.routes.Documents.post_document
      parameters:
        - $ref: '#/components/parameters/InboxIdQueryParam'
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: X-PB-Document-Content-Type
          in: header
          description: Optional header to specify the content type of the document. This header overrides the content-type that is passed in the form data.
          schema:
            type: string
            enum:
              - "application/msword"
              - "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
              - "text/rtf"
              - "application/docx"
              - "application/rtf"
              - "application/x-rtf"
              - "application/vnd.ms-office"
              - "application/vnd.oasis.opendocument.text"
              - "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
              - "application/vnd.openxmlformats-officedocument.presentationml.presentation"
              - "application/vnd.ms-excel"
              - "application/vnd.oasis.opendocument.spreadsheet"
              - "application/x-gtar"
              - "application/x-tar"
              - "application/x-bzip2"
              - "application/x-xz"
              - "application/x-gzip"
              - "application/gzip"
              - "application/x-bzip"
              - "application/x-7z-compressed"
              - "application/x-zip-compressed"
              - "image/png"
              - "image/jpeg"
              - "image/tiff"
              - "image/jpg"
              - "image/*"
              - "image/x-png"
              - "image/webp"
              - "image/bmp"
              - "image/heic"
              - "image/heif"
              - "application/pdf"
              - "message/rfc822"
              - "application/eml"
              - "text/html"
              - "text/plain"
              - "application/octet-stream"
              - "/octet-stream"
              - "image/gif"
              - "text/vcard"
              - "text/x-vcard"
              - "application/zip"
              - "inode/x-empty"
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DocumentCreate'
        required: true
      responses:
        202:
          description: Payload accepted for processing
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    description: Document ID
  /documents/{document_id}:
    get:
      tags:
        - documents
      summary: Get a document
      description: Get a document by its ID
      operationId: app.flask.v3.routes.Documents.get_document
      parameters:
        - $ref: '#/components/parameters/DocumentIdParam'
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        200:
          description: Document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRead'
    patch:
      tags:
        - documents
      summary: Update a document
      description: Update a document by its ID
      operationId: app.flask.v3.routes.Documents.patch_document
      parameters:
        - $ref: '#/components/parameters/DocumentIdParam'
        - $ref: '#/components/parameters/ApiKeyParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentWrite'
        required: true
      responses:
        200:
          description: Document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRead'
  /documents/{document_id}/raw:
    get:
      tags:
        - documents
      summary: Get a raw document
      description: Get a raw (binary) document by its ID
      operationId: app.flask.v3.routes.Documents.get_raw_document
      parameters:
        - $ref: '#/components/parameters/DocumentIdParam'
        - $ref: '#/components/parameters/ApiKeyParam'
        - $ref: '#/components/parameters/AltExtensionParam'
      responses:
        200:
          description: Document
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /documents/{document_id}/mutations/{mutation_id}/raw:
    get:
      tags:
        - documents
      summary: Get a raw document mutation
      description: Get a raw (binary) document mutation by its ID
      operationId: app.flask.v3.routes.DocumentsMutations.get_raw_document
      parameters:
        - $ref: '#/components/parameters/DocumentIdParam'
        - $ref: '#/components/parameters/MutationIdParam'
        - $ref: '#/components/parameters/ApiKeyParam'
        - $ref: '#/components/parameters/AltExtensionParam'
      responses:
        200:
          description: Document
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /documents/{document_id}/topology/parts/{topology_id}/raw:
    get:
      tags:
        - documents
      summary: Get a raw document topology part
      description: Get a raw (binary) document topology part
      operationId: app.flask.v3.routes.Documents.get_raw_document_by_topology
      parameters:
        - $ref: '#/components/parameters/DocumentIdParam'
        - $ref: '#/components/parameters/TopologyIdParam'
        - $ref: '#/components/parameters/ApiKeyParam'
        - $ref: '#/components/parameters/AltExtensionParam'
      responses:
        200:
          description: Document
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /documents/{document_id}/mutations/{mutation_id}/topology/parts/{topology_id}/raw:
    get:
      tags:
        - documents
      summary: Get a raw document topology part from a mutation
      description: Get a raw (binary) document topology part from a mutation
      operationId: app.flask.v3.routes.DocumentsMutations.get_raw_document_by_topology
      parameters:
        - $ref: '#/components/parameters/DocumentIdParam'
        - $ref: '#/components/parameters/MutationIdParam'
        - $ref: '#/components/parameters/TopologyIdParam'
        - $ref: '#/components/parameters/ApiKeyParam'
        - $ref: '#/components/parameters/AltExtensionParam'
      responses:
        200:
          description: Document
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /inboxes/{inbox_id}/action_metadata_keys/{id}/options:
    put:
      tags:
        - inboxes
      summary: Replace options to an action metadata key
      description: Replace all options for the specified action metadata key
      operationId: app.flask.v3.routes.Inboxes.set_action_metadata_options
      parameters:
        - $ref: '#/components/parameters/InboxIdPathParam'
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/ApiKeyParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - options
              properties:
                options:
                  type: array
                  description: List of options to replace the existing ones
                  items:
                    type: object
                    required:
                      - provider_id
                      - name
                    properties:
                      provider_id:
                        type: string
                        description: Unique identifier for the option
                      name:
                        type: string
                        description: Human-readable name of the option
      responses:
        204:
          description: Options replaced successfully.
          content: {}
  /inboxes/{inbox_id}/entity_types/{id}/options:
    put:
      tags:
        - inboxes
      summary: Replace options to an entity type
      description: Replace all options for the specified entity type
      operationId: app.flask.v3.routes.Inboxes.set_entity_options
      parameters:
        - $ref: '#/components/parameters/InboxIdPathParam'
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/ApiKeyParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - options
              properties:
                options:
                  type: array
                  description: List of options to replace the existing ones
                  items:
                    type: object
                    required:
                      - provider_id
                      - name
                    properties:
                      provider_id:
                        type: string
                        description: Unique identifier for the option
                      name:
                        type: string
                        description: Human-readable name of the option
      responses:
        204:
          description: Options replaced successfully.
          content: {}
  /inboxes/{inbox_id}/tables/{table_id}/versions:
    post:
      tags:
        - masterdata
      summary: Create a new masterdata table version
      description: Create a new version of an existing masterdata table
      operationId: app.flask.v3.routes.MasterData.post_table_version
      parameters:
        - $ref: '#/components/parameters/InboxIdPathParam'
        - $ref: '#/components/parameters/ApiKeyParam'
        - $ref: '#/components/parameters/TableIdParam'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TableCreate'
        required: true
      responses:
        202:
          description: Payload accepted for processing
          content: {}
  /datasources/{datasource_id}/ingest/full:
    post:
      tags:
        - datasources
      summary: Upload a full data version to a datasource
      description: Upload a full data version to a datasource
      operationId: app.flask.v3.routes.Datasources.post_full_data
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - $ref: '#/components/parameters/DatasourceIdParam'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TableCreate'
        required: true
      responses:
        202:
          description: Payload accepted for processing
          content: {}
  /datasources/{datasource_id}/ingest/upserts:
    post:
      tags:
        - datasources
      summary: Upsert data on a datasource
      description: Upsert data on a datasource
      operationId: app.flask.v3.routes.Datasources.post_upserts
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - $ref: '#/components/parameters/DatasourceIdParam'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TableCreate'
        required: true
      responses:
        202:
          description: Payload accepted for processing
          content: {}
  /datasources/{datasource_id}/ingest/deletes:
    post:
      tags:
        - datasources
      summary: Upload deletes to a datasource
      description: Upload deletes to a datasource
      operationId: app.flask.v3.routes.Datasources.post_deletes
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - $ref: '#/components/parameters/DatasourceIdParam'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TableCreate'
        required: true
      responses:
        202:
          description: Payload accepted for processing
          content: {}
components:
  parameters:
    InboxIdQueryParam:
      name: inbox_id
      in: query
      description: Paperbox inbox ID
      required: true
      schema:
        type: string
    InboxIdPathParam:
      name: inbox_id
      in: path
      description: Paperbox inbox ID
      required: true
      schema:
        type: string
    ApiKeyParam:
      name: key
      in: query
      required: true
      schema:
        type: string
    DatasourceIdParam:
      name: datasource_id
      in: path
      description: Datasource ID
      required: true
      schema:
        type: string        
    DocTypeIdParam:
      name: doc_type_id
      in: query
      required: false
      schema:
        type: string
      description: Document type ID (Can only be used if an inbox_id is provided)
    DocSubtypeIdParam:
      name: doc_subtype_id
      in: query
      required: false
      schema:
        type: string
      description: Document subtype ID (Can only be used if an inbox_id is provided)
    TagTypeIdParam:
      name: tag_type_id
      in: query
      required: false
      schema:
        type: string
      description: Tag type ID (Can only be used if an inbox_id is provided)
    ValidationTokenParam:
      name: validationToken
      in: query
      required: false
      schema:
        type: string
      description: Validation token
    DocumentIdParam:
      name: document_id
      in: path
      description: Document ID
      required: true
      schema:
        type: string
    IdParam:
      name: id
      in: path
      description: Action metadata api ID
      required: true
      schema:
        type: string
    MutationIdParam:
      name: mutation_id
      in: path
      description: Document mutation ID
      required: true
      schema:
        type: string
    TopologyIdParam:
      name: topology_id
      in: path
      description: Document topology ID
      required: true
      schema:
        type: string
    AltExtensionParam:
      name: alt_extension
      in: query
      description: Alternative extension for the document (like .pdf or .msg)
      required: false
      schema:
        type: string
    TableIdParam:
      name: table_id
      in: path
      description: Paperbox masterdata table ID
      required: true
      schema:
        type: string
  schemas:
    DocumentCreate:
      type: object
      additionalProperties: false
      required:
        - provider_document_id
        - document
      properties:
        document:
          type: string
          description: Document payload
          format: binary
        provider_document_id:
          type: string
          x-paperbox-logging: true
          description: Custom document ID, set by the user
        doc_type_id:
          type: string
          x-paperbox-logging: true
          nullable: true
          description: Document type ID (Can only be used if an inbox_id is provided)
        doc_subtype_id:
          type: string
          x-paperbox-logging: true
          nullable: true
          description: Document subtype ID (Can only be used if an inbox_id is provided)
        tag_type_id:
          type: string
          x-paperbox-logging: true
          nullable: true
          description: Tag type ID (Can only be used if an inbox_id is provided)
        metadata:
          type: string
          description: Additional document metadata (JSON-formatted)
          format: binary
        name: 
          type: string
          x-paperbox-logging: false
          description: Name of the document
    DocumentWrite:
      type: object
      x-paperbox-logging: true
      additionalProperties: false
      properties:
        action:
          type: object
          additionalProperties: false
          properties:
            type:
              type: string
              description: Action to perform on the document
              enum:
                - approve
                - delete
                - bounce
          required:
            - type
    DocumentRead:
      type: object
      additionalProperties: false
      properties:
        document_id:
          type: string
          readOnly: true
          description: A unique identifier assigned by Paperbox to every processed document.
          x-paperbox-logging: true
        web_url:
          type: string
          readOnly: true
          description: A link to access a document or resource in the Paperbox system via the user interface (UI).
          x-paperbox-logging: true
        provider_document_id:
          type: string
          readOnly: true
          x-nullable: true
          description: An identifier set by the customer or third-party provider to track the document externally.
          x-paperbox-logging: true
        active:
          type: boolean
          description: The current status of the document in Paperbox, specifying whether it has been processed or not.
          x-paperbox-logging: true
        inbox_id:
          type: string
          description: Inbox ID
          x-paperbox-logging: true
        action:
          type: object
          additionalProperties: false
          x-nullable: true
          properties:
            type:
              type: string
              x-paperbox-logging: true
              description: Action that was performed on the document
              enum:
                - approve
                - delete
                - bounce
            actor_id:
              type: string
              readOnly: true
              description: The unique identifier of the user who performed the action.
              x-paperbox-logging: true
            timestamp:
              type: string
              readOnly: true
              description: Timestamp of the action
              x-paperbox-logging: true
            metadata:
              type: array
              description: Additional metadata on the performed 'bounce' or 'delete' action. Empty when the document is approved.
              readOnly: true
              x-nullable: true
              items:
                type: object
                additionalProperties: false
                properties:
                  type:
                    type: string
                  value: {}
                required:
                  - type
                  - value
          required:
            - type
            - actor_id
            - timestamp
        doc_type_id:
          type: string
          readOnly: true
          x-nullable: true
          x-paperbox-logging: true
          description: Document type ID (set by classification)
        doc_subtype_id:
          type: string
          readOnly: true
          x-nullable: true
          x-paperbox-logging: true
          description: Document subtype ID (set by classification)
        confidence:
          type: number
          readOnly: true
          description: Confidence of the classification of the document
          x-nullable: true
          x-paperbox-logging: true
          minimum: 0
          maximum: 1
        tag_type_id:
          type: string
        entities:
          type: array
          readOnly: true
          x-nullable: true
          description: Entities extracted from the document
          items:
            $ref: '#/components/schemas/Entity'
        metadata:
          type: object
          readOnly: true
          x-paperbox-logging: false
          description: Metadata
          additionalProperties: false
          properties:
            table:
              type: object
              additionalProperties: true
              description: Table metadata
            provider:
              type: object
              additionalProperties:
                 type: object
                 additionalProperties: false
                 properties:
                   value:
                     type: string
              description: Provider metadata

        upload_time:
          type: string
          readOnly: true
          x-paperbox-logging: true
          description: The timestamp the document was received by Paperbox
        available_time:
          type: string
          readOnly: true
          x-paperbox-logging: true
          description: The timestamp the document became available in the Paperbox user interface
          x-nullable: true
          nullable: true
      required:
        - document_id
        - active
        - upload_time
    Entity:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: Entity ID (internal use only)
          x-paperbox-logging: true
        type:
          type: string
          description: The entity type as extracted by Paperbox, as defined in the inbox settings.
          x-paperbox-logging: true
        value:
          description: The entity value as processed by Paperbox
          x-nullable: true
        raw_value:
          description: The original value as it appears in the document before any adjustments.
          x-nullable: true
        confidence:
          type: number
          x-paperbox-logging: true
          description: The confidence score indicating the reliability of the detected entity.
          x-nullable: true
          minimum: 0
          maximum: 1
        ocr_confidence:
          type: number
          x-paperbox-logging: true
          description: The confidence score assigned to the entity by OCR (Optical Character Recognition)
          x-nullable: true
          minimum: 0
          maximum: 1
    TableCreate:
      type: object
      additionalProperties: false
      required:
        - content_type
      properties:
        payload:
          type: string
          description: Masterdata table payload
          format: binary
        content_type:
          type: string
          x-paperbox-logging: true
          description: Content type of the table (e.g. 'text/csv' or 'application/json')
          enum:
            - text/csv
            - application/json
x-disable-papertool-validation: true
