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

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

ERRORS