Vic.ai Company Settings API

openapi: 3.2.0
info:
  version: v10.40.4
  contact: {}
  title: Vic.ai Company Settings 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: Company Settings
  description: 'Per-company configuration options that an integration partner

    can read and tune programmatically rather than by asking

    Vic.ai support. Requires partner authentication (obtain a

    token via `POST /v0/token` with partner credentials); the

    partner must have provisioned or been linked to the company.

    The settings response is a flat map of field name to value;

    PATCH applies a partial update and is atomic — either the full

    update succeeds or no changes are persisted.'
paths:
  /v2/companies/{company_id}/settings:
    parameters:
    - $ref: '#/components/parameters/CompanyId'
    get:
      description: 'Returns the company''s current configuration as a flat map. Every

        available setting is present in the response with either the

        company''s configured value or the default. Enum values are

        returned as strings.


        Requires partner authentication (obtain a token via

        `POST /v0/token` with partner credentials); the partner must

        have provisioned or been linked to the company.'
      summary: Get company settings
      operationId: getCompanySettingsV2
      tags:
      - Company Settings
      x-badges:
      - name: V2
        position: after
        color: blue
      responses:
        '200':
          $ref: '#/components/responses/CompanySettingsResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
    patch:
      description: 'Applies a partial settings update. The request body is a flat map

        of setting name to value; only fields included in the body are

        modified. Unknown field names and type-invalid values are

        rejected with a 422 error listing every offending field.


        Updates are atomic: either every change in the request is

        applied, or none are. On success the full refreshed settings map

        is returned.


        Requires partner authentication (obtain a token via

        `POST /v0/token` with partner credentials); the partner must

        have provisioned or been linked to the company.'
      summary: Update company settings
      operationId: updateCompanySettingsV2
      tags:
      - Company Settings
      x-badges:
      - name: V2
        position: after
        color: blue
      requestBody:
        $ref: '#/components/requestBodies/UpdateCompanySettingsRequestV2'
      responses:
        '200':
          $ref: '#/components/responses/CompanySettingsResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
