Write data

Write operations create and change records in your workspace. They cover clients, entities, engagements, saved tax data, documents, workpapers, account notes and review marks, client portal requests, and integration syncs. Every operation, its fields and its errors are in the REST reference. Each one has a matching MCP tool, listed under write tools.

Each write needs its domain's write scope, such as clients:write or documents:write. See scopes.

Idempotency keys#

Every write takes a new UUID as its idempotency key. REST takes it in the Idempotency-Key header, and MCP tools take it as idempotencyKey. A key belongs to your API client and to one operation.

• Send the same key and body again to get the stored response. A repeated create returns 200 instead of 201.
• The same key with a different body returns 422 idempotency_key_reused.
• A retry while the first request is still running returns 409 idempotency_in_progress with Retry-After.
• A missing key, or a value that is not a UUID, returns invalid_request.

Resource versions#

A record you can change carries a resourceVersion. REST responses for that record also send it in the ETag header.

To change a record that already exists, send the version you last read. REST takes it in If-Match, and MCP tools take it as expectedResourceVersion.

• A version that no longer matches returns 412 resource_version_conflict. Read the record again and retry with its current version.
• A missing version returns 428 precondition_required. If-Match takes one strong tag. *, weak tags and lists also return 428.

Get mutation preconditions returns whether an engagement can be changed, why it is locked when it cannot, and the current versions.

Locked engagements#

An engagement marked filed or signed off by a partner is read-only. Writes to it return 409 conflict.

The API does not amend a filed return, sign off a review, clear a review mark, or accept or reject a client's portal response. Those stay in the Filemark app.

Operations that reach outside Filemark#

Four operations send something outside Filemark.

Preview the same action you will apply. A confirmation token works once, for the API client and action it was issued for, and expires within 15 minutes. An expired, spent or mismatched token returns 409 conflict. Preview again to get a new one. An integration sync applies the data its preview fetched.

Only server integrations can hold portal:send, integrations:sync and exports:deliver. Delegated access cannot grant them.

Limits and attribution#

Writes count toward a limit of 30 per minute per API client. The four operations above count toward a limit of 10 per minute instead. See rate limits.

A write from a server integration is recorded as that API client's. A write through delegated access is recorded as the workspace member who approved the connection.