Tinvio Magic API

openapi: 3.2.0
info:
  title: Tinvio Com Magic API
  version: '1.0'
  contact:
    email: build.with@jaz.ai
    name: API Support
    url: https://jaz.ai
  description: 'Operations tagged Magic across 2 of this provider''s published API definitions: tinvio-com-openapi-original.yaml, tinvio-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.getjaz.com
tags:
- description: Create a transaction from an uploaded document or import a bank statement from an attachment, using AI extraction.
  name: Magic
paths:
  /api/v1/magic/createBusinessTransactionFromAttachment:
    post:
      description: Uploads and process invoice files. Supports file upload (sourceType=FILE), URL download (sourceType=URL), or raw HTML rendered to a PDF (sourceType=HTML).
      operationId: magic-create-business-transaction-from-attachment
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessMagicBTResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create Business Transaction from Attachment
      tags:
      - Magic
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                businessTransactionType:
                  type: string
                  enum:
                  - INVOICE
                  - BILL
                  - CUSTOMER_CREDIT_NOTE
                  - SUPPLIER_CREDIT_NOTE
                  - SALE_QUOTE
                  - SALE_ORDER
                  - PURCHASE_REQUEST
                  - PURCHASE_ORDER
                  default: INVOICE
                  description: Type of transaction to create.
                sourceType:
                  type: string
                  enum:
                  - URL
                  - FILE
                  - HTML
                  default: FILE
                  description: Source of the file to process.
                uploadMode:
                  type: string
                  enum:
                  - SEPARATE
                  - MERGED
                  default: SEPARATE
                  description: 'Upload mode for file preprocessing. SEPARATE (default): each file is processed individually, also handles auto-detected ZIPs. MERGED: a single PDF containing multiple documents is split into individual PDFs before processing.'
                sourceURL:
                  type: string
                  description: URL to download the file from (required if sourceType=URL). Max 65536 characters.
                sourceFile:
                  type: string
                  description: 'Attachment file to upload (required if sourceType=FILE). Supported: PDF, PNG, JPEG, HEIC, XLS, XLSX, EML. Max 10 MB.'
                  format: binary
                html:
                  type: string
                  description: Raw HTML to render to a PDF, then process (required if sourceType=HTML). Max 5 MB.
                internalNotes:
                  type: string
                  description: Internal notes to set on the record this file creates. Visible only inside the organization. Max 3000 characters.
              required:
              - businessTransactionType
              - sourceType
    servers:
    - url: https://api.getjaz.com
  /api/v1/magic/createClaimFromAttachment:
    post:
      description: Upload a receipt (sourceType=FILE), pull one from a URL (sourceType=URL), or render raw HTML such as an email body to a PDF (sourceType=HTML); the file is stored and run through the Magic OCR pipeline, which extracts the expense and creates a draft claim. Optional contactResourceId / claimProfileResourceId / currencyCode / valueDate / internalNotes override the OCR-extracted values. Optional employeeResourceId binds the draft to a specific employee (on-behalf-of). Omit it to auto-bind the uploader's own employee; naming another employee requires a claims Manager/Admin.
      operationId: magic-create-claim-from-attachment
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create Claim from Attachment
      tags:
      - Magic
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sourceType:
                  type: string
                  enum:
                  - URL
                  - FILE
                  - HTML
                  default: FILE
                  description: Source of the receipt.
                sourceFile:
                  type: string
                  description: 'Receipt file (required if sourceType=FILE). Supported: PDF, PNG, JPEG, HEIC. Max 10 MB.'
                  format: binary
                sourceURL:
                  type: string
                  description: URL to download the receipt from (required if sourceType=URL). Max 65536 characters.
                html:
                  type: string
                  description: Raw HTML (e.g. an email body) rendered to a PDF then processed (required if sourceType=HTML). Max 5 MB.
                contactResourceId:
                  type: string
                  description: Resource ID of the vendor contact to pre-bind.
                claimProfileResourceId:
                  type: string
                  description: Resource ID of the claim profile to bind.
                currencyCode:
                  type: string
                  description: Currency override (ISO 4217).
                valueDate:
                  type: string
                  description: Date override, in YYYY-MM-DD format.
                internalNotes:
                  type: string
                  description: Internal notes override.
                employeeResourceId:
                  type: string
                  description: Employee to bind the draft to, on-behalf-of (UUIDv4). Omit to auto-bind the uploader's own employee; naming another requires a claims Manager/Admin.
              required:
              - sourceType
    servers:
    - url: https://api.getjaz.com
  /api/v1/magic/importBankStatementFromAttachment:
    post:
      description: Uploads and process Bank Statement files. Supports file upload (sourceType=FILE) or URL download (sourceType=URL).
      operationId: magic-import-bank-statement-from-attachment
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessBankStatementResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Import Bank Statement from Attachment
      tags:
      - Magic
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                businessTransactionType:
                  type: string
                  enum:
                  - BANK_STATEMENT
                  default: BANK_STATEMENT
                  description: Type of transaction.
                sourceType:
                  type: string
                  enum:
                  - URL
                  - FILE
                  default: FILE
                  description: Source of the file to process.
                accountResourceId:
                  type: string
                  description: Resource ID of the bank account.
                sourceURL:
                  type: string
                  description: URL to download the file from (required if sourceType=URL). Max 65536 characters.
                sourceFile:
                  type: string
                  description: 'Attachment file to upload (required if sourceType=FILE). Supported: PDF, PNG, JPEG, HEIC, XLS, XLSX, EML. Max 10 MB.'
                  format: binary
              required:
              - businessTransactionType
              - sourceType
              - accountResourceId
    servers:
    - url: https://api.getjaz.com
  /api/v1/magic/workflows/search:
    post:
      description: Search across document-processing workflow tasks and bank statement imports, with filters, sort, and pagination.
      operationId: search-magic-workflow
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchMagicWorkflowPageableResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search Magic Workflows
      tags:
      - Magic
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchMagicWorkflowClientRequest'
        description: Search filters, sort, and pagination.
        required: true
    servers:
    - url: https://api.getjaz.com
