Vic.ai Partners API

openapi: 3.2.0
info:
  version: v10.40.4
  contact: {}
  title: Vic.ai Partners 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: Partners
  description: 'Partner API for integration providers to provision new organizations

    and companies. Requires partner-level credentials obtained from Vic.'
paths:
  /v2/organizations:
    get:
      description: 'Search and list organizations accessible. Accepts both company-scoped

        tokens and partner tokens (obtained via `POST /v0/token` with the

        respective credentials). Partners see the organizations they created

        via `POST /v2/organizations` or were granted access to.'
      summary: Search and list organizations accessible
      operationId: listOrganizationsV2
      tags:
      - Partners
      x-badges:
      - name: V2
        position: after
        color: blue
      parameters:
      - name: name_contains
        description: 'List organizations with names containing the value provided. This is

          a case insensitive match.

          '
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/PaginationV2'
      responses:
        '200':
          $ref: '#/components/responses/ListOrganizationsResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
    post:
      description: 'Create a new organization. The organization is automatically linked to

        the authenticated partner client. Requires partner authentication

        (obtain a token via `POST /v0/token`).


        This endpoint creates only the organization. Create the first company

        under it as a separate step with

        `POST /v2/organizations/{organization_id}/companies` — the partner

        bootstrap path, which returns the new company''s company-scoped OAuth

        client. (`POST /v2/companies` also creates companies, but it derives the

        organization from the calling client''s existing primary company, so it

        cannot bootstrap the very first company under a brand-new organization.)'
      summary: Create an organization
      operationId: createOrganizationV2
      tags:
      - Partners
      x-badges:
      - name: V2
        position: after
        color: blue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationV2'
      responses:
        '201':
          description: Organization created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OrganizationV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
  /v2/organizations/{organization_id}:
    get:
      description: 'Get an organization. Accepts both company-scoped tokens and partner

        tokens (obtained via `POST /v0/token` with the respective

        credentials). The organization must be one the caller has access to —

        for partners, one they created via `POST /v2/organizations` or were

        granted access to. Useful for verifying an existing organization

        before creating companies under it.'
      summary: Get an organization
      operationId: getOrganizationV2
      tags:
      - Partners
      x-badges:
      - name: V2
        position: after
        color: blue
      parameters:
      - name: organization_id
        description: The ID of the Organization.
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          $ref: '#/components/responses/GetOrganizationResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
  /v2/organizations/{organization_id}/companies:
    post:
      description: 'Create a company under a specific organization, using partner

        authentication. The company is created under the organization named in

        the path — which must be one the authenticated partner client already

        has access to (e.g. one it created via `POST /v2/organizations`) — and

        any `organization_id` in the request body is ignored.


        The response includes the new company''s company-scoped OAuth client so

        the partner can bootstrap a company-level integration without a second

        round-trip; the `client_secret` is returned only at creation time and

        cannot be retrieved later.


        Use this to create the first company under a newly-created organization,

        where no company-scoped client exists yet to call `POST /v2/companies`.'
      summary: Create a company under an organization
      operationId: createOrganizationCompanyV2
      tags:
      - Partners
      x-badges:
      - name: V2
        position: after
        color: blue
      parameters:
      - name: organization_id
        description: The ID of the organization to create the company under.
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        $ref: '#/components/requestBodies/CreateCompanyRequestV2'
      responses:
        '201':
          $ref: '#/components/responses/CreateCompanyResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
  /v2/companies/{company_id}/tags:
    get:
      description: 'List the tags assigned to a company. Requires partner authentication;

        the company must belong to an organization the partner can access.'
      summary: List a company's tags
      operationId: listCompanyTagsV2
      tags:
      - Partners
      x-badges:
      - name: V2
        position: after
        color: blue
      parameters:
      - name: company_id
        description: The ID (UUID) of the company.
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The company's tags.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyTagV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
    post:
      description: 'Assign a tag to a company, using partner authentication. The company

        must belong to an organization the partner can access.


        Tags are how Vic expresses **company grouping**: mark the parent company

        of a group with the `group-leader` tag and a shared `group:` tag,

        and mark each member company with the same `group:` tag. Assigning

        a `group:`/`group-leader` tag also enables company groups on the

        organization. Re-assigning an existing tag is idempotent.'
      summary: Assign a tag to a company
      operationId: createCompanyTagV2
      tags:
      - Partners
      x-badges:
      - name: V2
        position: after
        color: blue
      parameters:
      - name: company_id
        description: The ID (UUID) of the company.
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompanyTagV2'
      responses:
        '201':
          description: The assigned tag.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CompanyTagV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
  /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:
      - Partners
      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:
      - Partners
      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:
  schemas:
    OrganizationV2:
      type: object
      required:
      - id
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateOrganizationV2:
      type: object
      required:
      - name
      - billing_timezone
      properties:
        name:
          type: string
          description: Display name for the organization.
        billing_timezone:
          type: string
          description: IANA timezone identifier.
          example: America/New_York
        remote_id:
          type: string
          description: External identifier from the partner's system.
    CompanyTagV2:
      type: object
      required:
      - tag
      properties:
        tag:
          type: string
          description: The tag value assigned to the company.
          example: group:acme
    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
    CreateCompanyV2:
      type: object
      required:
      - name
      - country_code
      - billing_timezone
      properties:
        name:
          type: string
          description: The display name for the company.
        country_code:
          type: string
          description: Two-letter ISO 3166-1 alpha-2 country code.
          minLength: 2
          maxLength: 2
          example: US
        billing_timezone:
          type: string
          description: IANA timezone identifier used for billing dates.
          example: America/New_York
        legal_name:
          type: string
          description: The legal entity name, if different from the display name.
        doing_business_as:
          type: string
          description: Trade name or DBA.
        remote_id:
          type: string
          description: An external identifier from the integration partner's system.
        org_number:
          type: string
          description: Organization/registration number.
        organization_id:
          type: string
          format: uuid
          description: 'The organization (accounting firm) to place the company under.

            Defaults to the OAuth client''s primary company organization.

            Must be an organization the client already has access to.

            '
    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
    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
    CreatedCompanyV2:
      type: object
      description: 'Sparse company payload returned at company creation time (by

        `POST /v2/companies` or `POST /v2/organizations/{organization_id}/companies`).

        It carries the same identifier fields as `CompanyV2` plus a

        company-scoped OAuth client; the `client_secret` is exposed only at

        creation time and cannot be retrieved later.

        '
      required:
      - id
      - oauth_client
      properties:
        id:
          type: string
        name:
          type: string
        organization_id:
          description: The organization (accounting firm) the company belongs to.
          oneOf:
          - type: 'null'
          - type: string
            format: uuid
        remote_id:
          description: The company's id in the ERP system if applicable.
          oneOf:
          - type: 'null'
          - type: string
        updated_at:
          type: string
          format: date-time
        oauth_client:
          type: object
          description: 'Company-scoped OAuth client generated alongside the company.

            Returned only on creation.

            '
          required:
          - client_id
          - client_secret
          properties:
            client_id:
              type: string
            client_secret:
              type: string
    CreateCompanyTagV2:
      type: object
      required:
      - tag
      properties:
        tag:
          type: string
          description: 'The tag to assign. For grouping, use `group-leader` on the parent

            company and a shared `group:<key>` tag on the parent and every

            member.

            '
          example: group:acme
    PaginationMetaV2:
      type: object
      properties:
        cursor:
          description: 'The cursor to the next page of data. If it is null, that means there

            is no more data to fetch.

            '
          oneOf:
          - type: string
          - type: 'null'
    PaginationV2:
      type: object
      properties:
        size:
          type: integer
          description: The page size.
          maximum: 50
          minimum: 1
        cursor:
          type: string
          description: The cursor to use to get the next page of results.
  requestBodies:
    CreateCompanyRequestV2:
      description: Create a new company.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateCompanyV2'
    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'
  responses:
    ListOrganizationsResponseV2:
      description: A successful list of organizations
      content:
        application/json:
          schema:
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/PaginationMetaV2'
              data:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationV2'
    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'
    CompanySettingsResponseV2:
      description: The effective settings map for the company.
      content:
        application/json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                $ref: '#/components/schemas/CompanySettingsV2'
    CreateCompanyResponseV2:
      description: 'A single newly-created company including a company-scoped OAuth

        client. The `client_secret` is exposed only at creation time and

        cannot be retrieved later.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/CreatedCompanyV2'
    GetOrganizationResponseV2:
      description: A single organization.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/OrganizationV2'
  parameters:
    CompanyId:
      name: company_id
      in: path
      required: true
      description: The ID of the company
      schema:
        type: string
        format: uuid
    PaginationV2:
      name: page
      in: query
      schema:
        $ref: '#/components/schemas/PaginationV2'
  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