Vic.ai Organizations API

openapi: 3.2.0
info:
  version: v10.40.4
  contact: {}
  title: Vic.ai Organizations 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: Organizations
  description: 'Organizations within the Vic system. The old name for this resource is

    Account Firm. We are transitioning to the name of Organization.'
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:
      - Organizations
      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:
      - Organizations
      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:
      - Organizations
      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}/users:
    get:
      description: List users attached to an organization.
      summary: List users attached to an organization
      operationId: listOrganizationUsersV2
      tags:
      - Organizations
      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
      - name: name
        description: The name of the user. This is a case-insensitive match.
        in: query
        schema:
          type: string
      - name: name_contains
        description: 'The name of the user contains the value specified. This is a

          case-insensitive match.

          '
        in: query
        schema:
          type: string
      - name: email
        description: 'The user has the email address. This is a case-insensitive match.

          '
        in: query
        schema:
          type: string
      - name: email_contains
        description: 'The email of the user contains the value specified. This is a

          case-insensitive match.

          '
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/PaginationV2'
      responses:
        '200':
          $ref: '#/components/responses/ListOrganizationUsersResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
    post:
      description: 'Create and attach a user to an organization. If the user already exists,

        use the `attachUserToOrganizationV2` (`POST /v2/organizations/{organization_id}/users/attach`)

        operation instead.'
      summary: Create and attach user to an organization
      operationId: createOrganizationUserV2
      tags:
      - Organizations
      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
      requestBody:
        $ref: '#/components/requestBodies/CreateOrganizationUserRequestV2'
      responses:
        '201':
          $ref: '#/components/responses/CreateOrganizationUserResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
  /v2/organizations/{organization_id}/users/attach:
    post:
      description: 'Attaches an existing user to an organization. You may provide the

        `user_id` or `email`. If the user does not exist, you will need to use

        the `createOrganizationUserV2` operation.'
      summary: Attach an existing user to an organization
      operationId: attachUserToOrganizationV2
      tags:
      - Organizations
      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
      requestBody:
        $ref: '#/components/requestBodies/AttachUserToOrganizationRequestV2'
      responses:
        '201':
          $ref: '#/components/responses/CreateOrganizationUserResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
  /v2/organizations/{organization_id}/users/{user_id}:
    delete:
      description: 'Removes the user from the organization. **NOTE**: This will remove the

        user from __ALL__ of the companies within the organization.'
      summary: Remove user from organization
      operationId: removeUserFromOrganizationV2
      tags:
      - Organizations
      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
      - name: user_id
        description: The ID of the user.
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          $ref: '#/components/responses/RemoveUserFromOrganizationResponseV2'
        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
    CreateUserV2:
      type: object
      required:
      - name
      - email
      properties:
        first_name:
          type: string
          description: The first name of the user.
        last_name:
          type: string
          description: The last name of the user.
        name:
          type: string
          description: The full preferred name of the user.
        phone_number:
          type: string
          description: 'The phone number the user is connected with. This is not required to

            be set. If provided, the phone number is validated.

            '
        email:
          type: string
          description: The User's email. Must be unique.
        timezone:
          $ref: '#/components/schemas/TimeZoneV2'
        language:
          $ref: '#/components/schemas/LanguageV2'
        address:
          $ref: '#/components/schemas/UserAddressV2'
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/UserMetadataEntryV2'
        date_of_birth:
          type: string
          format: date
          description: When the user was born.
    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.
    TimeZoneV2:
      type: string
      example: Etc/UTC
    UserAddressV2:
      type: object
      properties:
        street_1:
          type: string
        street_2:
          type: string
        city:
          type: string
        postal_code:
          type: string
        country:
          $ref: '#/components/schemas/CountryCode'
    UserManagerV2:
      description: A user's manager.
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: The manager's user ID.
        name:
          type: string
          description: The manager's full preferred name.
        email:
          type: string
          description: The manager's email.
    UserV2:
      description: A User attached to an organization.
      type: object
      required:
      - id
      - name
      - email
      properties:
        id:
          type: string
        legacy_id:
          type:
          - string
          - 'null'
          description: The Users's internal ID. This is a legacy field and will be removed in the future.
          example: '12345'
        first_name:
          type: string
          description: The first name of the user.
        last_name:
          type: string
          description: The last name of the user.
        name:
          type: string
          description: The full preferred name of the user.
        phone_number:
          type: string
          description: 'The phone number the user is connected with. This is not required to

            be set. If provided, the phone number is validated.

            '
        email:
          type: string
          description: The User's email. Must be unique.
        status:
          $ref: '#/components/schemas/UserStatusV2'
        timezone:
          $ref: '#/components/schemas/TimeZoneV2'
        language:
          $ref: '#/components/schemas/LanguageV2'
        address:
          $ref: '#/components/schemas/UserAddressV2'
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/UserMetadataEntryV2'
        date_of_birth:
          type: string
          format: date
          description: When the user was born.
        manager:
          description: 'The user''s manager (the user they are managed by), or `null` when

            no manager is set or when the manager is outside the scope of the

            request (for example, not a member of the requested company).

            '
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/UserManagerV2'
        created_at:
          type: string
          format: date-time
          description: When the user was created in Vic.
        updated_at:
          type: string
          format: date-time
          description: When the user was last updated in Vic.
    CountryCode:
      description: 'The ISO-3166 country code. The acceptable values are Alpha-2 codes.

        '
      type: string
      format: ISO-3166
      maxLength: 2
      example: US
    OrganizationUserMetaV2:
      type: object
      properties:
        user_id:
          description: The user the organization is attached to.
          type: string
          format: uuid
        organization_id:
          description: The organization the user is attached to.
          type: string
          format: :uuid
        created_at:
          description: When the user was added to the organization.
          type: string
          format: date-time
        updated_at:
          description: When the user's role was modified.
          type: string
          format: date-time
    LanguageV2:
      type: string
      description: The two letter code for the language used.
      example: en
    UserStatusV2:
      type: string
      description: The type of invoice item line.
      enum:
      - active
      - out_of_office
      default: active
    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
    UserMetadataEntryV2:
      type: object
      properties:
        name:
          type: string
          description: 'The name of the metadata entry. The name **MUST** be only lower case

            `a-z` and numbers `0-9`. The `_` character is allowed. The name

            *MUST** be unique in the set.

            '
          pattern: ^[a-z0-9_]+$
          example: job_title
        type:
          type: string
          enum:
          - string
          - boolean
          - integer
          - date
        value:
          type: string
          description: The value of the entry.
          example: Senior Manager
    AttachUserToOrganizationV2:
      type: object
      properties:
        user_id:
          description: 'The User''s id. Both can be provided. `user_id` takes higher

            precedence than `email`.

            '
          type: string
          format: uuid
        email:
          description: 'The existing User''s email. Both can be provided. `user_id` takes

            higher precedence than `email`.

            '
          type: string
        role:
          description: 'Optional organization-level role to grant the user when attaching.

            One of `user`, `admin`, `superadmin`, or `manager`. Defaults to

            `user`. Ignored when the user is already attached to the

            organization; an existing member keeps their current role.

            '
          type: string
          enum:
          - user
          - admin
          - superadmin
          - manager
          default: user
    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:
    AttachUserToOrganizationRequestV2:
      description: Attach an existing user to an organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AttachUserToOrganizationV2'
    CreateOrganizationUserRequestV2:
      description: Create a user and attach it to an organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateUserV2'
  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'
    CreateOrganizationUserResponseV2:
      description: User was created and attached to the organization successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationUserMetaV2'
    RemoveUserFromOrganizationResponseV2:
      description: 'The user was removed from the organization and companies successfully.

        '
    ListOrganizationUsersResponseV2:
      description: A successful list of users attached to an organization.
      content:
        application/json:
          schema:
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/PaginationMetaV2'
              data:
                type: array
                items:
                  $ref: '#/components/schemas/UserV2'
    GetOrganizationResponseV2:
      description: A single organization.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/OrganizationV2'
  parameters:
    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