Risk score ( risk_score )

Role

The risk score serves as a quantitative signal in decision processes: credit granting, order ceiling, triggering enhanced checks. It is produced by an external scoring engine — your own model, a risk provider, or an internal rule — and recorded on the platform through the API.

Object immutability guarantees complete traceability: you can retrieve which score was in effect at decision time, compare results across model versions, and automatically detect deterioration or improvement in a company's profile.

Identifier and structure

Every score has a stable identifier prefixed with rsk_. The factors field is a free-form object whose structure is defined by your model.

{
"object": "risk_score",
"id": "rsk_4c2e9f8a1b3d5e7f",
"company_id": "cmp_3a8f1d9c2b4e7f6a",
"score": 72,
"model_version": "credit-v2.1",
"factors": {
  "payment_history": 88,
  "outstanding_balance": 55,
  "credit_utilization": 71,
  "time_as_customer": 90
},
"source_reference": null,
"metadata": {},
"computed_at": "2026-06-17T08:00:00.000Z",
"created_at": "2026-06-17T08:01:00.000Z"
}

Fields

Score and interpretation

The score is an integer between 0 and 100. The convention is: the higher the score, the better the risk profile — a score of 90 indicates a reliable company, while 20 indicates high risk. This convention is reflected in events: risk_score.degraded triggers when the score decreases, and risk_score.improved when it increases.

The model_version field identifies the version of the model or rule that produced this score. It is free-form and defined by your system. It lets you:

• compare scores for the same company across model versions;
• filter history to analyze only scores from one specific version;
• detect regressions when moving to a new model.

The factors field is a free-form JSON object describing the signals that contributed to the score. Its structure is entirely defined by your model — the platform stores and returns it as-is without interpreting it.

History and current score

Every call to POST /v1/risk-scores creates a new independent row. The previous score is never modified or replaced. The complete score list for a company is available through:

GET /v1/risk-scores?company_id=cmp_3a8f

Results are sorted by computed_at descending, newest first.

To retrieve only the most recent score for a company — the “current” score — use the dedicated endpoint:

GET /v1/risk-scores/latest?company_id=cmp_3a8f&merchant_id=mrc_1a2b

{
"id": "rsk_4c2e",
"score": 72,
"model_version": "credit-v2.1"
}

The API returns 404 when no score exists for this company.

In processes

There is no dedicated node for creating a risk_score. The object is typically populated through two paths:

• External system — your scoring engine directly calls POST /v1/risk-scores after every recalculation, such as a nightly batch or triggering event.

• From a process — a connector node calls the risk provider and returns an integer score; an HTTP action in the process then calls POST /v1/risk-scores to persist it.

Once persisted, a company's current score can be retrieved in a process through the generic node fetch_risk_score, which accepts a prefixed identifier rsk_ and returns the object platform.risk_score.

Events

Every score creation triggers up to two events: a systematic event on the company and a direction event when a previous score existed.

All three events carry the complete object risk_score in their payload. Direction events also include a diff with before/after scores, usable to trigger conditional process actions such as alerts, manual review, or credit-limit updates:

{
"id": "rsk_4c2e",
"object": "risk_score",
"company_id": "cmp_3a8f",
"score": 72,
"diff": {
  "before": { "score": 68 },
  "after": { "score": 72 }
}
}

When no previous score exists for the company — the first calculation — company.risk_score_updated is emitted without a diff, and events risk_score.degraded / risk_score.improved are not triggered. When the score is identical to the previous one (delta = 0), only company.risk_score_updated is emitted.