components:
  parameters:
    CompanyId:
      name: company_id
      in: path
      required: true
      description: The ID of the company
      schema:
        type: string
        format: uuid
  schemas:
    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
    CompanySettingsV2:
      type: object
      description: 'A company''s configuration options. Every available setting is

        always present in the response. Enum values are returned as

        strings; booleans as booleans. `null` means the field has no

        configured value and the caller should treat it as "unset"

        rather than "false".

        '
      required:
      - backend_mode
      - approval_flow_engine_enabled
      - approval_flow_engine_user_edits_allowed
      - invoice_automation_enabled
      - invoice_automated_next_step
      - invoice_approval_next_step
      - po_invoice_automation_enabled
      - po_invoice_automated_next_step
      - po_invoice_approval_next_step
      - purchase_order_matching
      - purchase_order_matching_level
      - purchase_order_require_matching_to_post
      - aaf_ignores_po_invoice_items
      - enable_posting
      - tax_handling
      - freight_handling
      properties:
        backend_mode:
          description: 'Backend processing mode for the company. Production

            companies should use `default`. Non-default values are

            reserved for demo and sandbox environments and should not

            be set on production companies.

            '
          type: string
          enum:
          - default
          - stub
        approval_flow_engine_enabled:
          description: 'Master switch for the approval flow engine. Must be `true`

            for automatically generated approval steps to be created on

            the company''s invoices.

            '
          type: boolean
        approval_flow_engine_user_edits_allowed:
          description: 'Allow end users to edit automatically generated approval

            steps on an individual invoice.

            '
          type: boolean
        invoice_automation_enabled:
          description: 'When `true` combined with `invoice_automated_next_step`,

            non-PO invoices auto-advance once analysis finishes.

            '
          type: boolean
        invoice_automated_next_step:
          description: 'The next action to take automatically once analysis finishes

            on a non-PO invoice. `null` disables auto-advancement.

            '
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - start_approval
            - post
            - export
            - submit
        invoice_approval_next_step:
          description: 'The next action to take automatically once approval completes

            on a non-PO invoice. `null` disables auto-advancement.

            '
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - post
            - export
            - submit
        po_invoice_automation_enabled:
          description: 'When `true` combined with `po_invoice_automated_next_step`,

            PO-matched invoices auto-advance once analysis finishes.

            '
          type: boolean
        po_invoice_automated_next_step:
          description: 'The next action to take automatically once analysis finishes

            on a PO-matched invoice. `null` disables auto-advancement.

            '
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - start_approval
            - post
        po_invoice_approval_next_step:
          description: 'The next action to take automatically once approval completes

            on a PO-matched invoice, independent of

            `invoice_approval_next_step` (which covers non-PO invoices).

            `null` disables auto-advancement for PO-matched invoices.

            '
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - post
            - export
            - submit
        purchase_order_matching:
          description: 'Purchase-order matching mode. `none` disables PO matching

            entirely; `standard`, `implicit`, and `explicit` select

            different matching strategies.

            '
          type: string
          enum:
          - none
          - standard
          - implicit
          - explicit
        purchase_order_matching_level:
          description: 'Granularity of PO matching: `line` matches invoice lines

            against PO lines; `document` groups lines at the PO level.

            '
          type: string
          enum:
          - document
          - line
        purchase_order_require_matching_to_post:
          description: 'When `true`, an invoice cannot be posted until every item

            line is matched to a PO line.

            '
          type: boolean
        aaf_ignores_po_invoice_items:
          description: 'When `true` (the default), approval flow rules evaluating

            against an invoice''s total amount sum only expense lines,

            excluding PO-matched item lines (which are covered by the

            PO matching approval path instead). Set to `false` to have

            those rules evaluate against the full invoice total

            including PO-matched items.

            '
          type: boolean
        enable_posting:
          description: 'Gates the post-approval posting action in the UI and the

            corresponding API endpoints. Defaults to `false` on new

            companies so the ERP integration can be verified before

            invoices are pushed out.

            '
          type: boolean
        tax_handling:
          description: 'How invoice tax is computed and allocated across lines.

            '
          type: string
          enum:
          - none
          - tax_engine
          - tax_codes
          - tax_expense_line
          - vat_for_po_invoices
          - tax_allocation
        freight_handling:
          description: 'How freight charges are allocated across lines. `null`

            disables automatic freight handling.

            '
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - expense_line
            - even_allocation
            - weighted_allocation
    UpdateCompanySettingsV2:
      type: object
      description: 'Partial update for company settings. All fields are optional; only

        fields included in the body are modified. Shape and types mirror

        `CompanySettingsV2`. Unknown fields and invalid values produce a

        422 error listing every offending key.

        '
      properties:
        backend_mode:
          type: string
          enum:
          - default
          - stub
        approval_flow_engine_enabled:
          type: boolean
        approval_flow_engine_user_edits_allowed:
          type: boolean
        invoice_automation_enabled:
          type: boolean
        invoice_automated_next_step:
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - start_approval
            - post
            - export
            - submit
        invoice_approval_next_step:
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - post
            - export
            - submit
        po_invoice_automation_enabled:
          type: boolean
        po_invoice_automated_next_step:
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - start_approval
            - post
        po_invoice_approval_next_step:
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - post
            - export
            - submit
        purchase_order_matching:
          type: string
          enum:
          - none
          - standard
          - implicit
          - explicit
        purchase_order_matching_level:
          type: string
          enum:
          - document
          - line
        purchase_order_require_matching_to_post:
          type: boolean
        aaf_ignores_po_invoice_items:
          type: boolean
        enable_posting:
          type: boolean
        tax_handling:
          type: string
          enum:
          - none
          - tax_engine
          - tax_codes
          - tax_expense_line
          - vat_for_po_invoices
          - tax_allocation
        freight_handling:
          oneOf:
          - type: 'null'
          - type: string
            enum:
            - expense_line
            - even_allocation
            - weighted_allocation
  responses:
    CompanySettingsResponseV2:
      description: The effective settings map for the company.
      content:
        application/json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                $ref: '#/components/schemas/CompanySettingsV2'
    ErrorResponseV2:
      description: An unexpected error has occurred. Check the body for more details.
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorV2'
  requestBodies:
    UpdateCompanySettingsRequestV2:
      description: 'Partial update to the company settings map. Only fields

        included in the body are modified.

        '
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateCompanySettingsV2'
  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