Vic.ai Attachments API

openapi: 3.1.0
info:
  version: v10.40.4
  contact: {}
  title: Vic.ai Accounts Attachments API
  description: "## Introduction\n\nThe Vic.ai API provides a seamless connection between your Enterprise Resource\nPlanning (ERP) system and the Vic.ai product suite.\n\nThe API is designed to offer three main areas of functionality:\n\n- **Syncing master data:** This refers to the data in your ERP that Vic.ai\n  interacts with. You are required to supply and update this data in Vic.ai, and\n  you also have the option to verify the copy of the masterdata in Vic.ai.\n\n- **Syncing training data:** We need historical data to train your AI model. To\n  that end, the API provides endpoints to sync historical invoices into Vic.ai\n  and to confirm their presence.\n\n- **Subscribing to and receiving webhooks:** Webhooks enable users or automated\n  tasks to interact with your ERP through various actions in the Vic.ai product\n  suite, such as posting an invoice, payment or purchase order or requesting\n  synchronization. You will receive a notification via a webhook when these\n  actions occur.\n\n\nFor US-based integrations, please use the following base API URL:\n\n```\nhttps://api.us.vic.ai\n```\n\nFor integrations based in Norway, use the following base API URL:\n\n```\nhttps://api.no.vic.ai\n```\n\nAll paths mentioned in this documentation should use one of these URLs as the\nbase.\n\nExample:\n\n```bash\ncurl https://api.us.vic.ai/v0/healthCheck \\\n    -H \"Content-Type: application/json\" \\\n    -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## Getting Started\n\nTo begin interacting with the Vic.ai API, you will need the following\ncredentials:\n\n* A Vic.ai client ID\n* A Vic.ai client secret.\n\nThese can be provided to you securely by a Vic.ai representative\n[upon request](https://www.vic.ai/book-a-demo).\n\n**Please note:** These credentials are essentially the keys to your ERP\nintegration. If they fall into the wrong hands, unauthorized parties could\nimpersonate you, gain access to sensitive data, and potentially perform\nmalicious actions. Therefore, it's crucial to keep these credentials safe at all\ntimes to protect your application's integrity and your clients' data.\n\n### Limitations\n\nThe Vic.ai API has the following limitations:\n\n**Rate Limiting:** The API is rate-limited to 500 requests per 10-second time\nframe. If you exceed this limit, you will receive a `429 Too Many Requests`\nresponse. The limit is per Oauth client ID. If you continue to receive `429`s,\nplease contact support with a request id from the response headers.\n"
servers:
- url: https://api.no.stage.vic.ai
  description: staging server, NO
- url: https://api.us.vic.ai
  description: production server, US
- url: https://api.no.vic.ai
  description: production server, NO
security:
- BearerAuth: []
tags:
- name: Attachments
  description: "Attachments are original invoice documents that can be processed by Vic.ai.\n\n## Supported content types\n\n- `application/msword`\n- `application/pdf`\n- `application/vnd.ms-word.document.macroEnabled.12`\n- `application/vnd.ms-word.template.macroEnabled.12`\n- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`\n- `application/vnd.openxmlformats-officedocument.wordprocessingml.template`\n- `image/tiff`\n- `text/xml` **(See note below about supported EDI formats)**\n- `image/jpg`\n- `image/jpeg`\n- `image/png`\n- `image/gif`\n- `application/vnd.ms-excel`\n- `application/vnd.ms-excel.addin.macroenabled.12`\n- `application/vnd.ms-excel.sheet.binary.macroenabled.12`\n- `application/vnd.ms-excel.sheet.macroenabled.12`\n- `application/vnd.ms-excel.template.macroenabled.12`\n- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`\n- `application/vnd.openxmlformats-officedocument.spreadsheetml.template`\n\n### Supported EDI formats:\n\n#### PEPPOL BIS Billing v3 \n\nSupported embedded attachment MIME codes: \n\n- `application/pdf`\n- `image/jpeg`\n- `image/png`\n- `image/tiff`\n\nThe API will ignore other attachment types.\n\n#### X12 EDI 810\n\nX12 ingestion is opt-in — contact Vic.ai support to enable it for your\norganization.\n\nRaw X12 EDI 810 invoice files (version 4010) are accepted — upload the file as\nyour supplier sends it (a `.edi` or `.x12` file beginning with an `ISA`\nsegment), with no conversion. An interchange may contain several invoices; each\ntransaction set becomes its own invoice, and Vic.ai renders an image for each so\nit is processed like any other invoice.\n\nBecause processing happens asynchronously, the upload response confirms only that\nthe file was received. Use `GET /v0/attachments/{id}` to check whether processing\ncompleted and to retrieve the ids of the invoices that were created.\n"
