Go back

Decisioning API

The Decisioning API lets you list, inspect, and execute published decision flows, and retrieve execution traces for audit and debugging.

Before you begin:

Endpoints

Environment Base URL
Test https://api.staging.principa.cloud/decisioning/v1
Production https://api.principa.cloud/decisioning/v1

List Active Decision Flows

Returns all active decision flow definitions available to the authenticated account.

GET /flows

Headers

Authorization: Bearer <your_token>

Successful response

Field Type Description
id guid Unique identifier of the decision flow
code string Decision flow code
version integer Decision flow version number

Example response

[
  { "id": "3d5f4d09-e5a1-4c9c-b92b-0f4e6b7c27af", "code": "CREDIT_SCORE_V2", "version": 3 },
  { "id": "8a1c2e34-f6b7-4d8a-a3c1-1e2f3a4b5c6d", "code": "FRAUD_CHECK", "version": 1 }
]

Get Decision Flow Definition

Returns the full definition of a decision flow, including its input and output contract.

GET /flows/{id}

Headers

Authorization: Bearer <your_token>

Path parameters

Parameter Type Description
id guid The unique identifier of the decision flow

Successful response

Field Type Description
id guid Unique identifier
code string Decision flow code
version integer Version number
inputs array List of input field definitions
outputs array List of output field definitions

Each inputs item:

Field Type Description
key string Input field identifier
name string Human-readable label
type string Data type (e.g. string, number)
defaultValue string Default value if not supplied

Each outputs item:

Field Type Description
key string Output field identifier
field string Source field in the flow result
defaultValue string Default value if output is absent
fallback string Fallback value on evaluation failure

Example response

{
  "id": "3d5f4d09-e5a1-4c9c-b92b-0f4e6b7c27af",
  "code": "CREDIT_SCORE_V2",
  "version": 3,
  "inputs": [
    { "key": "income", "name": "Monthly Income", "type": "number", "defaultValue": null },
    { "key": "age", "name": "Age", "type": "number", "defaultValue": null }
  ],
  "outputs": [
    { "key": "decision", "field": "Decision", "defaultValue": "DECLINED", "fallback": "ERROR" },
    { "key": "score", "field": "CreditScore", "defaultValue": "0", "fallback": "0" }
  ]
}

Error responses

Status Description
404 Decision flow not found
403 Decision flow does not belong to this account

Execute

Executes a decision flow against an array of input records for the authenticated account.

POST /flows/execute

Headers

Authorization: Bearer <your_token>

Request body

Field Type Required Notes
code string yes Decision flow code to execute
version integer yes Decision flow version (must be > 0)
productCode string yes Product code for billing
data array of key-value objects yes One object per record; keys must match decision flow inputs

Example request

{
  "code": "CREDIT_SCORE_V2",
  "version": 3,
  "productCode": "DECISION_BASIC",
  "data": [
    { "income": "15000", "age": "34" },
    { "income": "8500", "age": "28" }
  ]
}

Successful response

Field Type Description
success boolean true when the execution is without errors
code string SUCCESS
message string Human-readable result message
count integer Number of records processed
results array Per-record results (see below)

Each results item:

Field Type Description
index integer Zero-based position in the input array
success boolean true if this record was processed
output object (key-value) Decision flow output fields for this record
errors array of string Validation or evaluation errors

Example response

{
  "success": true,
  "code": "SUCCESS",
  "message": "Decision flow executed successfully.",
  "count": 2,
  "results": [
    { "index": 0, "success": true, "output": { "decision": "APPROVED", "score": "720" }, "errors": [] },
    { "index": 1, "success": true, "output": { "decision": "DECLINED", "score": "480" }, "errors": [] }
  ]
}

Error responses

Status Code Description
400 VALIDATION_ERROR Request validation failed (missing/invalid fields)
400 INSUFFICIENT_FUNDS Not enough credits to cover the execution cost
500 INTERNAL_SERVER_ERROR Unexpected error during processing

Unsuccessful response example — Code 400

{
  "success": false,
  "code": "INSUFFICIENT_FUNDS",
  "message": "Not enough funds available."
}

Execute with Mapper

Executes a decision flow against a single external payload, using a saved mapper to translate that payload into the flow's inputs. Use this when the calling system's request shape does not match the flow inputs directly — the mapper does the translation server-side so you can send your own JSON.

POST /flows/execute/with-mapper

Headers

Authorization: Bearer <your_token>

Request body

Field Type Required Notes
flowCode string yes Decision flow code to execute
flowVersion integer no Decision flow version. Omit or 0 for the latest active version
mapperCode string yes Saved mapper code that translates the payload into flow inputs
mapperVersion integer no Mapper version. Omit for the latest active version
productCode string yes Product code for billing
payload object yes Arbitrary JSON object the mapper reads from
validationMode string no Accumulate (default) collects all transform issues; FailFast stops at the first

Example request

{
  "flowCode": "CREDIT_SCORE_V2",
  "mapperCode": "PARTNER_INTAKE",
  "productCode": "DECISION_BASIC",
  "validationMode": "Accumulate",
  "payload": {
    "applicant": {
      "monthlyIncome": 15000,
      "dateOfBirth": "1990-04-12"
    }
  }
}

Successful response

Field Type Description
success boolean true when the transform and the execution both succeeded
code string SUCCESS
message string Human-readable result message
mappedInputs object (key-value) The flow inputs the mapper produced from the payload
output object (key-value) Decision flow output fields
warnings array of Issue Non-fatal mapper issues (see below)
errors array of string Combined transform and flow errors (empty on success)

