> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smokeball.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a new layout

> Adds a new layout matter item to a matter.



## OpenAPI

````yaml /openapi.json post /matters/{matterId}/layouts
openapi: 3.0.1
info:
  title: API
  version: '1.0'
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: []
paths:
  /matters/{matterId}/layouts:
    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'
components:
  schemas:
    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
    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
    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: {}
    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
    LayoutEvent:
      type: object
      properties:
        id:
          type: string
          nullable: true
        appointmentId:
          type: string
          nullable: true
      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

````