paths:
  /v0/attachments:
    post:
      description: 'Use this to upload an attachment to Vic.ai. The attachment will be

        created and processing enqueued automatically.


        The response is a 201 with the attachment ID.

        '
      summary: Upload an attachment
      operationId: uploadAttachment
      tags:
      - Attachments
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          $ref: '#/components/responses/AttachmentCreatedResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        4XX:
          $ref: '#/components/responses/ErrorResponse'
  /v0/attachments/{id}:
    get:
      description: 'Returns the processing status of an uploaded attachment, and the ids of

        any invoices created from it.


        Processing is asynchronous: a `201` from the upload only confirms the

        file was received and queued. Poll this endpoint to learn whether

        processing completed (`status: processed`) or failed (`status: failed`).

        '
      summary: Get attachment processing status
      operationId: getAttachmentStatus
      tags:
      - Attachments
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The attachment's processing status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                    - processing
                    - processed
                    - failed
                    - ignored
                  error_code:
                    oneOf:
                    - type: 'null'
                    - type: string
                  error_message:
                    oneOf:
                    - type: 'null'
                    - type: string
                  invoice_ids:
                    type: array
                    items:
                      type: string
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        4XX:
          $ref: '#/components/responses/ErrorResponse'
components:
  responses:
    ErrorResponse:
      description: An unexpected error has occurred. Check the body for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequestsResponse:
      description: HTTP call rate limit exceeded.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request. Waiting this long guarantees the rate-limit window has reset.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AttachmentCreatedResponse:
      description: The shape of the response when an attachment is created.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Attachment'
  schemas:
    ErrorString:
      type: string
      maxLength: 255
    Error:
      description: 'generic error message in JSON format.  Note the ''code'' field should

        match the HTTP status code of the wrapping HTTP request.

        '
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          minimum: 100
          maximum: 599
        message:
          $ref: '#/components/schemas/ErrorString'
    Attachment:
      type: object
      required:
      - id
      properties:
        id:
          $ref: '#/components/schemas/InternalId'
    InternalId:
      description: The internal id Vic uses for the record.
      type: string
      example: '47'
      readOnly: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Integration
  tags:
  - Authentication
  - Pagination
  - Webhooks
  - Webhook Subscriptions
  - Webhook Events
  - Synchronizing
  - Status
- name: Master Data
  tags:
  - Accounts
  - Dimensions
  - Vendors
  - Vendor Groups
  - Vendor Tags
  - Tags
  - Tax Codes
  - VAT Codes
  - Payment Terms
- name: Organization & Access
  tags:
  - Partners
  - Organizations
  - Companies
  - Users
- name: Invoices & Bills
  tags:
  - Invoices
  - Bills
  - Attachments
  - Invoice Approval Flows
  - Invoice Posting Guide
  - Training Invoices
- name: Purchase Orders
  tags:
  - Purchase Orders
  - Purchase Order Line Items
  - Purchase Order Matching Guide
- name: Payments
  tags:
  - Payment Batches
  - Payment Confirmations
  - Credit Confirmations
- name: Reporting
  tags:
  - CSV Reports
- name: Reference
  tags:
  - Changelog