# Update contract state and appearance

Update the contract's state values and appearance using [JSON Patch (RFC 6902)](https://datatracker.ietf.org/doc/html/rfc6902) operations.
The available operations depend on the path, as does the value. Operations are applied sequentially in the order they appear, so later operations can build on the result of earlier ones.
By default the patch is all-or-nothing: if any operation fails, nothing is saved and the endpoint returns `422`.
Set `allow_partial: true` to save the operations that succeed. The response is then always `200` and lists the failed operations under `meta.failed_operations`; if every operation failed, nothing is saved. A failed operation leaves no changes behind, so later operations that depend on it — including ones whose array index paths assume it succeeded — may fail or target a different element.
Authentication, not-found, and malformed-request errors (such as an unsupported `op`) fail the whole request. A `5xx` response does not guarantee that nothing was saved, so read the state before retrying.
See more detailed description and examples [here](/embed-api/legal-engine/document-state).

Endpoint: PATCH /api/builder/sessions/{session_id}/contract
Version: 1.0.0
Security: APIKey

## Security:

  - `APIKey` (unknown)
    http bearer API Key

## Path parameters:

  - `session_id` (string, required)
    The UUID of the session

## Header parameters:

  - `X-Participant` (string, required)
    The participant ID for the builder session. This header is required for updating the contract state.

## Request fields (application/json):

  - `operations` (array, required)
    JSON Patch operations, applied in the order they appear.

  - `operations.op` (string, required)
    Enum: "replace", "remove", "add"

  - `operations.path` (string, required)
    Example: /document_name

  - `operations.value` (any)
    Example: My document

  - `allow_partial` (boolean)
    When `true`, operations that succeed are saved even if others fail, and the response lists the failed operations under `meta.failed_operations`. When `false` (the default), the patch is all-or-nothing.
    Example: true

## Request examples:

  - `Default all-or-nothing patch` (unknown)

  - `Partial success allowed` (unknown)

## Response 200:

  - `200` (unknown)
    The resulting contract state. `meta.failed_operations` lists the operations that failed; an empty list means every operation was applied. Without `allow_partial` it is always empty, because any failed operation returns `422` instead.