components:
  schemas:
    MagicWorkflowSearchFilter:
      properties:
        createdAt:
          allOf:
          - $ref: '#/components/schemas/DateExpression'
          description: Workflow creation date, in YYYY-MM-DD format.
        documentType:
          description: 'Document type filter. Determines which workflow tables are queried. Allowed values: SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, SALE_QUOTE, SALE_ORDER, PURCHASE_REQUEST, PURCHASE_ORDER, BANK_STATEMENT.'
          items:
            enum:
            - SALE
            - PURCHASE
            - SALE_CREDIT_NOTE
            - PURCHASE_CREDIT_NOTE
            - SALE_QUOTE
            - SALE_ORDER
            - PURCHASE_REQUEST
            - PURCHASE_ORDER
            - BANK_STATEMENT
            type: string
          type: array
        fileName:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Original file name of the uploaded attachment.
        fileType:
          description: 'File type filter for the uploaded attachment. Allowed values: PDF, PNG, JPEG, JPG, HEIC, CSV, XLS, XLSX, EML.'
          items:
            enum:
            - PDF
            - PNG
            - JPEG
            - JPG
            - HEIC
            - CSV
            - XLS
            - XLSX
            - EML
            type: string
          type: array
        resourceId:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Workflow resource ID (UUIDv4).
        status:
          description: 'Unified workflow status filter. Allowed values: SUBMITTED, PROCESSING, COMPLETED, FAILED.'
          items:
            enum:
            - SUBMITTED
            - PROCESSING
            - COMPLETED
            - FAILED
            type: string
          type: array
      type: object
    SearchMagicWorkflowClientRequest:
      properties:
        filter:
          allOf:
          - $ref: '#/components/schemas/MagicWorkflowSearchFilter'
          description: Filter criteria for magic workflow search.
        limit:
          default: 100
          description: Maximum number of results per page (max 1000).
          maximum: 1000
          minimum: 1
          type: integer
        offset:
          default: 0
          description: Zero-indexed row offset into the result set. Sort is required when offset is set.
          maximum: 65536
          minimum: 0
          type: integer
        query:
          description: 'Structured search query using Jaz search operators. Parsed automatically into filter fields.

            Explicit filter fields override query results on conflict.

            Example: "status:unpaid AND $500+".'
          maxLength: 1000
          type: string
        sort:
          allOf:
          - $ref: '#/components/schemas/MagicWorkflowSortFilter'
          description: Sort criteria (required when using offset).
      type: object
    ErrorResponse:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/ErrorResponseData'
          description: Error details.
      type: object
    DateExpression:
      properties:
        between:
          description: Match dates between these two dates (exactly two, in YYYY-MM-DD format).
          items:
            type: string
          type: array
        eq:
          description: Match dates equal to this, in YYYY-MM-DD format.
          type: string
        gt:
          description: Match dates after this, in YYYY-MM-DD format.
          type: string
        gte:
          description: Match dates on or after this, in YYYY-MM-DD format.
          type: string
        isNotNull:
          description: Match records where the date is set. Pass the placeholder date "0001-01-01".
          example: '0001-01-01'
          type: string
        isNull:
          description: Match records where the date is not set. Pass the placeholder date "0001-01-01".
          example: '0001-01-01'
          type: string
        lt:
          description: Match dates before this, in YYYY-MM-DD format.
          type: string
        lte:
          description: Match dates on or before this, in YYYY-MM-DD format.
          type: string
        notBetween:
          description: Match dates outside these two dates (exactly two, in YYYY-MM-DD format).
          items:
            type: string
          type: array
      required:
      - between
      type: object
    SearchMagicWorkflowPageableResponse:
      properties:
        data:
          description: List of magic workflow records.
          items:
            $ref: '#/components/schemas/MagicWorkflowItem'
          type: array
        totalElements:
          description: Total number of records matching the query.
          example: 42
          type: integer
        totalPages:
          description: Total number of pages.
          example: 1
          type: integer
      type: object
    BaseResponse:
      properties:
        data:
          description: The response object.
      type: object
    ProcessMagicBTResponse:
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/ProcessMagicBTResponseData'
          description: Processing result.
      type: object
    MagicWorkflowBankStatementDetails:
      properties:
        accountNumber:
          description: Bank account number.
          type: string
        importedDate:
          description: Import timestamp.
          type: string
        organizationAccountResourceId:
          description: Linked bank account resource ID.
          type: string
        statementEndDate:
          description: Statement period end date, in YYYY-MM-DD format.
          example: '2024-01-31'
          type: string
        statementEntryCount:
          description: Number of parsed statement entries.
          example: 25
          type: integer
        statementStartDate:
          description: Statement period start date, in YYYY-MM-DD format.
          example: '2024-01-01'
          type: string
        statementStatus:
          description: Statement processing status.
          type: string
      type: object
    StringExpression:
      properties:
        contains:
          description: Match values containing this substring.
          type: string
        endWith:
          description: Match values ending with this term (case sensitive).
          type: string
        eq:
          description: Match values equal to this.
          type: string
        in:
          description: Match values equal to any of these.
          items:
            type: string
          maxItems: 100
          type: array
        isBlank:
          description: Match records where the field is null or empty ("true") or neither ("false").
          type: string
        isNotBlank:
          description: Match records where the field is neither null nor empty ("true").
          type: string
        isNull:
          description: Match records where the field is null ("true") or not null ("false").
          type: string
        likeIn:
          description: Match values containing any of these substrings.
          items:
            type: string
          maxItems: 100
          type: array
        neq:
          description: Match values not equal to this.
          type: string
        notContains:
          description: Match values not containing this substring.
          type: string
        notEndWith:
          description: Match values not ending with this term (case sensitive).
          type: string
        notStartWith:
          description: Match values not starting with this term (case sensitive).
          type: string
        reg:
          description: Match values containing any of these terms. This is a substring match, not a regular expression, despite the name.
          items:
            type: string
          maxItems: 100
          type: array
        startWith:
          description: Match values starting with this term (case sensitive).
          type: string
      required:
      - in
      - likeIn
      - reg
      type: object
    ProcessBankStatementResponse:
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/ProcessBankStatementResponseData'
          description: Processing result.
      type: object
    MagicWorkflowSortFilter:
      properties:
        order:
          description: Sort direction, ASC or DESC.
          enum:
          - ASC
          - asc
          - DESC
          - desc
          type: string
        sortBy:
          description: Fields to sort by, in priority order.
          items:
            type: string
          maxItems: 25
          type: array
          uniqueItems: true
      required:
      - order
      - sortBy
      type: object
    ProcessMagicBTResponseData:
      properties:
        businessTransactionType:
          description: Type of transaction created.
          enum:
          - SALE
          - PURCHASE
          - SALE_CREDIT_NOTE
          - PURCHASE_CREDIT_NOTE
          - SALE_QUOTE
          - SALE_ORDER
          - PURCHASE_REQUEST
          - PURCHASE_ORDER
          example: SALE
          type: string
        filename:
          description: Original file name of the uploaded attachment.
          example: invoice.pdf
          type: string
        invalidFiles:
          description: Files that failed processing.
          items:
            $ref: '#/components/schemas/MagicFileResult'
          type: array
        validFiles:
          description: Files processed successfully.
          items:
            $ref: '#/components/schemas/MagicFileResult'
          type: array
      type: object
    MagicWorkflowBusinessTransactionDetails:
      properties:
        businessTransactionResourceId:
          description: Resource ID of the created draft business transaction (null until created).
          type: string
        ocrJobType:
          description: OCR job type (SYNC or ASYNC).
          example: SYNC
          type: string
        parentResourceId:
          description: Parent workflow resource ID for retry/split flows.
          type: string
        workflowStatus:
          description: Raw workflow status (for example TRANSACTION_CREATED, OCR_SYNC_SUCCEEDED, or OCR_ASYNC_SUBMITTED).
          example: TRANSACTION_CREATED
          type: string
      type: object
    MagicWorkflowItem:
      properties:
        bankStatementDetails:
          allOf:
          - $ref: '#/components/schemas/MagicWorkflowBankStatementDetails'
          description: Bank statement import details. Populated for BANK_STATEMENT rows, null for transaction rows.
        batchId:
          description: Batch grouping identifier.
          type: string
        businessTransactionDetails:
          allOf:
          - $ref: '#/components/schemas/MagicWorkflowBusinessTransactionDetails'
          description: Transaction workflow details. Populated for transaction rows, null for BANK_STATEMENT rows.
        createdAt:
          description: Workflow creation timestamp.
          example: '2024-01-15'
          type: string
        createdBy:
          description: User who created the workflow.
          type: string
        documentType:
          description: Document type (SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, or BANK_STATEMENT).
          example: SALE
          type: string
        failureReason:
          description: Error details when workflow has failed.
          type: string
        fileId:
          description: File identifier (MD5 hash).
          type: string
        fileName:
          description: Original filename of the uploaded attachment.
          example: invoice.pdf
          type: string
        fileType:
          description: File type of the uploaded attachment (PDF, PNG, JPG, CSV, etc.).
          example: PDF
          type: string
        fileUrl:
          description: URL of the uploaded file.
          type: string
        firebaseUpdated:
          description: When true, the real-time status notification has been sent.
          type: boolean
        organizationResourceId:
          description: Organization resource ID (UUIDv4).
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        resourceId:
          description: Workflow resource ID (UUIDv4).
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          type: string
        status:
          description: Unified workflow status (SUBMITTED, PROCESSING, COMPLETED, FAILED).
          example: COMPLETED
          type: string
        updatedAt:
          description: Workflow last updated timestamp.
          example: '2024-01-15'
          type: string
      type: object
    MagicFileDetails:
      properties:
        fileId:
          description: MD5 hash identifier of the file.
          type: string
        fileName:
          description: Original file name.
          example: invoice.pdf
          type: string
        fileType:
          description: File MIME type.
          example: PDF
          type: string
        fileURL:
          description: URL of the uploaded file.
          type: string
      type: object
    ProcessBankStatementResponseData:
      properties:
        businessTransactionType:
          description: Type of transaction.
          example: BANK_STATEMENT
          type: string
        filename:
          description: Original file name of the uploaded attachment.
          example: statement.pdf
          type: string
        invalidFiles:
          description: Files that failed processing.
          items:
            $ref: '#/components/schemas/MagicFileResult'
          type: array
        validFiles:
          description: Files processed successfully.
          items:
            $ref: '#/components/schemas/MagicFileResult'
          type: array
      type: object
    ErrorResponseData:
      properties:
        error_type:
          description: Error category, for example validation_error, invalid_request_body, or internal_server_error.
          example: validation_error
          type: string
        errors:
          description: Error messages describing what went wrong.
          items:
            type: string
          type: array
      type: object
    MagicFileResult:
      properties:
        errorCode:
          description: Error code when processing failed.
          type: string
        errorMessage:
          description: Error message when processing failed.
          type: string
        fileDetails:
          allOf:
          - $ref: '#/components/schemas/MagicFileDetails'
          description: Details of the uploaded file.
        subscriptionFBPath:
          description: Subscription path for real-time status updates.
          type: string
        workflowResourceId:
          description: Resource ID of the workflow task, for tracking processing status.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Organization API key. Pass it in the x-jk-api-key header on every request.
      in: header
      name: x-jk-api-key
      type: apiKey
x-refined-from:
- tinvio-com-openapi-original.yaml
- tinvio-com-openapi.yml