Vic.ai CSV Reports API

openapi: 3.2.0
info:
  version: v10.40.4
  contact: {}
  title: Vic.ai CSV Reports API
  description: '## Introduction


    The Vic.ai API provides a seamless connection between your Enterprise Resource

    Planning (ERP) system and the Vic.ai product suite.'
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: CSV Reports
  description: Generate and retrieve reports
paths:
  /v0/csvReports:
    get:
      description: 'Get the status of all available CSV reports. This endpoint returns a list

        of all supported report types along with their current status (`READY` or `NOT_READY`).

        Reports that are `READY` can be downloaded immediately.


        **Note**: This feature is only available to customers with analytics CSV reports enabled.


        If you would like access to the reports please contact Customer Support.'
      summary: List CSV reports status
      operationId: listCsvReportsStatuses
      tags:
      - CSV Reports
      x-badges:
      - name: Beta
        position: after
        color: orange
      responses:
        '200':
          $ref: '#/components/responses/CsvReportsListResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        4XX:
          $ref: '#/components/responses/ErrorResponse'
    post:
      description: 'Generate all available CSV reports. This operation is asynchronous -

        the reports will be queued for generation and their status

        will be NOT_READY initially. Use the GET endpoint to check when reports

        are READY and can be downloaded. This endpoint has rate limiting (max 1 requests

        per hour).


        **Note**: This feature is only available to customers with analytics CSV reports enabled.


        If you would like access to the reports please contact Customer Support.'
      summary: Generate CSV reports
      operationId: startCsvReportsGeneration
      tags:
      - CSV Reports
      x-badges:
      - name: Beta
        position: after
        color: orange
      requestBody:
        $ref: '#/components/requestBodies/CreateCsvReportsRequest'
      responses:
        '201':
          $ref: '#/components/responses/CsvReportsListResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        4XX:
          $ref: '#/components/responses/ErrorResponse'
  /v0/csvReports/{report_name}:
    get:
      description: 'Download a specific CSV report by name. Returns a redirect (302) to a

        signed URL where the CSV file can be downloaded. The report must be in

        READY status to be downloadable otherwise it will return a 404.


        **Note**: This feature is only available to customers with analytics CSV reports enabled.


        If you would like access to the reports please contact Customer Support.'
      summary: Download CSV report
      operationId: downloadCsvReport
      tags:
      - CSV Reports
      x-badges:
      - name: Beta
        position: after
        color: orange
      parameters:
      - name: report_name
        in: path
        required: true
        description: 'The name of the CSV report to download. Forwards to the location of the CSV file

          and also returns the signedUrl.

          '
        schema:
          type: string
          example: companyUsers
      responses:
        '302':
          $ref: '#/components/responses/CsvReportDownloadResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
        4XX:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    CsvReportDownload:
      type: object
      required:
      - signedUrl
      properties:
        signedUrl:
          type: string
          format: uri
          description: A URL for downloading the CSV file
          example: https://example.com/report.csv
    CreateCsvReports:
      type: object
      properties:
        reportStartAt:
          type: string
          format: date-time
          description: 'Optional filter for the report data (ISO 8601 format).

            If not provided (default 60 days ago at the start of the day).

            '
          example: '2024-01-01T00:00:00Z'
        reportEndAt:
          type: string
          format: date-time
          description: 'Optional end date for the report data (ISO 8601 format).

            If not provided, all data up to the current date will be included.

            '
          example: '2026-12-31T23:59:59Z'
    CsvReport:
      type: object
      required:
      - name
      - status
      properties:
        name:
          type: string
          description: The name/identifier of the CSV report
          example: companyUsers
        status:
          type: string
          enum:
          - READY
          - NOT_READY
          description: 'The current status of the report:

            - `READY`: Report is available for download

            - `NOT_READY`: Report is being created or creation was never initiated

            '
          example: READY
    ErrorString:
      type: string
      maxLength: 255
    CsvReportsList:
      type: object
      required:
      - reports
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/CsvReport'
          description: List of all available CSV reports with their current status
    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'
  responses:
    ForbiddenResponse:
      description: The request was forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CsvReportsListResponse:
      description: List of all CSV reports with their current status.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CsvReportsList'
    BadRequestResponse:
      description: The request was malformed or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CsvReportDownloadResponse:
      description: Redirect to the CSV file download URL.
      headers:
        location:
          description: The signed URL for downloading the CSV file
          schema:
            $ref: '#/components/schemas/CsvReportDownload'
    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'
    ResourceNotFoundResponse:
      description: Resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  requestBodies:
    CreateCsvReportsRequest:
      description: Generate CSV reports with optional date filtering.
      required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateCsvReports'
  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