## Response 200 fields (application/json):

  - `data` (object)

  - `data.state` (object)
    Contract current state

  - `data.state.id` (string)

  - `data.state.status` (string)
    If document is finalized, it cannot be edited.
    Enum: "draft", "finalized"

  - `data.state.document_name` (string)
    Name of the document. End-users can edit this. This is not visible on the document itself.

  - `data.state.jurisdiction` (string)
    Jurisdiction of the agreement.
    Example: FI

  - `data.state.languages` (array)
    Languages in which the document is drafted. It usually contains just one.
    Example: ["en-GB"]

  - `data.state.value` (object)
    Values filled in to the form. The schema varies in every template. See [this](/embed-api/legal-engine/document-state#update-document-field-values) for more information.

  - `data.state.sections` (array)
    List of sections included in the document. It contains templates and custom sections added by end-users. The sections are presented in the same order as they appear in the document.

  - `data.state.appearance` (object)

  - `data.state.appearance.logo` (object)

  - `data.state.appearance.logo.enabled` (boolean)
    Example: false

  - `data.state.appearance.logo.content` (string | null)
    Data URI with base64 encoded JPG,PNG or SVG image.
    Example: null

  - `data.state.appearance.logo.scale` (number)
    Size of the logo, scale 20-100 where 20 is the smallest and 100 is the largest.
    Example: 50

  - `data.state.appearance.footer` (object)

  - `data.state.appearance.footer.enabled` (boolean)
    Example: false

  - `data.state.appearance.footer.content` (string)

  - `data.state.appearance.heading1` (object)

  - `data.state.appearance.heading1.family` (string)
    Example: arial

  - `data.state.appearance.heading1.color` (string)
    Example: #000000

  - `data.state.appearance.heading1.size` (string)
    Example: 20

  - `data.state.appearance.heading1.weight` (string)
    Example: bold

  - `data.state.appearance.heading1.alignment` (string)
    Example: left

  - `data.state.appearance.heading1.transform` (string)
    Example: none

  - `data.state.appearance.heading2` (object)

  - `data.state.appearance.heading2.family` (string)
    Example: arial

  - `data.state.appearance.heading2.color` (string)
    Example: #000000

  - `data.state.appearance.heading2.size` (string)
    Example: 13

  - `data.state.appearance.heading2.weight` (string)
    Example: bold

  - `data.state.appearance.heading2.alignment` (string)
    Example: left

  - `data.state.appearance.heading2.transform` (string)
    Example: none

  - `data.state.appearance.heading3` (object)

  - `data.state.appearance.heading3.family` (string)
    Example: arial

  - `data.state.appearance.heading3.color` (string)
    Example: #000000

  - `data.state.appearance.heading3.size` (string)
    Example: 12

  - `data.state.appearance.heading3.weight` (string)
    Example: bold

  - `data.state.appearance.heading3.alignment` (string)
    Example: left

  - `data.state.appearance.heading3.transform` (string)
    Example: none

  - `data.state.appearance.heading4` (object)

  - `data.state.appearance.heading4.family` (string)
    Example: arial

  - `data.state.appearance.heading4.color` (string)
    Example: #000000

  - `data.state.appearance.heading4.size` (string)
    Example: 11

  - `data.state.appearance.heading4.weight` (string)
    Example: bold

  - `data.state.appearance.heading4.alignment` (string)
    Example: left

  - `data.state.appearance.heading4.transform` (string)
    Example: none

  - `data.state.appearance.heading5` (object)

  - `data.state.appearance.heading5.family` (string)
    Example: arial

  - `data.state.appearance.heading5.color` (string)
    Example: #000000

  - `data.state.appearance.heading5.size` (string)
    Example: 11

  - `data.state.appearance.heading5.weight` (string)
    Example: regular

  - `data.state.appearance.heading5.alignment` (string)
    Example: left

  - `data.state.appearance.heading5.transform` (string)
    Example: none

  - `data.state.appearance.heading6` (object)

  - `data.state.appearance.heading6.family` (string)
    Example: arial

  - `data.state.appearance.heading6.color` (string)
    Example: #000000

  - `data.state.appearance.heading6.size` (string)
    Example: 11

  - `data.state.appearance.heading6.weight` (string)
    Example: regular

  - `data.state.appearance.heading6.alignment` (string)
    Example: left

  - `data.state.appearance.heading6.transform` (string)
    Example: none

  - `data.state.appearance.paragraph` (object)

  - `data.state.appearance.paragraph.family` (string)
    Example: arial

  - `data.state.appearance.paragraph.color` (string)
    Example: #000000

  - `data.state.appearance.paragraph.size` (string)
    Example: 11

  - `data.state.appearance.paragraph.weight` (string)
    Example: regular

  - `data.state.appearance.paragraph.alignment` (string)
    Example: justify

  - `data.state.appearance.paragraph.transform` (string)
    Example: none

  - `data.state.appearance.table` (object)

  - `data.state.appearance.table.family` (string)
    Example: arial

  - `data.state.appearance.table.size` (string)
    Example: 11

  - `data.state.appearance.table.color` (string)
    Example: #000000

  - `data.state.appearance.table.bgColor` (string)
    Example: #ffffff

  - `data.state.appearance.table.headerBgColor` (string)
    Example: #e7e5e4

  - `data.state.appearance.table.headerColor` (string)
    Example: #000000

  - `data.state.appearance.table.borderColorEnabled` (boolean)
    Example: true

  - `data.state.appearance.table.borderColor` (string)
    Example: #ffffff

  - `data.state.appearance.table.alternatingRowBgColorEnabled` (boolean)
    Example: true

  - `data.state.appearance.table.alternatingRowBgColor` (string)
    Example: #fafaf9

  - `data.signees` (array)
    List of signees found from the document.

  - `data.signees._type` (string)
    Enum: "signature"

  - `data.signees.id` (string, required)
    Unique ID for the signature.

  - `data.signees.first_name` (string, required)

  - `data.signees.last_name` (string, required)

  - `data.signees.job_title` (string)

  - `data.signees.company_name` (string)

  - `data.signees.fieldset_name` (string, required)
    Name of the fieldset from which this signee originates.

  - `data.signees.page` (integer, required)
    Number of the page where the signature area of this signee is located. It is 1-based.

  - `data.signees.x` (number, required)
    X position of the signature area's location. The value is % of the page's width. For e.g. 0.10 means it is 10% of the page width.
    Example: 0.1

  - `data.signees.y` (number, required)
    Y position of the signature area's location. The value is % of the page's height. For e.g. 0.10 means it is 10% of the page height.
    Example: 0.1

  - `data.signees.width` (number, required)
    Width of the signature area. The value is % of the page's width. For e.g. 0.10 means it is 10% of the page width.
    Example: 0.1

  - `data.signees.height` (number, required)
    Height of the signature area. The value is % of the page's height. For e.g. 0.10 means it is 10% of the page height.
    Example: 0.1

  - `meta` (object, required)

  - `meta.status` (object, required)

  - `meta.status.code` (integer)
    Example: 200

  - `meta.status.text` (string)
    Example: OK

  - `meta.failed_operations` (array, required)
    The operations that failed, in request order. Operations not listed were applied. Always empty when the request did not set `allow_partial` to `true`.

  - `meta.failed_operations.index` (integer, required)
    Zero-based position of the operation in the request's `operations` array.
    Example: 1

  - `meta.failed_operations.path` (string, required)
    The `path` of the operation, as sent in the request.
    Example: /value/basic/title

  - `meta.failed_operations.error` (object, required)
    Why the operation failed.

  - `meta.failed_operations.error.code` (string, required)
    Machine-readable reason. `invalid_operation` means the operation failed validation, for example a path that cannot be patched or a value of the wrong type. `operation_failed` means it could not be applied to the state.
    Enum: "invalid_operation", "operation_failed"

  - `meta.failed_operations.error.message` (string, required)
    Human-readable reason.
    Example: Operation "replace" at "/value/basic/title" failed: invalid value

  - `meta.failed_operations.error.details` (any, required)
    Validation details as a map of what failed to a message or a list of messages — for example `value` when the operation's `value` does not match the field. An empty array when there are no details.
    Example: {"value":"Invalid input: expected object, received string"}

## Response 401:

  - `401` (unknown)
    Authentication failed. The API key is missing or invalid.

## Response 401 fields (application/json):

  - `data` (null, required)
    Always null for error responses.

  - `meta` (object, required)

  - `meta.status` (object, required)

  - `meta.status.code` (integer, required)

  - `meta.status.text` (string, required)

  - `meta.error` (object, required)

  - `meta.error.text` (string, required)

  - `meta.error.details` (object)
    Validation details, when available, as a map of what failed to a message or a list of messages.

## Response 404:

  - `404` (unknown)
    Session or participant not found, or the session has been deleted.

## Response 404 fields (application/json):

  - `data` (null, required)
    Always null for error responses.

  - `meta` (object, required)

  - `meta.status` (object, required)

  - `meta.status.code` (integer, required)

  - `meta.status.text` (string, required)

  - `meta.error` (object, required)

  - `meta.error.text` (string, required)

  - `meta.error.details` (object)
    Validation details, when available, as a map of what failed to a message or a list of messages.

## Response 422:

  - `422` (unknown)
    Nothing was saved. Either the request is malformed, or — without `allow_partial` — an operation failed. `meta.error.details` describes the problem when available.

## Response 422 fields (application/json):

  - `data` (null, required)
    Always null for error responses.

  - `meta` (object, required)

  - `meta.status` (object, required)

  - `meta.status.code` (integer, required)

  - `meta.status.text` (string, required)

  - `meta.error` (object, required)

  - `meta.error.text` (string, required)

  - `meta.error.details` (object)
    Validation details, when available, as a map of what failed to a message or a list of messages.

## Response 200 examples:

  - `Partial success allowed and some operations failed` (unknown)

  - `Partial success allowed and every operation failed` (unknown)

  - `Full contract state` (unknown)

## Response 422 examples:

  - `Operation failed without partial success` (unknown)

  - `Malformed request` (unknown)