OpenAPI Specification
openapi: 3.1.0
info:
version: v10.40.4
contact: {}
title: Vic.ai Accounts CSV Reports 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: 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:
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'
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'
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
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
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
responses:
ErrorResponse:
description: An unexpected error has occurred. Check the body for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ResourceNotFoundResponse:
description: Resource was not found.
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'
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'
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'
ForbiddenResponse:
description: The request was forbidden.
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