Workflows and Records
How records relate to workflows, and which API to use to update a contract.
In the Ironclad app, a contract in progress and the finished contract look like one thing. The API splits them in two:
- A workflow is the process that produces a contract: create, review, sign, archive.
- A record is the contract's entry in the repository.
Every workflow has a record behind it. Which API you use to change a contract depends on whether its workflow is still running.
How they're linked
- A record created by a workflow has
source.typeset toworkflow, andsource.workflowIdis that workflow's ID. - Once a workflow reaches its Archive step, its
recordIdslists the records it created. Before then,recordIdsmay be missing even though the record exists.
While the workflow is in progress
While a workflow is active or paused, the workflow owns its record. Every time the workflow changes, and again at the Archive step, Ironclad rewrites the record from the workflow's data, including:
- the record's name, type, and properties
- links to related records, and parent and child relationships
- user and group access
If you change that record through the Records API during this time, the request succeeds, but the change is overwritten the next time the workflow changes.
To change the contract while its workflow is in progress, update the workflow instead:
- Update Workflow Metadata (
PATCH /workflows/{id}/attributes) updates workflow fields. The workflow must be in the Review step. - For roles, approvals, signers, and documents, use the matching endpoints under
/workflows/{id}.
After the workflow completes
Once a workflow is completed, its record is in the repository. Ironclad still keeps the workflow's own tracking properties up to date, such as workflow dates and step durations, but it stops rewriting the rest of the record. From then on, update the contract through the Records API, for example Update Record Metadata (PATCH /records/{id}) or Replace a Record (PUT /records/{id}). Those changes are kept.
If a workflow is cancelled before it completes, its record is never added to the repository.
Summary
| Workflow status | Update the contract with | Records API changes |
|---|---|---|
active, paused | Workflows API | Overwritten by the workflow |
completed | Records API | Kept |
Updated about 21 hours ago

