Veryfi Financial Document Processing

naftiko: "1.0.0-alpha1"

info:
  label: "Veryfi Financial Document Processing"
  description: >-
    Unified financial document processing capability using the Veryfi OCR API.
    Enables accounts payable teams, tax professionals, lenders, and finance
    teams to extract structured data from receipts, invoices, bank statements,
    checks, W-2s, W-9s, and custom documents through a single REST and MCP
    interface. Supports 91 currencies and 38 languages.
  tags:
    - AI
    - Accounts Payable
    - Bank Statements
    - Checks
    - Document Processing
    - Finance
    - Invoices
    - OCR
    - Receipts
    - Tax Forms
    - Veryfi
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VERYFI_CLIENT_ID: VERYFI_CLIENT_ID
      VERYFI_API_KEY: VERYFI_API_KEY
      VERYFI_USERNAME: VERYFI_USERNAME

capability:
  consumes:
    - import: veryfi
      location: ./shared/veryfi-ocr.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: financial-document-processing-api
      description: "Unified REST API for AI-powered financial document data extraction."
      resources:
        - path: /v1/documents
          name: documents
          description: "Process receipts, invoices, and bills"
          operations:
            - method: POST
              name: process-document
              description: "Process a Document"
              call: "veryfi.process-document"
              with:
                file_url: "rest.file_url"
                tags: "rest.tags"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: GET
              name: list-documents
              description: "List All Documents"
              call: "veryfi.list-documents"
              with:
                created_date__gt: "rest.created_date__gt"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/documents/{documentId}
          name: document
          description: "Single document operations"
          operations:
            - method: GET
              name: get-document
              description: "Get a Document"
              call: "veryfi.get-document"
              with:
                documentId: "rest.documentId"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: DELETE
              name: delete-document
              description: "Delete a Document"
              call: "veryfi.delete-document"
              with:
                documentId: "rest.documentId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/bank-statements
          name: bank-statements
          description: "Process and retrieve bank statements"
          operations:
            - method: POST
              name: process-bank-statement
              description: "Process a Bank Statement"
              call: "veryfi.process-bank-statement"
              with:
                file_url: "rest.file_url"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: GET
              name: list-bank-statements
              description: "List All Bank Statements"
              call: "veryfi.list-bank-statements"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/bank-statements/{documentId}
          name: bank-statement
          description: "Single bank statement operations"
          operations:
            - method: GET
              name: get-bank-statement
              description: "Get a Bank Statement"
              call: "veryfi.get-bank-statement"
              with:
                documentId: "rest.documentId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/checks
          name: checks
          description: "Process and retrieve checks"
          operations:
            - method: POST
              name: process-check
              description: "Process a Check"
              call: "veryfi.process-check"
              with:
                file_url: "rest.file_url"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: GET
              name: list-checks
              description: "List All Checks"
              call: "veryfi.list-checks"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/w2s
          name: w2s
          description: "Process and retrieve W-2 tax forms"
          operations:
            - method: POST
              name: process-w2
              description: "Process a W-2 Form"
              call: "veryfi.process-w2"
              with:
                file_url: "rest.file_url"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: GET
              name: list-w2s
              description: "List All W-2 Forms"
              call: "veryfi.list-w2s"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/w9s
          name: w9s
          description: "Process and retrieve W-9 tax forms"
          operations:
            - method: POST
              name: process-w9
              description: "Process a W-9 Form"
              call: "veryfi.process-w9"
              with:
                file_url: "rest.file_url"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/any-documents
          name: any-documents
          description: "Process custom documents with blueprints"
          operations:
            - method: POST
              name: process-any-document
              description: "Process Any Document"
              call: "veryfi.process-any-document"
              with:
                file_url: "rest.file_url"
                blueprint_name: "rest.blueprint_name"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/classify
          name: classify
          description: "Classify documents before processing"
          operations:
            - method: POST
              name: classify-document
              description: "Classify a Document"
              call: "veryfi.classify-document"
              with:
                file_url: "rest.file_url"
                document_types: "rest.document_types"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9080
      namespace: financial-document-processing-mcp
      transport: http
      description: "MCP server for AI-assisted financial document data extraction."
      tools:
        - name: process-receipt-invoice
          description: >-
            Extract structured data from a receipt or invoice. Provide a
            publicly accessible URL to the document. Returns vendor details,
            line items, taxes, totals, and currency in 91 currencies and 38
            languages.
          hints:
            readOnly: false
            openWorld: false
          call: "veryfi.process-document"
          with:
            file_url: "tools.file_url"
            tags: "tools.tags"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-documents
          description: "List all previously processed receipts and invoices."
          hints:
            readOnly: true
            openWorld: true
          call: "veryfi.list-documents"
          with:
            created_date__gt: "tools.created_date__gt"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-document
          description: "Get details for a specific processed document by its numeric ID."
          hints:
            readOnly: true
            openWorld: false
          call: "veryfi.get-document"
          with:
            documentId: "tools.documentId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: delete-document
          description: "Permanently delete a processed document and its extracted data."
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "veryfi.delete-document"
          with:
            documentId: "tools.documentId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: process-bank-statement
          description: >-
            Extract structured transaction data, account information, and
            balances from a bank statement PDF or image URL.
          hints:
            readOnly: false
            openWorld: false
          call: "veryfi.process-bank-statement"
          with:
            file_url: "tools.file_url"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-bank-statements
          description: "List all previously processed bank statements."
          hints:
            readOnly: true
            openWorld: true
          call: "veryfi.list-bank-statements"
          outputParameters:
            - type: object
              mapping: "$."

        - name: process-check
          description: >-
            Extract routing number, account number, check number, payee,
            and amount from a check image URL.
          hints:
            readOnly: false
            openWorld: false
          call: "veryfi.process-check"
          with:
            file_url: "tools.file_url"
          outputParameters:
            - type: object
              mapping: "$."

        - name: process-w2
          description: >-
            Extract wages, tax withholdings, employer EIN, and employee
            information from a W-2 tax form.
          hints:
            readOnly: false
            openWorld: false
          call: "veryfi.process-w2"
          with:
            file_url: "tools.file_url"
          outputParameters:
            - type: object
              mapping: "$."

        - name: process-w9
          description: >-
            Extract taxpayer name, TIN, entity type, and certification
            details from a W-9 form.
          hints:
            readOnly: false
            openWorld: false
          call: "veryfi.process-w9"
          with:
            file_url: "tools.file_url"
          outputParameters:
            - type: object
              mapping: "$."

        - name: process-any-document
          description: >-
            Extract data from any document type using a named Veryfi
            extraction blueprint. Useful for contracts, custom forms, and
            non-standard documents.
          hints:
            readOnly: false
            openWorld: false
          call: "veryfi.process-any-document"
          with:
            file_url: "tools.file_url"
            blueprint_name: "tools.blueprint_name"
          outputParameters:
            - type: object
              mapping: "$."

        - name: classify-document
          description: >-
            Classify a document to determine its type before processing.
            Optionally restrict to specific document types (receipt, invoice,
            bank_statement, w2, w9, check).
          hints:
            readOnly: true
            openWorld: false
          call: "veryfi.classify-document"
          with:
            file_url: "tools.file_url"
            document_types: "tools.document_types"
          outputParameters:
            - type: object
              mapping: "$."