---
title: "Add a new layout"
method: POST
path: "/matters/{matterId}/layouts"
tags: ["Layout Matter Items"]
---

# Add a new layout

`POST /matters/{matterId}/layouts`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/matters/{matterId}/layouts`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Adds a new layout matter item to a matter.

## Path parameters

- `matterId` string, uuid, required

## Query parameters

- `skipFieldValidation` boolean

## Request body

- LayoutMatterItemData
  - `itemId` string, nullable: Unique identifier for the matter list item.
  - `layoutDesignId` string, nullable: Identifier of the layout design.
  - `index` integer: Zero-based index of the layout item.
  - `parentItemId` string, nullable: Unique identifier for the parent matter list item.
  - `parentId` string, nullable: Identifier of the parent matter list item specific to the provider.
  - `parentIndex` integer: Zero-based index of the parent matter list item.
  - `name` string, nullable: Name of the layout item.
  - `description` string, nullable: Brief description of the layout item.
  - `values` LayoutValue[], nullable: List of layout values.
    - `key` string, nullable
    - `value` string, nullable
    - `state` unknown
  - `events` LayoutEvent[], nullable: List of layout events.
    - `id` string, nullable
    - `appointmentId` string, nullable
  - `isRemoved` boolean: Boolean flag indicating if the layout item is to be removed.

## Response `202`

When request is accepted. Returns a hypermedia 'Link' object of the layout item to be created.

- Link
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable

## Other responses

- `400`: When the new matter item contain invalid data.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: When the matter or a layout item with the specified ID does not exist.
- `503`: Service Unavailable

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)