openapi: 3.0.1
info:
  title: Smokeball Activity Codes Layout Matter Items API
  version: '1.0'
  description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
  contact:
    name: Smokeball Developer Support
    url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
  x-api-id: smokeball
  x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
  token: []
tags:
- name: Layout Matter Items
paths:
  /matters/{matterId}/layouts:
    get:
      tags:
      - Layout Matter Items
      summary: Get layouts
      description: Returns a collection of layout items on a specified matter.
      operationId: GetLayoutMatterItems
      parameters:
      - name: matterId
        in: path
        description: Matter Id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a 'LayoutMatterItemDataCollection' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayoutMatterItemDataCollection'
    post:
      tags:
      - Layout Matter Items
      summary: Add a new layout
      description: Adds a new layout matter item to a matter.
      operationId: AddLayout
      parameters:
      - name: matterId
        in: path
        description: Matter ID
        required: true
        schema:
          type: string
          format: uuid
      - name: skipFieldValidation
        in: query
        schema:
          type: boolean
          default: false
      requestBody:
        description: Layout matter item to add
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutMatterItemData'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutMatterItemData'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutMatterItemData'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the layout item to be created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When the new matter item contain invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When the matter or a layout item with the specified ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/layouts/{itemId}:
    get:
      tags:
      - Layout Matter Items
      summary: Get a layout
      description: Retrieves a layout item on a specified matter.
      operationId: GetLayoutMatterItemById
      parameters:
      - name: matterId
        in: path
        description: Matter Id
        required: true
        schema:
          type: string
          format: uuid
      - name: itemId
        in: path
        description: Layout item Id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a 'LayoutMatterItem' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayoutMatterItem'
        '404':
          description: When a layout item with the specified ID does not exist on the matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    patch:
      tags:
      - Layout Matter Items
      summary: Merge a layout
      description: Merges layout data.
      operationId: MergeLayout
      parameters:
      - name: matterId
        in: path
        description: Matter ID
        required: true
        schema:
          type: string
          format: uuid
      - name: itemId
        in: path
        description: Matter item Id
        required: true
        schema:
          type: string
          format: uuid
      - name: skipFieldValidation
        in: query
        description: Used to skip the field validation, may be needed for Smokeball data split migrations
        schema:
          type: boolean
          default: false
      requestBody:
        description: Data to merge into the existing layout
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutMatterItemApiPatch'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutMatterItemApiPatch'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutMatterItemApiPatch'
      responses:
        '202':
          description: When the request is accepted. Returns a hypermedia 'Link' object of the layout item to be updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When the update payload does not contain an ID that matched the ID of the item requiring update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When the matter or a layout item with the specified ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Layout Matter Items
      summary: Remove a layout
      description: Removes a layout matter item from a matter.
      operationId: RemoveLayout
      parameters:
      - name: matterId
        in: path
        description: Matter ID
        required: true
        schema:
          type: string
          format: uuid
      - name: itemId
        in: path
        description: Layout matter item ID to remove
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: When request is accepted.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When the matter or a layout item with the specified ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/layouts/{itemId}/contacts:
    get:
      tags:
      - Layout Matter Items
      summary: Get layout contacts
      description: Returns a list of contacts on a specified layout.
      operationId: GetLayoutMatterItemContacts
      parameters:
      - name: matterId
        in: path
        description: ''
        required: true
        schema:
          type: string
          format: uuid
      - name: itemId
        in: path
        description: ''
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a list of 'LayoutContact' objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LayoutContact'
        '404':
          description: When contacts do not exist for the layout item with specified id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      tags:
      - Layout Matter Items
      summary: Add a contact to a layout
      description: Adds a new contact on a specified layout.
      operationId: AddLayoutMatterItemContact
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: itemId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutContactData'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutContactData'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/LayoutContactData'
      responses:
        '202':
          description: When request is accepted
        '404':
          description: When layout item with specified id does not exist on the matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Layout Matter Items
      summary: Remove a contact from a layout
      description: Removes a contact from a specified layout, deleting the associated role or relationship from the matter.
      operationId: RemoveLayoutMatterItemContact
      parameters:
      - name: matterId
        in: path
        description: Matter Id
        required: true
        schema:
          type: string
          format: uuid
      - name: itemId
        in: path
        description: ItemId of the layout
        required: true
        schema:
          type: string
          format: uuid
      - name: key
        in: query
        description: Layout contact key identifying the contact to remove.
        schema:
          type: string
      responses:
        '202':
          description: When request is accepted.
        '404':
          description: When the layout item does not exist on the matter or no contact is assigned at the specified key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    LayoutMatterItem:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        name:
          type: string
          description: Name of the layout item.
          nullable: true
          example: Item
        description:
          type: string
          description: Brief description of the layout item.
          nullable: true
          example: Text describing item
        itemId:
          type: string
          description: Unique identifier for the layout item.
          format: uuid
          example: 59791902-6280-471b-bd18-f8439ba3042f
        parentId:
          type: string
          description: Unique identifier for the parent layout design.
          nullable: true
          example: Client
        index:
          type: integer
          description: Zero-based index of the layout item.
          format: int32
          example: 0
        parentIndex:
          type: integer
          description: Zero-based index of the parent layout matter item, if one exists.
          format: int32
          nullable: true
          example: 0
        layoutDesign:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the layout design.
          nullable: true
        values:
          type: array
          items:
            $ref: '#/components/schemas/LayoutValue'
          description: List of layout values.
          nullable: true
        events:
          type: array
          items:
            $ref: '#/components/schemas/LayoutEvent'
          description: List of layout events.
          nullable: true
      additionalProperties: false
    LayoutContact:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        key:
          type: string
          description: Unique key name for the layout contact.
          nullable: true
          example: ''
        contact:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the layout contact.
          nullable: true
      additionalProperties: false
    LayoutMatterItemApiPatch:
      type: object
      properties:
        itemId:
          type: string
          description: Unique identifier for the matter list item.
          nullable: true
          example: 59791902-6280-471b-bd18-f8439ba3042f
        layoutDesignId:
          type: string
          description: Identifier of the layout design.
          nullable: true
          example: 414ab774-adce-4659-b18c-82d1b0e826a0
        index:
          type: integer
          description: Zero-based index of the layout item.
          format: int32
          example: 0
        parentItemId:
          type: string
          description: Unique identifier for the parent matter list item.
          nullable: true
          example: 59791902-6280-471b-bd18-f8439ba3042f
        parentId:
          type: string
          description: Identifier of the parent matter list item specific to the provider.
          nullable: true
          example: Client
        parentIndex:
          type: integer
          description: Zero-based index of the parent matter list item.
          format: int32
          example: 0
        name:
          type: string
          description: Name of the layout item.
          nullable: true
          example: Item
        description:
          type: string
          description: Brief description of the layout item.
          nullable: true
          example: Text describing item
        isRemoved:
          type: boolean
          description: Boolean flag indicating if the layout item is to be removed.
          example: false
        values:
          type: array
          items:
            $ref: '#/components/schemas/LayoutValue'
          description: List of layout values.
          nullable: true
        events:
          type: array
          items:
            $ref: '#/components/schemas/LayoutEvent'
          description: List of layout events.
          nullable: true
      additionalProperties: false
    LayoutContactData:
      required:
      - contactId
      - key
      type: object
      properties:
        key:
          minLength: 1
          type: string
          description: Name (mapping) of the layout field that contains ContactId.
        contactId:
          type: string
          description: Unique identifier for the layout contact.
          format: uuid
      additionalProperties: false
    Link:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
      additionalProperties: false
    LayoutEvent:
      type: object
      properties:
        id:
          type: string
          nullable: true
        appointmentId:
          type: string
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    LayoutMatterItemDataCollection:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        value:
          type: array
          items:
            $ref: '#/components/schemas/LayoutMatterItem'
          nullable: true
      additionalProperties: false
    LayoutValue:
      type: object
      properties:
        key:
          type: string
          nullable: true
        value:
          type: string
          nullable: true
        state:
          description: 'Gets or sets the object that contains supplemental data about the key/value pair.


            This property was introduced in NV-2643, and is usage-specific. It contains data which is used together with Value.

            For example, if a layout contains a textbox control with an override checkbox, their Text and IsChecked properties

            can be persisted in Value and State respectively. In this case, the type of State would be bool or bool?.'
          nullable: true
      additionalProperties: false
    LayoutMatterItemData:
      type: object
      properties:
        itemId:
          type: string
          description: Unique identifier for the matter list item.
          nullable: true
          example: 59791902-6280-471b-bd18-f8439ba3042f
        layoutDesignId:
          type: string
          description: Identifier of the layout design.
          nullable: true
          example: 414ab774-adce-4659-b18c-82d1b0e826a0
        index:
          type: integer
          description: Zero-based index of the layout item.
          format: int32
          example: 0
        parentItemId:
          type: string
          description: Unique identifier for the parent matter list item.
          nullable: true
          example: 59791902-6280-471b-bd18-f8439ba3042f
        parentId:
          type: string
          description: Identifier of the parent matter list item specific to the provider.
          nullable: true
          example: Client
        parentIndex:
          type: integer
          description: Zero-based index of the parent matter list item.
          format: int32
          example: 0
        name:
          type: string
          description: Name of the layout item.
          nullable: true
          example: Item
        description:
          type: string
          description: Brief description of the layout item.
          nullable: true
          example: Text describing item
        values:
          type: array
          items:
            $ref: '#/components/schemas/LayoutValue'
          description: List of layout values.
          nullable: true
        events:
          type: array
          items:
            $ref: '#/components/schemas/LayoutEvent'
          description: List of layout events.
          nullable: true
        isRemoved:
          type: boolean
          description: Boolean flag indicating if the layout item is to be removed.
          example: false
      additionalProperties: false
  securitySchemes:
    api-key:
      type: apiKey
      name: x-api-key
      in: header
    token:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools