ReviewDesk guide · By the Ingenious AI team · Published 14 November 2026 · Reviewed 14 November 2026
How do you integrate decision traces through the ReviewDesk workspace API?
Generate a free adverse-outcome letter — no sign-up Build a free pre-use notice See pricing
The short answer. Authenticate with the workspace API key, file one trace per decision as the decision is made — decision id, timestamp, model version, factors used, outcome, notice and human-review flags — treat filing failures like payment failures, and reconcile trace counts against your decision log daily. The traces then project into the sealed Colorado, California and preparatory EU packs without further work. This guide describes the integration discipline around the workspace API that Pro and Team plans carry.
What is the workspace API trace integration?
The workspace API trace integration is the connection between a customer's decision system and ReviewDesk's evidence engine: using the workspace API key, the customer's pipeline files an immutable, hash-chained decision trace per automated decision, which ReviewDesk projects into three sealed evidence packs with the customer's scope-test worksheet attached.
What is the integration's shape?
Deliberately narrow: one authenticated channel, one record shape, filed per decision. The workspace API key identifies the workspace — the same key discipline the platform uses for owner API-key creation — and each filing creates one trace. Narrowness is the design virtue: an integration an engineer can implement in a day, test in an hour and monitor forever beats a rich interface that takes a quarter and fails in twelve places. The fields are the pack's fields, no more: decision id tying to your own system's record, the decision timestamp, model or tool version, the factors used, the outcome, and whether notice and human review were offered.
File through the same reliability pattern you use for billing events, because the evidentiary economics are identical: a lost billing event is lost revenue, a lost trace is a decision your packs cannot evidence. Queue at the producer, retry with backoff, dead-letter visibly, alert on age. The engine's immutability begins at filing — a trace cannot be edited after the fact — so the producer side owns correctness at the moment of the call: validate the payload against your own decision record before sending, because the chain will faithfully preserve whatever you file, including your mistakes, with corrections appended per the chaining guide.
Why must traces be filed at decision time?
Because the timestamp is evidence. A trace filed in the decision's own transaction proves the record was made when the decision was, by the system that made it. A trace filed in a nightly batch proves only that it was typed up later — and a sceptical reader prices the difference immediately, because batch reconstruction is exactly where plausible-but-wrong factors creep in. Decision-time filing also surfaces integration failures while the decisions are current: a broken producer is visible within the hour, not at the month's reconciliation, when a month of decisions has already gone unrecorded.
Where a legacy pipeline genuinely cannot file in real time, file as close to the event as the architecture allows, and let the packs carry the truth about filing latency — the gap discipline of the evidence guide applies to timing too. Then put the real-time migration on the roadmap with the pack as its justification. Do not solve the embarrassment by backdating: the chain's honesty about when records were made is worth more than any cohort's cosmetic completeness.
What belongs in the factors field — and what does not?
The factors that materially counted for this decision, in the vocabulary your notices and letters use — the factor groups the person was told about, resolved to this decision's actual drivers. Not the model's full feature vector (hundreds of signals, most immaterial, none printable), and not a generic criteria list copied onto every trace (the trace would then describe your policy, not your decision). The test from the reasons guide applies: the factors a letter could truthfully quote for this person. If your pipeline cannot yet produce per-decision factors, that is the integration's first work item — it is the field the entire evidence structure exists to carry.
Model version deserves the same precision: the version that produced this decision, stamped by the serving system, not the version the team believes was live. Version drift between belief and serving is common enough that the trace programme usually finds it in the first month — another case of the evidence system paying for itself as operational telemetry before any examiner arrives.
How should failures and duplicates be handled?
Failures loudly, duplicates idempotently. The producer retries transient failures with backoff and alerts when the queue ages beyond your threshold; a silent producer is the integration's worst state, worse than a down one, because decisions accumulate unrecorded while dashboards stay green. ReviewDesk's own producer discipline — heartbeats, silence treated as incident — is the pattern to mirror on your side of the wire. Duplicates are handled by the decision id: filing the same decision twice must not create two decisions' worth of evidence, so treat the decision id as the idempotency key in your producer logic and verify the behaviour in testing.
Build the reconciliation job with the integration, not after it: daily, decisions in your log versus traces filed, mismatches listed by id, an owner named for clearing them. The mismatch list is the integration's conscience. A programme that reconciles daily can state its completeness as a measured fact; one that reconciles at audit time can only hope, and hope is not a control. The wider evidence model these mechanics serve is in the pack guide.
How do scope worksheets and corrections flow through the integration?
Worksheets are configuration, not traffic: completed per decision type in the desk, refreshed on material change, and attached to the packs automatically — the API's job is decisions, the desk's job is determinations. Corrections flow as new traces referencing the original decision id, carrying the corrected element and its reason, appended to the chain. Your producer needs a corrections path distinct from its decisions path, because corrections are authored by the review process — often by a human in the inbox — rather than by the decision pipeline. Wire the inbox's correction outcomes to emit correction traces, and the loop closes: decision, challenge, correction, all one chain.
Test the correction path before the first real correction needs it. Corrections are rare, urgent and authored under pressure — the worst combination for an untested code path. A quarterly synthetic correction, filed and read back in the pack, keeps the path warm; the quarterly rhythm matches the vault export test in the vault guide, and the two drills belong in the same calendar slot.
What does a healthy integration look like after a quarter?
Boring, measurable and owned. Filing latency near zero, reconciliation mismatches cleared inside a day, a named engineer owning trace completeness the way billing owns payment events, and a gap list — fields still rendering 'not recorded' — that shrinks month over month as instrumentation catches up with ambition. The packs read better each quarter without anyone touching them, because the records feeding them got truer. That is the integration's real deliverable: not an API connection, but a decision pipeline whose evidence is a by-product of its operation.
Resist enriching the integration beyond the packs' needs. Every field added is a field to keep true under deadline pressure, and evidence systems die of ambitious schemas maintained at eighty per cent. The six-field discipline is the feature. If a future regime genuinely needs a seventh field, the worksheet and pack structure will say so, and the addition will be as deliberate as the original design. Until then: file completely, file on time, reconcile daily, and let the chain accumulate.
Your five actions for the workspace API trace integration
- Authenticate with the workspace API key and file one trace per decision, in the decision's own flow — never as a nightly reconstruction.
- Carry exactly the pack's fields: decision id, timestamp, model version, per-decision factors in notice vocabulary, outcome, notice and review flags.
- Build producer reliability like billing: queue, retry, dead-letter, alert on silence, decision id as the idempotency key.
- Reconcile trace counts against the decision log daily, with a named owner for mismatches.
- Wire corrections from the inbox as referenced traces, drill the path quarterly, and keep the schema at six honest fields.
Worked example: a trace integration that found a version lie
A fictional lender — NorthLoop Finance — integrates traces for its banding pipeline in a week: producer in the decision service, reconciliation job, alerting. In the first month the reconciliation is clean, but the packs surface a surprise: model version 4.1 appears on decisions three weeks after the team believed 4.2 had fully replaced it. One legacy worker node, missed in the rollout, has been serving the old model to a slice of traffic — invisible to every dashboard, because outcomes looked normal, and obvious in the traces, because versions are evidence.
The node is drained, the affected cohort is identifiable by trace for the first time in the company's history, and the version field — included for evidence reasons — pays for the entire integration as an operational instrument. NorthLoop's engineers draw the moral themselves: any field you stamp immutably at decision time becomes a truth serum for the pipeline that produced it. The packs were the purpose. The truth serum was the dividend.
Frequently asked questions
How do I authenticate trace filings?
With the workspace API key for your ReviewDesk workspace, on Pro and Team plans. Each filing creates one immutable trace for one decision, identified by your own decision id.
What fields does a trace carry?
Decision id, timestamp, model or tool version, the factors used, the outcome, and whether notice and human review were offered — plus your scope-test worksheet attached per decision type at pack level.
What if our pipeline cannot file in real time yet?
File as close to decision time as the architecture allows, let the packs show the reality, and roadmap the real-time move. Never backdate: the chain's honesty about when a record was made is worth more than cosmetic completeness.
How are duplicates and failures handled?
Decision id acts as the idempotency key in your producer logic; failures queue with retry and alerting, and a daily reconciliation against your decision log lists mismatches by id for a named owner to clear.
Is this guide legal advice?
No. ReviewDesk is templates and workflow tooling, not legal advice. The integration is described as ReviewDesk's evidence engine is built; consult counsel for your obligations.
Keep reading: Who should own an ADMT programme — owner, reviewers and record-keepers? · What are the key ADMT deadlines — Illinois now, Colorado and California 2027, the EU in December 2027? · What changed with Colorado SB 26-189 — and what does it keep from the earlier AI Act approach? · What is the California ADMT compliance timeline — from the 2026 regulations to the 2028 assessment? · What does ReviewDesk's free tier actually cover — and when do you need Pro or Team? · All ReviewDesk guides · ReviewDesk home · Try the free desk · Free letter generator · Free notice builder · Pricing
ReviewDesk is built by Ingenious AI. Templates and workflow tools — not legal advice.