POST /v1/protocol/evaluate-decision is the canonical Decionis route for new partner decision workflows once onboarding and deployment-bundle issuance are complete. Use the returned org API key as the bearer credential, include an idempotency key for write safety, and reserve /v1/action-gate/evaluate for higher-level wrappers that need an action-gate envelope.
The public docs should guide teams through the actual production credential handoff, not a parallel wrapper-first path.
| Step | Route | Outcome |
|---|---|---|
| 1. Verify sponsor identity | /v1/public/auth/register/start and /v1/public/auth/register/verify | Get the onboarding grant and resolved org ID. |
| 2. Create mapping baseline | /v1/public/pilot/signal-mapping/sessions | Open the workflow mapping session and upload representative samples. |
| 3. Issue deployment bundle | /v1/public/pilot/signal-mapping/sessions/:sessionId/deployment-bundle | Receive the org API key, connector ID, webhook secret, webhook URL, and policy version. |
| 4. Persist runtime credentials | Store the org API key | Use the org API key as the bearer token for direct decision evaluation calls. |
| 5. Call the canonical route | /v1/protocol/evaluate-decision | Submit governed decisions directly and inspect the resolved domain, pack, and dossier references. |
Use /docs/quickstart for the full onboarding sequence and /docs/auth for auth boundaries. Use /v1/action-gate/evaluate only when a surface-specific adapter wants a higher-level wrapper envelope over the same decisioning posture.
This route is the public canonical surface for direct governed decision requests.
/v1/protocol/evaluate-decisionAPI keyEvaluate a governed decision, resolve the workflow pack, persist protocol artifacts, and return the decision outcome plus dossier references.
Authorization: Bearer dcy_org_xxx
Idempotency-Key: cfd-order-${ORDER_ID}
Content-Type: application/jsonCall this route only after the deployment bundle has issued the org API key. For finance CFD workflows, set workflow_key to cfd_trade_execution and use one idempotency key per execution intent so retries replay safely without flattening live decision volume.
It exposes the protocol decision surface directly, preserves resolved metadata such as decision_domain and vertical_pack, and avoids coupling new partner integrations to a wrapper-specific response contract.
This is the recommended generic finance payload for a broker or partner workflow evaluating a CFD order request.
curl -X POST https://api.decionis.com/v1/protocol/evaluate-decision -H "Authorization: Bearer dcy_org_xxx" -H "Idempotency-Key: cfd-order-${ORDER_ID}" -H "Content-Type: application/json" -d '{
"org_id": "11111111-1111-4111-8111-111111111111",
"decision_type": "CFD_TRADE_EXECUTION",
"amount": 18000,
"risk_score": 0.74,
"objective_profile": "risk_conservative",
"mode": "ENFORCEMENT",
"workflow_key": "cfd_trade_execution",
"vertical_pack": "cfd_trade_execution",
"context": {
"broker": "Geminix Capital",
"instrument": "EURUSD",
"side": "BUY",
"order_type": "MARKET",
"notional": 18000,
"leverage": 12,
"margin_available": 5400,
"stop_loss": 1.0715,
"take_profit": 1.094,
"time_in_force": "GTC",
"approval_path": ["desk_risk", "finance_control"],
"policy_version": "cfd_trade_execution-v1",
"override_reason_code": null
}
}'Supply instrument, side, order_type, leverage, margin_available, approval_path, and policy_version. Provide either size or notional so the workflow pack can satisfy the size_or_notional requirement.
Include stop_loss, take_profit, time_in_force, and any broker order controls so the finance engine can distinguish bounded orders from trades that require escalation or tighter review.
The canonical response preserves protocol evaluation fields plus the resolved finance workflow metadata.
| Field | Meaning |
|---|---|
| outcome | Governed result such as APPROVE, REJECT, or ESCALATE. |
| policy_version | Policy version used for the evaluation. |
| policy_snapshot | Hash-backed reference to the encoded policy bundle evaluated by the protocol. |
| reason_codes | Stable Decionis reason codes for audit, UI handling, and SDK errors. |
| decision_domain | Resolved domain, such as CFD_TRADE_EXECUTION. |
| vertical_pack | Resolved workflow pack metadata including key and source. |
| dossier_id | Decision Dossier identifier for later retrieval or verification. |
| governance_metrics | Rollout and governance telemetry for the evaluated decision. |
{
"outcome": "ESCALATE",
"confidence": 0.91,
"policy_version": "cfd_trade_execution-v1",
"policy_snapshot": {
"policy_version": "cfd_trade_execution-v1",
"policy_bundle_id": "aaaaaaaa-aaaa-4aaa-8aaa-000000000001",
"rules_sha256": "7c9f...",
"parameters_sha256": "b31a...",
"effective_from": "2026-05-04T00:00:00.000Z",
"effective_to": null,
"evaluated_at": "2026-05-04T06:44:51.799Z",
"source": "org_policy_bundle"
},
"objective_profile": "risk_conservative",
"dossier_id": "22222222-2222-4222-8222-222222222222",
"dossier_sha256": "hash-1",
"evaluation_id": "33333333-3333-4333-8333-333333333333",
"decision_resolution_id": "44444444-4444-4444-8444-444444444444",
"ledger_entry_id": "55555555-5555-4555-8555-555555555555",
"ledger_entry_hash": "ledger-hash",
"mode": "ENFORCEMENT",
"reason_codes": [
"PROTOCOL_OUTCOME_ESCALATE",
"POLICY_MATCHED",
"POLICY_ACTION_REQUIRE_REVIEW"
],
"reconciliation_required": true,
"reconciliation_status": "PENDING",
"decision_domain": "CFD_TRADE_EXECUTION",
"vertical_pack": {
"key": "cfd_trade_execution",
"source": "workflow_key",
"workflow_key": "cfd_trade_execution"
},
"decision_chain": {
"chain_id": "77777777-7777-4777-8777-777777777777",
"workflow_id": "cfd-order-flow-001",
"step_id": "broker_execution_gate",
"root_evaluation_id": "33333333-3333-4333-8333-333333333333",
"parent_evaluation_ids": [],
"parent_dossier_ids": [],
"lineage_depth": 0,
"integrity_hash": "chain-hash",
"chain_api_path": "/v1/protocol/decision-chains/77777777-7777-4777-8777-777777777777?org_id=11111111-1111-4111-8111-111111111111"
},
"governance_metrics": {
"override_drift_rate": 0.1,
"governance_tension_index": 0.2,
"boundary_volatility_score": 0.3,
"decision_volume_under_governance": 1
},
"idempotent_replay": false
}Link related Decionis evaluations into workflow lineage so an auditor can reconstruct why an execution path was allowed, blocked, or escalated.
/v1/protocol/decision-chains/:chainIdAPI keyRetrieve the ordered Decision Chain with dossier links and integrity verification for every linked step.
curl "https://api.decionis.com/v1/protocol/decision-chains/77777777-7777-4777-8777-777777777777?org_id=11111111-1111-4111-8111-111111111111" -H "Authorization: Bearer dcy_org_xxx"Send decision_chain.parent_evaluation_ids or parent_dossier_ids on evaluate-decision when the current action depends on prior Decionis decisions.
The chain contains decision and dossier references, step identity, lineage depth, and integrity hashes. It does not expose policy rules or thresholds to the application.
Read protocol-owned rollout evidence from saved SHADOW evaluate-decision records without exposing policy rules to the integrating application.
/v1/protocol/shadow-reportsAPI keyAggregate observe-only decisions into adoption proof, near misses, and candidate enforcement paths.
curl "https://api.decionis.com/v1/protocol/shadow-reports?org_id=11111111-1111-4111-8111-111111111111&days=30&limit=50" -H "Authorization: Bearer dcy_org_xxx"The report returns would-block, would-escalate, policy-drift, near-miss, and candidate-enforcement-path cards sourced from protocol decision rows.
Use POST /v1/protocol/shadow-reports/export for a hashable JSON artifact suitable for enforcement-readiness review and rollout signoff.
{
"summary": {
"shadow_evaluations": 120,
"would_allow": 96,
"would_block": 4,
"would_escalate": 12,
"review_required": 8,
"policy_drift_count": 3,
"near_miss_count": 9,
"candidate_enforcement_path_count": 2
},
"candidate_enforcement_paths": [
{
"path_key": "cfd_trade_execution",
"total": 80,
"non_allow_rate": 0.05,
"recommendation": "CANDIDATE_FOR_ENFORCEMENT"
}
]
}Reason codes are a stable protocol vocabulary. Applications should branch on ALLOW, BLOCK, ESCALATE, or REVIEW_REQUIRED; reason codes are for explanation, audit, and support workflows.
| Route | Purpose |
|---|---|
| GET /v1/protocol/reason-codes | Discover stable Decionis reason-code definitions and categories. |
| reason_codes | Returned by protocol and SDK-compatible decision responses when Decionis can normalize the outcome, policy guard, and selected policy action. |
Keep the wrapper route documented, but clearly subordinate it to the canonical protocol route.
You are integrating a new governed decision flow directly, you want the protocol response as-is, or you need the resolved decision_domain and vertical_pack metadata in the response.
An existing adapter or workflow surface already expects the action-gate response envelope and you are intentionally working through that higher-level abstraction.
/v1/action-gate/evaluateAPI keyHigher-level wrapper route that remains available for compatibility and surface-specific adapters.