Pick one state change
Start with a discount, refund, access grant, payout, CRM write-back, or agent tool action that already has an owner.
Integration Guides
Put a decision record in front of the systems that change state.
Every integration follows the same pattern: detect a bounded action, call /api/decide from a server-side caller, persist the returned record, then proceed, block, or route to review.
First-boundary rollout packet
Use this page when choosing the first production boundary. The goal is a small integration that proves the full lifecycle: decide before action, receipt the attempted mutation, report the result, then export a packet reviewers can verify.
Call from the server
Keep x-api-key behind your backend, queue worker, or private proxy. Browser-visible automation steps should not hold production keys.
Attach every artifact
Store the Decision Record, record the execution receipt, report the Outcome Record, and export Decision Packet v1.
Verify before widening
Move to the next boundary only after the first one has stable fail-closed behavior and a verified proof packet.
The shared integration sequence
Use this before writing connector-specific code. It keeps Decide as a small API layer instead of turning the first rollout into a workflow rebuild.
Name the action
Pick the exact state change that should require a verdict, such as applying a discount, issuing a credit, granting access, or executing an agent step.
Send the context
Call /api/decide with the question, workflow name, owner, source identifiers, guardrail fields, and evidence references.
Map the verdict
yes proceeds, no blocks, and review routes to the declared owner path. Errors should not silently approve.
Store the record
Persist the full Decision Record v1 object beside the downstream action or source record.
Start where the owner already exists.
The first integration should not require new governance theater. Use the software boundary where an owner already cares about the outcome and can define review behavior.
Lifecycle proof mapping
The integration is strongest when every stage leaves a durable artifact. Use this table as the handoff between engineering, operations, and reviewers.
| Integration stage | Artifact to create | Fail-closed rule |
|---|---|---|
| Before state change | Decision Record v1 from POST /api/decide, including verdict, evidence, policy version, hashes, verify URL, and replay URL. | Only yes proceeds. no, review, auth failures, rate limits, and unknown errors do not execute the action. |
| When mutation is attempted | Action Execution Receipt with target system, target object, mutation, executor, state hashes, and execution hash. | If the mutation is not bound to the authorized action, stop and route to owner review. |
| After business result is known | Outcome Record with status, action taken, observed metrics, target system, and outcome hash. | If the result is ambiguous, report review or pending instead of inventing success. |
| For buyer or security review | Decision Packet v1 containing record, execution receipts, Outcome Records, policy intelligence, audit-chain metadata, and verification hints. | Do not expand the rollout until the packet verifies and the owner understands the review path. |
CRM guide: Salesforce, HubSpot, and quote approvals
Use Decide before a CRM workflow applies a pricing exception, packaging override, approval status, or routing decision that should carry an audit handle.
Quote or deal requests an exception
Use an internal service, workflow action, or automation step to send the decision payload before the CRM field is finalized.
Pass fields the owner can audit
Include account segment, plan, term, discount, owner rule, margin floor, source record id, and evidence references.
Attach the handle to the object
Store the Decision Record v1 object on the opportunity, quote, deal, or approval row that changes state.
| CRM field | Decide context key | Why it matters |
|---|---|---|
| Opportunity, quote, or deal id | source_record_id | Lets the decision trace point back to the exact CRM record. |
| Discount, package, or approval request | requested_action | Names the software action being gated. |
| Owner or approval group | owner_rule | Defines who can approve or review ambiguous outcomes. |
| Margin, plan, or term guardrail | guardrails | Gives the verdict enough structure to explain itself later. |
| Decision metadata fields | request_id, decision_id, record_hash, receipt_hash, verify_url, replay_url | Stores verification, replay, and tamper-checkable record handles beside the CRM state change. |
Billing guide: Stripe-style changes, credits, discounts, and refunds
Billing integrations should fail closed when the decision record is missing. Call Decide before the billing mutation, then store the returned handles in metadata, an internal ledger, or both.
Server-side decision payload
{
"question": "Approve annual-plan discount exception before billing update?",
"mode": "single",
"context": {
"workflow": "billing_discount_gate",
"customer_id": "cus_...",
"invoice_or_subscription_id": "sub_...",
"requested_action": "apply_discount",
"discount_percent": 15,
"margin_floor": "passed",
"owner_rule": "verified"
}
}Metadata to persist
{
"decide_request_id": "req_9f3c",
"decide_decision_id": "dec_43b2",
"decide_verdict": "yes",
"decide_action": "approve_discount",
"decide_record_hash": "7f3a...",
"decide_receipt_hash": "c91e...",
"decide_verify_url": "/api/decision/dec_43b2/verify",
"decide_replay_url": "/api/decision/dec_43b2/replay"
}| Outcome | Billing behavior | Operator behavior |
|---|---|---|
yes | Apply the billing update and write Decide metadata. | Review only if your own local validation fails. |
no | Do not apply the update. | Show the evidence checks and source fields that caused the block. |
review | Leave the record pending. | Route to owner review before any irreversible billing change. |
| HTTP error | Fail closed for high-risk changes. | Retry with backoff only when your integration policy allows it. |
Automation guide: Zapier, Make, and no-code flows
No-code automation can call Decide safely, but the production key should stay behind a server-side proxy or private internal endpoint. Do not put production API keys in browser-visible steps.
No-code trigger, server-side Decide proxy
The automation posts the event to your own endpoint. Your endpoint adds x-api-key, calls Decide, stores the record, then returns the route instruction.
Production key in a public workflow step
If a workflow tool exposes step details to many operators, use a private proxy so key rotation and audit remain under engineering control.
Workflow event fires
Deal updated, ticket changes status, payout queued, or access change requested.
Private endpoint receives it
Normalize fields and attach internal trace ids before calling Decide.
Decide returns route
Proceed, deny, review, or escalate based on verdict and evidence.
Automation continues
Store the Decision Record v1 object and move only when the verdict allows it.
Webhook and queue guide
For async jobs, Decide should run before the worker performs the state-changing side effect. The queue message should carry the returned decision handles forward.
Worker pattern
receive job
build Decide payload from job + source record
POST /api/decide with x-api-key
if verdict is yes:
perform side effect
store request_id and decision_id with job result
if verdict is no:
mark job blocked with evidence
if verdict is review or API unavailable:
mark job pending owner reviewQueue metadata
{
"job_id": "job_841",
"decide_request_id": "req_9f3c",
"decide_decision_id": "dec_43b2",
"decision_verdict": "yes",
"decision_evidence": ["OWNER_RULE_VERIFIED"],
"source_record_id": "deal_1042"
}Agent guide: verdict before autonomous action
Agent integrations should treat Decide as a permission boundary. The agent proposes an action, Decide records the verdict, and the agent proceeds only when the returned action permits it.
Agent proposes a bounded action
For example: grant access, issue refund, execute payout, send customer offer, or route a queue item.
System calls Decide
The server wraps the agent proposal with owner, risk, source state, and policy context before execution.
Only proceed on allowed verdicts
Agents should treat review, unknown, rate limits, and auth errors as non-execution states.
First-boundary launch checklist
Before live traffic, make each owner confirm the narrow action boundary and the evidence they will inspect after launch.
| Owner | Confirm before launch | Review artifact |
|---|---|---|
| Workflow owner | The exact action, allowed verdict behavior, review path, and expansion rule are written down. | Decision Record v1 plus source-system object link. |
| Engineering | API key is server-side, idempotency is set, errors fail closed, and records persist beside the action. | First-hour implementation example and integration smoke result. |
| Operations | Status/readiness export is reviewed and quota behavior is understood before production traffic. | Status packet and launch readout. |
| Reviewer | Decision Packet v1 verifies and includes execution and outcome evidence for the first live run. | Exported packet plus hosted verifier or SDK verification output. |
Minimum record schema
Use your own database, source-system metadata, or ledger. The important part is that the decision record stays attached to the action it governed.
Lifecycle record schema
create table decision_actions (
id text primary key,
source_system text not null,
source_record_id text not null,
requested_action text not null,
decision_verdict text not null,
decide_request_id text not null,
decide_decision_id text not null,
decide_record_hash text,
decide_receipt_hash text,
decide_execution_id text,
decide_execution_hash text,
decide_outcome_id text,
decide_outcome_hash text,
decide_packet_hash text,
decide_verify_url text,
decide_replay_url text,
evidence_json text,
action_status text not null,
created_at timestamp not null
);