Each warnings item (Issue):

Field Type Description
key string The flow input key the issue relates to
path string The path within the payload the issue relates to
message string Human-readable description of the issue

Example response

{
  "success": true,
  "code": "SUCCESS",
  "message": "Decision flow executed successfully.",
  "mappedInputs": { "income": "15000", "age": "36" },
  "output": { "decision": "APPROVED", "score": "720" },
  "warnings": [],
  "errors": []
}

Error responses

Status Code Description
400 VALIDATION_ERROR Invalid request, or the payload could not be mapped to required inputs
400 INSUFFICIENT_FUNDS Not enough credits to cover the execution cost
404 NOT_FOUND The flow or mapper code/version does not exist for this account
500 INTERNAL_SERVER_ERROR Unexpected error during processing

Unsuccessful response example — Code 400

When the mapper cannot produce the inputs the flow requires, the offending fields are returned in errors (and any non-fatal issues in warnings):

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "The payload could not be mapped to the decision flow inputs.",
  "mappedInputs": { "income": "15000" },
  "warnings": [],
  "errors": [ "age (applicant.dateOfBirth): required input could not be resolved" ]
}

Retrieve an Execution Trace

Returns the full trace for a previously completed decision flow execution: the inputs supplied, the outputs produced, status, timings, record counts, and the flow's log and error output. Useful for explainability, audit, and debugging.

GET /flows/{executionId}/trace

Headers

Authorization: Bearer <your_token>

Path parameters

Parameter Type Required Notes
executionId guid yes The execution id of the decision flow run

Example request

GET /flows/8d2c7a14-3f44-4d2e-9b81-77f0f5b3a1d2/trace

Successful response

Field Type Description
success boolean true when the trace was retrieved
code string SUCCESS on retrieval, NOT_FOUND on 404
message string Human-readable message
trace object The trace payload (see below)

trace fields:

Field Type Description
executionId guid The execution id
accountId guid Account that owns the execution
workflowDefinitionId guid Definition that was executed
workflowCode string Decision flow code that was executed
workflowVersion integer Decision flow version that was executed
status string Execution status (e.g. Completed, Failed)
startedAt datetime When execution started (UTC)
completedAt datetime When execution finished (UTC)
durationMs integer Total wall-clock duration in milliseconds
inputRecords integer Number of input records processed
outputRecords integer Number of output records emitted
successCount integer Number of records that completed successfully
errorCount integer Number of records that errored
warningCount integer Number of records that emitted a warning
input object (string-string map) Input fields supplied to the execution
output object (string-string map) Output fields produced by the execution
nodes array of Node Each node visited during execution (see below)
logs array of string Log lines emitted during execution
errors array of Error Structured errors and warnings (see below)

nodes[] fields:

Field Type Description
id string Node id within the decision flow definition
success boolean Whether the node completed successfully
isFinal boolean Whether the node is a terminal node
executionTime timespan Time spent evaluating this node
outputs object Output values produced by the node
logs array of string Log lines emitted by this node
errors array of string Errors emitted by this node

errors[] fields:

Field Type Description
level string Severity (Error, Warning, Info)
message string Human-readable message
timestamp datetime When the entry was emitted (UTC)
nodeId string Node that emitted the entry, if applicable
nodeName string Human-readable node name, if applicable

Example response

{
  "success": true,
  "code": "SUCCESS",
  "message": "Execution trace retrieved.",
  "trace": {
    "executionId": "8d2c7a14-3f44-4d2e-9b81-77f0f5b3a1d2",
    "accountId": "a3f1c2d4-9b8e-4c52-9f10-2a7b6d1e3c44",
    "workflowDefinitionId": "f17a9b2c-1d4e-4a8b-9c3d-5e6f7a8b9c0d",
    "workflowCode": "AFFORD_V1",
    "workflowVersion": 3,
    "status": "Completed",
    "startedAt": "2026-05-26T10:42:11Z",
    "completedAt": "2026-05-26T10:42:11Z",
    "durationMs": 312,
    "inputRecords": 1,
    "outputRecords": 1,
    "successCount": 1,
    "errorCount": 0,
    "warningCount": 0,
    "input": {
      "monthlyIncome": "25000",
      "monthlyExpenses": "12000"
    },
    "output": {
      "decision": "APPROVED",
      "affordabilityScore": "0.72"
    },
    "nodes": [
      {
        "id": "income-floor",
        "success": true,
        "isFinal": false,
        "executionTime": "00:00:00.0120000",
        "outputs": { "pass": true },
        "logs": ["monthlyIncome >= 5000"],
        "errors": []
      },
      {
        "id": "decision",
        "success": true,
        "isFinal": true,
        "executionTime": "00:00:00.0040000",
        "outputs": { "decision": "APPROVED" },
        "logs": [],
        "errors": []
      }
    ],
    "logs": [
      "Loaded definition AFFORD_V1 v3",
      "Evaluated rule R-INCOME-FLOOR: pass"
    ],
    "errors": []
  }
}

Not found

A 404 is returned when the execution id is unknown OR when the execution exists but belongs to a different account. Existence is deliberately not leaked.

{
  "success": false,
  "code": "NOT_FOUND",
  "message": "Execution trace not found."
}

Authorization

All endpoints require a valid bearer token. Include it in the Authorization header of every request:

Authorization: Bearer <your_token>

See How to Authenticate for details on obtaining a token.

An unhandled error has occurred. Reload 🗙