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-001
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 so the protocol layer resolves the correct pack metadata and policy defaults.
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-001" -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. |
| 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",
"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",
"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"
},
"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
}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.