> For the complete documentation index, see [llms.txt](https://api-docs.intratool.help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.intratool.help/introduction/layouts.md).

# Layouts

Layouts separate presentation structure, content, and resource assignments. A [Layout](https://api-docs.intratool.help/api-reference/layouts/layouts.md) stores its origin and contains ordered [LayoutRows](https://api-docs.intratool.help/api-reference/layouts/layout-rows.md) and [LayoutColumns](https://api-docs.intratool.help/api-reference/layouts/layout-columns.md). [LayoutableLayouts](https://api-docs.intratool.help/api-reference/layouts/layoutable-layouts.md) assign an existing layout to a resource for a particular purpose.

An endpoint that accepts `layouts` receives references to existing layouts. The array assigns presentation purposes; it does not create or edit rows, columns, fields, or content.

## Origin and Assignment

A layout's origin identifies its owner and original purpose. The assignment identifies where that layout is used. These values are independent: assigning a layout does not change its origin.

| Value                       | Location         | Meaning                                                        |
| --------------------------- | ---------------- | -------------------------------------------------------------- |
| `origin_entity_type`        | Layout           | Alias of the origin resource; required on creation.            |
| `origin_entity_id`          | Layout           | Origin resource ID; may be omitted until that resource exists. |
| `origin_entity_layout_type` | Layout           | Original presentation purpose; required on creation.           |
| `layouts.*.id`              | Resource request | Existing layout ID to assign.                                  |
| `layouts.*.type`            | Resource request | Presentation purpose of that assignment.                       |

The origin type and original purpose remain fixed after creation. An unset origin ID can be filled after the origin resource is created; an assigned origin ID cannot be replaced. The server derives the layout's `user_id` from the authenticated user. Omitting `lang_id` on creation uses the system language.

Before an origin ID is assigned, access follows the layout's creator. Afterward, it follows the origin resource. Layout writes use administration routes and require the corresponding administration access.

## Assignment Structure

Each entry in `layouts` contains an existing layout `id` and an assignment `type`. The receiving resource determines the supported and required types; its endpoint documents those requirements. A type may occur only once in the array. The same layout ID may be assigned to different types.

The following fragment assigns layout ID `1` to both the input and message presentation, and layout ID `2` to email content. Both layouts already exist.

```json
{
  "layouts": [
    {
      "id": 1,
      "type": "default"
    },
    {
      "id": 1,
      "type": "formMessage"
    },
    {
      "id": 2,
      "type": "formMail"
    }
  ]
}
```

### Replacement and Partial Updates

Supplying `layouts` replaces the complete assignment set. Entries for omitted types are removed, and the resulting set must include every type required by the receiving resource. An empty array is valid only when the resource has no required assignments.

On a partial update that supports `layouts`, omitting the key preserves the existing assignments. To change one assignment, submit the complete intended set with that entry changed. Changing assignments does not edit the referenced layout's content.

The standalone [assignment synchronization endpoint](https://api-docs.intratool.help/api-reference/layouts/layoutable-layouts.md#admin-sync) applies the same replacement rules. Its request also identifies the receiving resource with `layoutable_type` and `layoutable_id`.

### Assignment Responses

When a resource returns its assigned layouts through `include=layouts`, each layout carries the assignment purpose in `pivot.type`. The layout's `origin_entity_layout_type` still describes its original purpose. The `layouts.*.id` in a write payload is the layout ID, not the assignment record's ID.

## Creation Flow

1. Create the layout with its origin type and original purpose. If the origin resource does not exist, leave `origin_entity_id` unset.
2. Create the resource with all required layout assignments, using the returned layout IDs.
3. Fill each layout's unset origin ID with the created resource ID.
4. Create rows and columns and populate them through their own endpoints.

Rows reference their layout through `layout_id`; columns reference their row through `layout_row_id`. [ContentElements](https://api-docs.intratool.help/api-reference/layouts/content-elements.md) and [FormFields](https://api-docs.intratool.help/api-reference/forms/form-fields.md) provide the content placed in columns. Their creation and update endpoints document the supported placement keys and parent-resource constraints. Type-specific content configurations and payload examples are documented in [ContentElementTypes](https://api-docs.intratool.help/api-reference/layouts/content-element-types.md).

[LayoutColumnLayoutElements](https://api-docs.intratool.help/api-reference/layouts/layout-column-layout-elements.md) record element placement and order. Synchronizing an element to a destination column removes that element's other column assignments while retaining other elements in the destination. This operation changes placement, independently of the resource's `layouts` array.
