Arcadia Business Units API

openapi: 3.2.0
info:
  description: Plug API
  title: Plug Business Units API
  version: 2.0.0
servers:
- url: https://api.arcadia.com
security:
- OAuth2: []
tags:
- name: Business Units
paths:
  /businessUnits:
    get:
      description: Returns a paginated list of Business Units within the caller's organization, scoped to the Business Units the caller is permitted to access.
      operationId: list-business-units
      parameters:
      - description: 'A search query string. See [this page](ref:searching) for more information.


          The searchable fields for this endpoint are:

          - `createdAt`

          - `createdBy`

          - `id`

          - `lastModifiedAt`

          - `lastModifiedBy`

          - `name`

          - `parentId`

          - `sandboxWebhookUrl`

          - `uniqueId`

          - `webhookUrl`'
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: A global search query string. See [this page](ref:searching#global-search) for more information.
        in: query
        name: globalSearch
        required: false
        schema:
          type: string
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPagedPlugBusinessUnitResource'
          description: OK
      summary: List Business Units
      tags:
      - Business Units
    post:
      description: Creates a new Business Unit as a child of the specified parent Business Unit.
      operationId: create-business-unit
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicBusinessUnitCreateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPlugBusinessUnitResource'
          description: OK
      summary: Create Business Unit
      tags:
      - Business Units
      parameters:
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
  /businessUnits/{businessUnitId}:
    delete:
      description: Deletes a Business Unit. Any accounts assigned to it are moved to the Business Unit specified by `moveAccountsToBusinessUnitId`, or to its parent if that parameter is omitted.
      operationId: delete-business-unit
      parameters:
      - in: path
        name: businessUnitId
        required: true
        schema:
          type: string
      - description: The Business Unit to move the deleted Business Unit's accounts to. Defaults to the deleted Business Unit's parent if omitted.
        in: query
        name: moveAccountsToBusinessUnitId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          description: OK
      summary: Delete Business Unit
      tags:
      - Business Units
    get:
      description: Returns a single Business Unit along with the IDs of its ancestors and the full tree of its descendants.
      operationId: retrieve-business-unit
      parameters:
      - in: path
        name: businessUnitId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPlugBusinessUnitTreeResource'
          description: OK
      summary: Retrieve Business Unit
      tags:
      - Business Units
    patch:
      description: Partially updates a Business Unit. Only the fields supplied in the request body are changed; omitted fields are left as-is.
      operationId: update-business-unit
      parameters:
      - in: path
        name: businessUnitId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessUnitPatchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPlugBusinessUnitResource'
          description: OK
      summary: Update Business Unit
      tags:
      - Business Units
  /businessUnits/{businessUnitId}/events:
    get:
      description: Returns a paginated list of the change events recorded against a single Business Unit, such as creation and field updates.
      operationId: list-business-unit-events
      parameters:
      - in: path
        name: businessUnitId
        required: true
        schema:
          type: string
      - description: 'A search query string. See [this page](ref:searching) for more information.


          The searchable fields for this endpoint are: createdAt, eventType, fieldName'
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPagedPlugBusinessUnitEventResource'
          description: OK
      summary: List Business Unit Events
      tags:
      - Business Units
  /plug/businessUnits/{businessUnitId}/events:
    get:
      description: Account-level Business Unit assignment and unassignment history for a Business Unit the caller has access to.
      operationId: list-business-unit-assignment-events
      parameters:
      - in: path
        name: businessUnitId
        required: true
        schema:
          type: string
      - description: 'A search query string. See [this page](ref:searching) for more information.


          The searchable fields for this endpoint are:

          - `createdAt`

          - `eventType`'
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPublicBusinessUnitEventResource'
          description: Successfully retrieved Business Unit events
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPublicBusinessUnitEventResource'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPublicBusinessUnitEventResource'
          description: Forbidden — caller does not have access to this Business Unit
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPublicBusinessUnitEventResource'
          description: Business Unit not found
      summary: List Business Unit Assignment Events
      tags:
      - Business Units
components:
  schemas:
    PublicPagedPlugBusinessUnitEventResource:
      required:
      - businessUnitEvents
      - page
      type: object
      properties:
        businessUnitEvents:
          type: array
          description: An array of business unit event objects.
          items:
            $ref: '#/components/schemas/PublicPlugBusinessUnitEventResource'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedPublicBusinessUnitEventResource:
      type: object
      properties:
        businessUnitEvents:
          type: array
          description: Account-level Business Unit assignment events for the requested Business Unit.
          items:
            $ref: '#/components/schemas/PublicBusinessUnitEventResource'
        page:
          $ref: '#/components/schemas/PageMetadata'
      required:
      - businessUnitEvents
      - page
    PublicBusinessUnitEventResource:
      type: object
      description: An account-level Business Unit assignment event.
      properties:
        accountId:
          type:
          - string
          - 'null'
          description: Identifier of the affected account.
        createdAt:
          type: string
          format: date-time
          description: When the event was recorded.
        effectiveAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the assignment change took effect.
        eventType:
          type: string
          description: Whether the BU was assigned to or unassigned from the account.
          enum:
          - BUSINESS_UNIT_ASSIGNED
          - BUSINESS_UNIT_UNASSIGNED
        id:
          type: string
          description: Unique identifier for the event.
          readOnly: true
      required:
      - accountId
      - createdAt
      - effectiveAt
      - eventType
      - id
    BusinessUnitPatchRequest:
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 1
          type:
          - string
          - 'null'
          description: The new name of the Business Unit. Omit to leave unchanged.
        parentId:
          pattern: ^([A-Za-z]{2,3}_)?(\d+|[A-Fa-f0-9]{8}-?[A-Fa-f0-9]{4}-?[A-Fa-f0-9]{4}-?[A-Fa-f0-9]{4}-?[A-Fa-f0-9]{12})$
          type:
          - string
          - 'null'
          description: The unique identifier of the new parent Business Unit. Omit to leave unchanged.
        sandboxWebhookUrl:
          maxLength: 255
          minLength: 0
          pattern: ^$|^http(s)?://(.)*$
          type:
          - string
          - 'null'
          description: The new URL where webhooks for sandbox entities associated with this Business Unit will be sent. Omit to leave unchanged, or supply an empty string to clear it. Must not match the sandbox webhook URL of any ancestor or descendant Business Unit.
        webhookUrl:
          maxLength: 255
          minLength: 0
          pattern: ^$|^http(s)?://(.)*$
          type:
          - string
          - 'null'
          description: The new URL where webhooks for live entities associated with this Business Unit will be sent. Omit to leave unchanged, or supply an empty string to clear it. Must not match the webhook URL of any ancestor or descendant Business Unit.
    PublicPlugBusinessUnitTreeResource:
      required:
      - ancestorBusinessUnitIds
      - children
      - createdAt
      - createdBy
      - id
      - lastModifiedAt
      - lastModifiedBy
      - name
      - sandboxWebhookUrl
      - uniqueId
      - webhookUrl
      type: object
      properties:
        ancestorBusinessUnitIds:
          type: array
          description: An array of IDs for the ancestors of the Business Unit, starting with its immediate parent and ending with the root Business Unit.
          items:
            type: string
            description: An array of IDs for the ancestors of the Business Unit, starting with its immediate parent and ending with the root Business Unit.
        children:
          type: array
          description: An array of resources of the immediate children of the Business Unit, which recursively includes all descendants.
          items:
            $ref: '#/components/schemas/PublicPlugBusinessUnitTreeResource'
        createdAt:
          type: string
          description: A timestamp indicating when the resource was created.
          format: date-time
        createdBy:
          type: string
          description: User or system responsible for creating the entity.
        id:
          type: string
          description: A unique identifier for the entity.
        lastModifiedAt:
          type: string
          description: The timestamp indicating when this resource was last modified.
          format: date-time
        lastModifiedBy:
          type: string
          description: The user or system that last modified this resource.
        name:
          type:
          - string
          - 'null'
          description: The name of the Business Unit. `null` for business units outside the caller's scope.
        sandboxWebhookUrl:
          type:
          - string
          - 'null'
          description: The URL where webhooks for sandbox entities associated with this Business Unit will be sent.
        uniqueId:
          type: string
          description: A secondary unique identifier for the Business Unit used in the Connect link.
        webhookUrl:
          type:
          - string
          - 'null'
          description: The URL where webhooks for live entities associated with this Business Unit will be sent.
    PublicPagedPlugBusinessUnitResource:
      required:
      - businessUnits
      - page
      type: object
      properties:
        businessUnits:
          type: array
          description: An array of business unit objects.
          items:
            $ref: '#/components/schemas/PublicPlugBusinessUnitResource'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PublicPlugBusinessUnitEventResource:
      required:
      - businessUnitId
      - createdAt
      - createdBy
      - eventType
      - fieldName
      - id
      - newValue
      - oldValue
      type: object
      properties:
        businessUnitId:
          type: string
          description: The unique identifier of the Business Unit this event was recorded against.
        createdAt:
          type: string
          description: A timestamp indicating when the event occurred.
          format: date-time
        createdBy:
          type: string
          description: User or system responsible for the event.
        eventType:
          type: string
          description: The type of event, indicating whether the Business Unit was created or updated.
          enum:
          - CREATED
          - UPDATED
        fieldName:
          type:
          - string
          - 'null'
          description: The name of the field that was changed. `null` for creation events.
        id:
          type: string
          description: A unique identifier for the event.
        newValue:
          type:
          - string
          - 'null'
          description: The value of the field after the change. `null` for creation events.
        oldValue:
          type:
          - string
          - 'null'
          description: The value of the field before the change. `null` for creation events.
      description: An array of business unit event objects.
    PageMetadata:
      required:
      - number
      - size
      - totalElements
      - totalPages
      type: object
      properties:
        number:
          type: integer
          format: int64
        size:
          type: integer
          format: int64
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int64
      description: Specifies which page of results to return; this is 0-indexed
    PublicPlugBusinessUnitResource:
      required:
      - ancestorBusinessUnitIds
      - childBusinessUnitIds
      - createdAt
      - createdBy
      - id
      - lastModifiedAt
      - lastModifiedBy
      - name
      - sandboxWebhookUrl
      - uniqueId
      - webhookUrl
      type: object
      properties:
        ancestorBusinessUnitIds:
          type: array
          description: An array of IDs for the ancestors of the Business Unit, starting with its immediate parent and ending with the root Business Unit.
          items:
            type: string
            description: An array of IDs for the ancestors of the Business Unit, starting with its immediate parent and ending with the root Business Unit.
        childBusinessUnitIds:
          type: array
          description: An array of IDs for only the immediate children of the Business Unit.
          items:
            type: string
            description: An array of IDs for only the immediate children of the Business Unit.
        createdAt:
          type: string
          description: A timestamp indicating when the resource was created.
          format: date-time
        createdBy:
          type: string
          description: User or system responsible for creating the entity.
        id:
          type: string
          description: A unique identifier for the entity.
        lastModifiedAt:
          type: string
          description: The timestamp indicating when this resource was last modified.
          format: date-time
        lastModifiedBy:
          type: string
          description: The user or system that last modified this resource.
        name:
          type:
          - string
          - 'null'
          description: The name of the Business Unit. `null` for business units outside the caller's scope.
        sandboxWebhookUrl:
          type:
          - string
          - 'null'
          description: The URL where webhooks for sandbox entities associated with this Business Unit will be sent.
        uniqueId:
          type: string
          description: A secondary unique identifier for the Business Unit used in the Connect link.
        webhookUrl:
          type:
          - string
          - 'null'
          description: The URL where webhooks for live entities associated with this Business Unit will be sent.
    PublicBusinessUnitCreateRequest:
      required:
      - name
      - parentId
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 0
          type: string
          description: The name of the Business Unit.
        parentId:
          minLength: 1
          pattern: ^([A-Za-z]{2,3}_)?(\d+|[A-Fa-f0-9]{8}-?[A-Fa-f0-9]{4}-?[A-Fa-f0-9]{4}-?[A-Fa-f0-9]{4}-?[A-Fa-f0-9]{12})$
          type: string
          description: The unique identifier of the parent Business Unit.
        sandboxWebhookUrl:
          maxLength: 255
          minLength: 0
          type:
          - string
          - 'null'
          description: The URL where webhooks for sandbox entities associated with this Business Unit will be sent. Must not match the sandbox webhook URL of any ancestor or descendant Business Unit.
        webhookUrl:
          maxLength: 255
          minLength: 0
          type:
          - string
          - 'null'
          description: The URL where webhooks for live entities associated with this Business Unit will be sent. Must not match the webhook URL of any ancestor or descendant Business Unit.
  parameters:
    arcVersionInHeaderParam:
      name: Arcadia-Version
      in: header
      example: '2024-02-21'
      description: The Arcadia-Version for the request
      required: true
      schema:
        type: string
        default: '2024-02-21'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: This API uses OAuth2 with the client credentials flow using the ['Create an Access Token'](ref:create-access-token) endpoint. API keys can be retrieved from the [Dashboard](https://dashboard.arcadia.com/).
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /oauth2/token
x-provenance:
  method: harvested
  publisher: Arcadia
  source: https://docs.arcadia.com/openapi/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)