Save Document Data

Save sidebar field values and complex table rows on a document without completing it. The document keeps its status, and no export, webhook or completion side effect runs. Use it to store edits made outside the Staple UI, for example from a review tool of your own. ##### HOW TO ADDRESS DATA - Sidebar fields are addressed by `fieldUuid`. Get the ids from `POST /v2/search/documents/model/fields` (`field_id`) or from the document JSON returned by `GET /v1/documents/:docId` (`field_id` on each field). - Tables are addressed by `tableTypeId` or `tableName`, plus a 0-based `pageNumber`. Get the table type and header ids from `POST /v2/search/documents/model/tables`. `tableName` is the model's table name returned there (for example `Tax Table`); the name a document shows for its own table is accepted too. - Rows are addressed by `lineItemId` or 0-based `rowIndex` on that page. Cells are keyed by header id or header name: the model's `headerName` (for example `Tax Code`), or the column name the document shows. - A name that matches more than one table type or header is rejected with 400. Use the id instead. ##### HOW ROWS ARE APPLIED - On an existing row only the cells you send change. Cells you leave out keep their value. - Only the rows you send change. Rows you do not mention are kept as they are. - Rows without `lineItemId` or `rowIndex` are added at the end of the page. A new row needs at least one cell. - To clear a value, send it as an empty string. - `removeRows` deletes rows on that page, each by `lineItemId` or `rowIndex` (the position before this save). A row cannot be patched and removed in the same request. - Rows on other pages are untouched. - `removeColumns` (header id or name) removes those columns from every page of the table type, the same as removing a column in the editor. ##### VALIDATION AND VERSIONING - Every changed value is validated against the data type of its field or header. If any value is invalid the whole request is refused with 422 and `errors.invalidValues`, and nothing is saved. - Send `expectedDataVersion` with the `dataVersion` you received from `GET /v1/documents/:docId`. If someone changed the document since then the request is refused with 409 and `errors.currentDataVersion`. Reload the document, or resend with the current version to overwrite. - Locked fields and exported documents cannot be changed (403). - Limited to 6 calls per 30 seconds per user. ##### REQUEST HEADERS | Attribute | Type | Option | Description | | --- | --- | --- | --- | | x-api-key | String | Required | An unique string | | Authorization | String | Required | The bearer token | | Content-Type | application/json | Required | The original resource | ##### REQUEST PAYLOAD ``` { "documentId": Int | required, "qid": Int | required | the queue the document is in, "expectedDataVersion": String | optional | dataVersion from GET /v1/documents/:docId, "fields": Array | optional | [{ "fieldUuid": String, "value": String }], "tables": Array | optional | [{ "tableTypeId" | "tableName": String, "pageNumber": Int (0-based), "rows": [{ "lineItemId"? | "rowIndex"?, "cells": { header_id_or_name: String } }] | optional, "removeRows": [{ "lineItemId" | "rowIndex" }] | optional, "removeColumns": [ header_id_or_name ] | optional }] } ``` At least one of `fields` or `tables` is required. Each table entry needs at least one of `rows`, `removeRows`, `removeColumns`. ##### RESPONSE BODY | Attribute | Type | Description | | --- | --- | --- | | message | String | Confirmation message | | documentId | Int | The document id | | qid | Int | The queue id | | dataVersion | String | New version token to send as `expectedDataVersion` on the next save | | fields | Array | Saved fields: `fieldUuid`, `value` (stored, canonical form), `originalValue` | | tables | Array | Per page: `tableTypeId`, `pageNumber`, `tableName` (the model's table name), `rowCount`, `addedLineItemIds`, `removedLineItemIds`, `removedColumnIds` | ##### ERRORS | Status | Meaning | | --- | --- | | 400 | Malformed body, ambiguous name, row listed twice, row from another page, empty new row, row both patched and removed | | 403 | Locked field, exported document, or no access to the queue | | 404 | Document, field, table, page, row or column not found | | 409 | Document changed since you loaded it (`errors.currentDataVersion`) | | 422 | Values invalid for their data type (`errors.invalidValues`) | | 503 | Validation service unavailable, nothing saved |