Vic.ai Bills API
Bills are imported invoices that can be created and updated through the API. These operations allow you to create new bills and update existing ones that were previously imported via the API.
OpenAPI Specification
openapi: 3.1.0
info:
version: v10.40.4
contact: {}
title: Vic.ai Accounts Bills 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: Bills
description: 'Bills are imported invoices that can be created and updated through the API.
These operations allow you to create new bills and update existing ones
that were previously imported via the API.
'
paths:
/v2/bills:
post:
description: 'Create a new imported bill with the given `remote_id`. If a bill with the
same `remote_id` already exists, returns an error.
Imported bills are automatically set to "posted" status.
**Document Upload**: You can upload a document along with the bill data using multipart/form-data.
When using multipart, send the bill data fields directly and the file as `document`.
**VAT Handling**: If `total_vat_amount` is provided and greater than zero, the system
will automatically create a hidden VAT line item in addition to the provided line items.
**Note**: Only bills imported via the API can be updated later using the update endpoint.
**Required Configuration**: This endpoint requires the "Allow bills to be imported via public API"
company configuration to be enabled. Returns 403 Forbidden if not enabled.
'
summary: Create a new imported bill
operationId: createBillV2
tags:
- Bills
x-badges:
- name: V2
position: after
color: blue
- name: Beta
position: after
color: orange
requestBody:
$ref: '#/components/requestBodies/CreateBillRequestV2'
responses:
'201':
$ref: '#/components/responses/CreateBillResponseV2'
4XX:
$ref: '#/components/responses/ErrorResponseV2'
/v2/bills/{id}:
put:
description: 'Update an existing imported bill with the given `id`. If no bill
with the `id` exists, returns an error.
Only bills that were previously imported via the API can be updated.
Attempting to update a bill that was not imported via the API will result in an error.
**Document Upload**: You can upload a new document along with the bill data using multipart/form-data.
When using multipart, send the bill data fields directly and the file as `document`.
**VAT Handling**: If `total_vat_amount` is provided and greater than zero, the system
will automatically create a hidden VAT line item in addition to the provided line items.
**Note**: This is a full replacement operation. All fields unspecified will be
treated as if they were `null` and will be cleared on the bill.
**Required Configuration**: This endpoint requires the "Allow bills to be imported via public API"
company configuration to be enabled. Returns 403 Forbidden if not enabled.
'
summary: Update an existing imported bill
operationId: updateBillV2
tags:
- Bills
x-badges:
- name: V2
position: after
color: blue
- name: Beta
position: after
color: orange
parameters:
- name: id
description: The ID of the bill in the Vic system.
in: path
required: true
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/UpdateBillRequestV2'
responses:
'200':
$ref: '#/components/responses/UpdateBillResponseV2'
4XX:
$ref: '#/components/responses/ErrorResponseV2'
components:
schemas:
BillOfLadingNumberV2:
description: The bill of lading number.
type: object
required:
- bol_number
properties:
bol_number:
type: string
description: Bill of Lading number.
minLength: 1
maxLength: 255
example: BOL-123456
ReceiptMatchV2:
type: object
description: Represents a match between an invoice item and a purchase order receipt line.
properties:
invoice_item:
type: object
description: The invoice item in this receipt match.
properties:
id:
type: string
format: uuid
description: The UUID of the invoice item.
example: 550e8400-e29b-41d4-a716-446655440000
legacy_id:
type: string
description: The legacy ID of the invoice item.
example: '12345'
purchase_order_item:
type: object
description: The purchase order item in this receipt match.
properties:
id:
type: string
format: uuid
description: The UUID of the purchase order item.
example: 550e8400-e29b-41d4-a716-446655440001
receipt_line:
type: object
description: The receipt line in this receipt match.
properties:
id:
type: string
format: uuid
description: The UUID of the receipt line.
example: 550e8400-e29b-41d4-a716-446655440002
quantity_matched:
type:
- string
- 'null'
format: decimal
description: The quantity matched between the invoice and receipt line.
example: '10.50'
amount_matched:
type:
- string
- 'null'
format: decimal
description: The amount matched between the invoice and receipt line.
example: '105.00'
InternationalBankAccountInputV2:
type: object
description: International bank account information.
properties:
iban:
type:
- string
- 'null'
maxLength: 255
bic:
type:
- string
- 'null'
maxLength: 255
CreditAccountInputV2:
type: object
description: Credit account lookup information.
properties:
kid:
type:
- string
- 'null'
maxLength: 255
description: Payment reference (KID).
credit_account_remote_id:
type:
- string
- 'null'
maxLength: 255
credit_account_id:
type:
- string
- 'null'
maxLength: 255
PaymentMethod:
type: string
enum:
- ach
- card
- check
- wire
InvoiceLineItemVatInfoV2:
type: object
description: VAT/tax details for a line item.
properties:
vat_code:
type:
- string
- 'null'
maxLength: 255
vat_code_id:
type:
- string
- 'null'
maxLength: 255
vat_amount:
type:
- string
- 'null'
format: decimal
vat_rate:
type:
- string
- 'null'
format: decimal
InvoicePaymentInputV2:
type: object
description: Payment information for the bill.
properties:
bank_account_number:
type:
- string
- 'null'
maxLength: 255
bankgiro:
type:
- string
- 'null'
maxLength: 255
plusgiro:
type:
- string
- 'null'
maxLength: 255
bban:
type:
- string
- 'null'
maxLength: 255
default_method:
type:
- string
- 'null'
enum:
- bank_account
- bankgiro
- plusgiro
- iban
- bban
international_bank_account:
oneOf:
- $ref: '#/components/schemas/InternationalBankAccountInputV2'
- type: 'null'
InvoiceFieldInput:
type: object
required:
- label
properties:
label:
type: string
maxLength: 255
description: Field label/name.
example: Project Code
value:
type:
- string
- 'null'
maxLength: 255
description: 'Field value. For `text` fields any printable string is accepted.
For `select` fields the value must match one of the field''s
configured options. For `date` fields the value must be an
ISO 8601 calendar date (`YYYY-MM-DD`); empty strings clear the
stored value.
'
example: PRJ-2024-001
ErrorV2:
type: object
required:
- message
properties:
field:
description: 'The field that the error occurred on. This field may not always be
present.
'
oneOf:
- type: string
- type: 'null'
message:
description: A description of the error.
type: string
InvoiceExternalPaymentStatus:
type: string
enum:
- paid
- unpaid
- voided
UpdateBillV2:
description: Schema for updating an existing imported bill.
allOf:
- $ref: '#/components/schemas/BillInputV2'
BillLineItemInputV2:
type: object
description: Input schema for a bill line item.
required:
- amount
properties:
index:
type:
- integer
- 'null'
description: The line item index/position.
example: 1
amount:
type: string
format: decimal
description: The amount for this line item.
example: '100.00'
amount_tax:
type:
- string
- 'null'
format: decimal
description: The VAT or tax amount for this line item.
example: '20.00'
unit_price:
type:
- string
- 'null'
format: decimal
description: Price per unit for this line item.
example: '20.00'
tax_code_id:
type:
- string
- 'null'
format: uuid
description: The tax code identifier for this line item.
example: 550e8400-e29b-41d4-a716-446655440000
comment:
type:
- string
- 'null'
maxLength: 255
description: An internal comment for this line item.
example: Some internal note
description:
type:
- string
- 'null'
maxLength: 255
description: A description of the line item.
example: Office supplies
billable:
type:
- boolean
- 'null'
description: Whether this line item is billable.
default: false
cost_account_remote_id:
type:
- string
- 'null'
maxLength: 255
description: The external id of the cost account associated with this line item.
example: EXT-4000
quantity_invoiced:
type:
- string
- 'null'
format: decimal
description: The quantity invoiced for this line item.
example: '5.0'
line_item_is_vat_only:
type:
- boolean
- 'null'
description: Whether this line item is a VAT-only line.
default: false
number:
type:
- string
- 'null'
maxLength: 255
description: Line item number or SKU.
example: ITEM-001
line_type:
type:
- string
- 'null'
description: The type of line item.
enum:
- item
- expense
example: expense
accrual:
oneOf:
- $ref: '#/components/schemas/AccrualV2'
- type: 'null'
vat_info:
oneOf:
- $ref: '#/components/schemas/InvoiceLineItemVatInfoV2'
- type: 'null'
dimensions:
type: array
description: Dimensions to attach to this line item.
items:
$ref: '#/components/schemas/ReferenceDimensionV2'
default: []
BillV2:
type: object
description: Schema for a bill response containing complete bill information including line items and payment details.
properties:
id:
type: string
format: uuid
description: The UUID of the bill in the Vic system.
example: 550e8400-e29b-41d4-a716-446655440000
legacy_id:
type: string
description: The legacy ID of the bill (for backwards compatibility).
example: '12345'
ref_number:
type:
- string
- 'null'
description: The reference number that appears on the bill.
maxLength: 255
example: INV-2024-001
remote_id:
type:
- string
- 'null'
description: The external ID of the bill in your system.
example: remote-123
status:
type: string
description: The processing status of the bill in Vic.ai.
example: posted
transaction_type:
type: string
description: The type of transaction.
enum:
- invoice
- credit_note
example: invoice
ui_status:
description: 'The bill''s processing status as shown in the Vic.ai interface,
or `null` if it has not been computed yet.
'
oneOf:
- $ref: '#/components/schemas/InvoiceUiStatus'
- type: 'null'
vendor:
$ref: '#/components/schemas/SparseVendorV2'
company:
type: object
description: The company information.
properties:
id:
type: string
format: uuid
description: The UUID of the company in the Vic system.
name:
type: string
description: The company's name.
remote_id:
type:
- string
- 'null'
description: The external ID of the company.
example: company-123
currency:
type:
- string
- 'null'
description: The currency code the bill is in.
format: ISO-4217
maxLength: 3
example: USD
description:
type:
- string
- 'null'
description: Description of the bill.
maxLength: 255
example: Monthly service fee
issue_date:
type:
- string
- 'null'
format: date
description: The date the bill was issued.
example: '2024-01-15'
due_date:
type:
- string
- 'null'
format: date
description: The date the bill is due.
example: '2024-02-15'
gl_date:
type:
- string
- 'null'
format: date
description: The general ledger date.
example: '2024-01-15'
language:
type:
- string
- 'null'
description: The language of the bill.
maxLength: 2
example: en
line_items:
type: array
description: Line items for the bill. When line item grouping is enabled for your company, line items that share the same general ledger account and dimensions are combined into a single summary line. Custom line field values can additionally be included in the grouping so that lines whose custom line field values differ remain separate; contact Vic.ai support to enable this.
items:
$ref: '#/components/schemas/BillLineItemV2'
payment_info:
type: object
description: Payment information for the bill.
properties:
bank_account_number:
type:
- string
- 'null'
description: Bank account number.
example: '1234567890'
bic:
type:
- string
- 'null'
description: Bank Identifier Code.
example: DNBANOKKXXX
iban:
type:
- string
- 'null'
description: International Bank Account Number.
example: NO9386011117947
bankgiro:
type:
- string
- 'null'
description: Bankgiro number.
example: '123456789'
plusgiro:
type:
- string
- 'null'
description: Plusgiro number.
example: '123456789'
remote_updated_at:
type:
- string
- 'null'
format: date-time
description: When the bill was last updated in your system.
account_number:
type:
- string
- 'null'
description: Vendor account number used on the bill.
example: ACC-1001
amount_freight:
type:
- string
- 'null'
format: decimal
description: The freight amount for the bill.
example: '15.00'
amount_net:
type:
- string
- 'null'
format: decimal
description: The net amount excluding VAT, tax, and freight.
example: '100.00'
amount_sum:
type:
- string
- 'null'
format: decimal
description: The total amount including all taxes and fees.
example: '135.00'
amount_tax:
type:
- string
- 'null'
format: decimal
description: The total tax amount for the bill.
example: '20.00'
amount_vat:
type:
- string
- 'null'
format: decimal
description: The total VAT amount for the bill.
example: '20.00'
automated_at:
type:
- string
- 'null'
format: date-time
description: 'When the bill was selected for AutoPilot (full automation),
or `null` if it was never automated.
'
example: '2024-01-15T10:30:00Z'
bill_status:
type: string
description: The payment status of the bill.
enum:
- unpaid
- paid
- partially_paid
- overpaid
default: unpaid
example: unpaid
bol_numbers:
type: array
description: Bill of Lading numbers associated with the bill.
items:
$ref: '#/components/schemas/BillOfLadingNumberV2'
default: []
credit_account:
oneOf:
- $ref: '#/components/schemas/CostAccountV2'
- type: 'null'
document_url:
type:
- string
- 'null'
format: uri
description: URL to download the bill document/PDF.
example: https://example.com/documents/bill.pdf
external_payment_amount:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/MonetaryValue'
description: External payment amount as reported by the ERP system.
example: '1500.00'
external_payment_currency_id:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/Currency'
description: ISO 4217 currency code for the external payment.
external_payment_date:
type:
- string
- 'null'
format: date
description: The date when the bill was paid externally.
example: '2024-02-01'
external_payment_number:
oneOf:
- type: 'null'
- type: string
maxLength: 32
description: External payment reference number.
example: PAY-123456
external_payment_status:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/InvoiceExternalPaymentStatus'
description: External payment status.
external_payment_type:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/PaymentMethod'
example: ach
external_payment_source:
oneOf:
- type: 'null'
- type: string
maxLength: 255
description: The financial entity or bank account the payment was made from in the ERP system.
external_payment_total_paid:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/MonetaryValue'
description: Total amount actually paid in the ERP system.
fields:
type: array
description: Custom fields configured for the bill.
items:
type: object
properties:
label:
type: string
description: The field label.
example: Project Code
type:
type: string
description: The field type.
example: text
value:
type:
- string
- 'null'
description: The field value.
example: PRJ-2024-001
default: []
kid:
type:
- string
- 'null'
description: Customer identification (KID) number for payment reference.
example: '1234567890123'
marked_as:
type:
- string
- 'null'
description: Manual marking/status of the bill.
example: reviewed
matched_purchase_orders:
type: array
description: Matched Purchase Orders to the Bill.
items:
type: object
description: Matched Purchase Order details
properties:
internal_id:
description: The internal ID of the purchase order.
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
external_id:
description: The external ID of the purchase order.
type: string
maxLength: 255
po_number:
type: string
description: The po number of the purchase order.
default: []
payment_term_id:
type:
- string
- 'null'
format: uuid
description: The ID of the payment term.
example: 550e8400-e29b-41d4-a716-446655440000
payment_term:
type: object
description: Payment term information.
oneOf:
- type: object
description: Full payment term details.
properties:
id:
type: string
format: uuid
description: Payment term ID.
name:
type:
- string
- 'null'
description: Payment term name.
description:
type:
- string
- 'null'
description: Payment term description.
days_to_pay:
type:
- integer
- 'null'
description: Number of days to pay.
days_to_pay_condition:
type:
- string
- 'null'
description: Condition for days to pay.
discount_percentage:
type:
- string
- 'null'
format: decimal
description: Early payment discount percentage.
discount_days:
type:
- integer
- 'null'
description: Days for early payment discount.
discount_days_condition:
type:
- string
- 'null'
description: Condition for discount days.
remote_id:
type:
- string
- 'null'
description: External payment term ID.
- type: object
description: Simple payment term with only days.
properties:
days_to_pay:
type: integer
description: Number of days to pay.
po_number:
type:
- string
- 'null'
deprecated: true
description: 'Deprecated. Echoes the first element of
`purchase_order_numbers` (or `null` if no POs are associated)
for backward compatibility. New integrations should read the
full list from `purchase_order_numbers`.
'
example: PO-2024-001
purchase_order_numbers:
type: array
items:
type: string
maxLength: 255
description: 'List of purchase order numbers associated with the bill,
sorted by stable insertion order. Empty when no POs are
associated.
'
default: []
example:
- PO-1001
- PO-1002
posting_error:
type:
- string
- 'null'
description: Error message if posting to ERP failed.
example: Connection timeout
remote_data:
type: object
description: Additional remote system data.
additionalProperties: true
self_assessed_use_tax_account:
type:
- string
- 'null'
description: Self-assessed use tax account.
example: USE-TAX-001
self_assessed_use_tax_amount:
type:
- string
- 'null'
format: decimal
description: Self-assessed use tax amount.
example: '5.00'
service_period_end:
type:
- string
- 'null'
format: date
description: End of the service period.
example: '2024-01-31'
service_period_start:
type:
- string
- 'null'
format: date
description: Start of the service period.
example: '2024-01-01'
source:
type:
- string
- 'null'
description: Source of the bill (e.g., EHF for electronic invoices).
example: EHF
inserted_at:
type:
- string
format: date-time
description: When the bill was first created in Vic.ai.
example: '2024-01-15T10:30:00Z'
updated_at:
type:
- string
- 'null'
format: date-time
description: When the bill was last updated in Vic.ai.
example: '2024-01-15T10:30:00Z'
SparseVendorV2:
type: object
description: A minimal vendor representation containing basic identification and contact information.
properties:
id:
type: string
format: uuid
description: The id of the vendor in the Vic system.
example: 550e8400-e29b-41d4-a716-446655440000
legacy_id:
type: string
description: The legacy ID of the vendor. This is a legacy field and will be removed in the future.
example: '12345'
remote_id:
type:
- string
- 'null'
description: The external ID of the vendor.
example: vendor-123
name:
type:
- string
- 'null'
description: The vendor's name.
example: Acme Corp
org_number:
type:
- string
- 'null'
description: The vendor's organization number.
example: '987654321'
AccrualV2:
type: object
description: Accrual period configuration.
required:
- start
- count
- unit
properties:
start:
type: string
format: date
description: Accrual start date.
example: '2024-01-01'
count:
type: integer
description: Number of periods to spread over.
example: 12
unit:
type: string
enum:
- MONTHS
description: Time unit for accrual periods.
example: MONTHS
BillInputV2:
type: object
description: Base schema for bill input data containing common properties for both create and update operations.
required:
- ref_number
- vendor_remote_id
- transaction_type
- remote_updated_at
- remote_id
properties:
account_number:
type:
- string
- 'null'
description: Vendor account number used on the bill.
maxLength: 255
example: ACC-1001
ref_number:
type: string
description: The reference number that appears on the bill.
maxLength: 255
example: INV-2024-001
vendor_remote_id:
type: string
description: The external ID of the vendor in your system.
maxLength: 255
example: vendor-123
transaction_type:
type: string
description: The type of transaction.
enum:
- invoice
- credit_note
example: invoice
remote_updated_at:
type: string
format: date-time
description: When the bill was last updated in your system.
remote_id:
type: string
description: The external ID of the bill in your system.
maxLength: 255
example: remote-123
issue_date:
type:
- string
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vicai/refs/heads/main/openapi/vicai-bills-api-openapi.yml