Risk API · v1 · sandbox
This API is in its sandbox. A test key reads a made-up ledger run through the real method, and every answer says sample: true. Live keys are refused until 4 Seasons opens it, and the real ledger is still small, so many step kinds will be refused for now. No insurer or lender has agreed to use these numbers.
A job where every step has enough behind it
Sandbox sampleFILE-2291 · $4,180.00 of step value
project.waterproof
$1,180.00
$38.79 expected, $16.61 to $71.386 of 64 verified had a problem later
project.shower
$2,360.00
$52.04 expected, $14.07 to $121.553 of 58 verified had a problem later
project.paint
$640.00
$4.11 expected, $0.17 to $14.980 of 47 verified had a problem later
Expected loss on the job
$94.94
$30.85 to $207.91 at 90% · smallest sample 47 · step-risk/1
A job with one step that does not
Sandbox sampleFILE-2292 · $2,700.00 of step value
project.waterproof
$1,180.00
$38.79 expected, $16.61 to $71.386 of 64 verified had a problem later
project.floor
$1,520.00
Not enough data. 9 verified, 30 needed
No band for this job 422 not_enough_data
Not enough verified work yet on this step kind (project.floor). No band is given for the job until every step has 30 followed instances and a cost and a value on record.
Read the method
The version, the interval level, how long a finished step is followed and the minimum sample. Keep the version with any number you keep.
GET /risk
See what has a number
Each step kind with work on record, its sample, and its rate and expected loss where it has the minimum. The rest say what is missing.
GET /risk/step-kinds
Ask about a job
Send its steps with their kinds and values. You get a band for the job, or a refusal that names the steps without enough behind them.
POST /risk/jobs
GET /risk returns the ones in force.422 not_enough_data with each step's counts. A sum over the steps that do have data would read as the whole job's risk, and it would not be.step-risk/1. It is deliberately plain, so a reader can check it by hand from the counts in each answer./api/v1, amounts in integer cents, the risk:read scope on every call.The method, its version, the minimum sample and what the numbers rest on
How the step risk numbers are worked out: the method version, the interval level, the days a finished step is followed, the minimum sample below which nothing is answered, and how many verified steps and later failures stand behind the whole table.
No parameters.
curl "https://www.build4seasons.com/api/v1/risk" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"livemode": false,
"sample": true,
"method": "step-risk/1",
"asOf": "2026-01-01T00:00:00.000Z",
"notice": "Sample data from the sandbox's made-up ledger, run through the real method. It describes no real work. Read from 4 Seasons' own work ledger by the method named here. It is not a rating, a quote or an offer of cover or credit, and no outside firm has agreed to rely on it.",
"intervalLevel": 0.9,
"windowDays": 365,
"minimums": {
"followedInstances": 30,
"costedFailures": 5
},
"prior": {
"laterFailureRate": 0.05,
"weightInInstances": 20
},
"basis": {
"verifiedSteps": 219,
"laterFailures": 12,
"markets": 1,
"firstFinished": "2024-05-12T00:00:00.000Z",
"lastFinished": "2024-11-27T00:00:00.000Z",
"stepKindsWithANumber": 4,
"stepKindsBelowMinimum": 1
},
"definitions": {
"verified": "A finished step a person judged and passed.",
"followed": "Verified steps weighted by how much of the window each has been watched. A step with a later failure counts whole.",
"laterFailure": "A callback, warranty claim, leak, punch item after completion, dispute or refund linked back to the step, inside the window, with a cause that is the work's.",
"stepValue": "The pay recorded for the step.",
"lossPer1000": "Expected loss in dollars per $1,000 of step value: rate × cost of a failure ÷ step value × 1,000."
}
}Each step kind with work on record: sample, later-failure rate, cost and expected loss
Every step kind that has finished work on record, with how many verified instances stand behind it. The rate, the cost of a failure and the expected loss per $1,000 of step value are null where the kind is below the minimum, and notEnough says what is missing.
No parameters.
curl "https://www.build4seasons.com/api/v1/risk/step-kinds" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"livemode": false,
"sample": true,
"method": "step-risk/1",
"asOf": "2026-01-01T00:00:00.000Z",
"notice": "Sample data from the sandbox's made-up ledger, run through the real method. It describes no real work. Read from 4 Seasons' own work ledger by the method named here. It is not a rating, a quote or an offer of cover or credit, and no outside firm has agreed to rely on it.",
"stepKinds": [
{
"stepKind": "project.waterproof",
"title": "Backer board and waterproofing",
"trade": "tile",
"verified": 64,
"followed": 64,
"laterFailures": 6,
"enough": true,
"laterFailureRate": {
"mean": 0.0833,
"low": 0.0403,
"high": 0.1377
},
"costPerFailureCents": {
"mean": 46854,
"low": 41525,
"high": 52183
},
"costBasis": "own",
"costedFailures": 6,
"meanStepValueCents": 118774,
"lossPer1000": {
"mean": 32.87,
"low": 14.07,
"high": 60.5
},
"notEnough": null
},
{
"stepKind": "project.shower",
"title": "Shower or tub and walls",
"trade": "tile",
"verified": 58,
"followed": 58,
"laterFailures": 3,
"enough": true,
"laterFailureRate": {
"mean": 0.0513,
"low": 0.0179,
"high": 0.0976
},
"costPerFailureCents": {
"mean": 101596,
"low": 78548,
"high": 124644
},
"costBasis": "all_kinds",
"costedFailures": 12,
"meanStepValueCents": 236265,
"lossPer1000": {
"mean": 22.05,
"low": 5.96,
"high": 51.5
},
"notEnough": null
},
{
"stepKind": "project.paint",
"title": "Paint",
"trade": "painting",
"verified": 47,
"followed": 47,
"laterFailures": 0,
"enough": true,
"laterFailureRate": {
"mean": 0.0149,
"low": 0.0008,
"high": 0.0444
},
"costPerFailureCents": {
"mean": 27114,
"low": 20963,
"high": 33265
},
"costBasis": "all_kinds",
"costedFailures": 12,
"meanStepValueCents": 63054,
"lossPer1000": {
"mean": 6.42,
"low": 0.26,
"high": 23.41
},
"notEnough": null
},
{
"stepKind": "task.toilet",
"title": "Replace a toilet",
"trade": "plumbing",
"verified": 41,
"followed": 41,
"laterFailures": 2,
"enough": true,
"laterFailureRate": {
"mean": 0.0492,
"low": 0.0138,
"high": 0.1012
},
"costPerFailureCents": {
"mean": 5962,
"low": 4610,
"high": 7315
},
"costBasis": "all_kinds",
"costedFailures": 12,
"meanStepValueCents": 13866,
"lossPer1000": {
"mean": 21.15,
"low": 4.58,
"high": 53.41
},
"notEnough": null
},
{
"stepKind": "project.floor",
"title": "Floor",
"trade": "flooring",
"verified": 9,
"followed": 9,
"laterFailures": 1,
"enough": false,
"laterFailureRate": null,
"costPerFailureCents": null,
"costBasis": "all_kinds",
"costedFailures": 12,
"meanStepValueCents": null,
"lossPer1000": null,
"notEnough": "Not enough data. 9 of 30 verified instances followed, 9 of 30 instances with their pay on record"
}
]
}The expected loss band for a job you describe by its steps
Send the job's steps, each with its step kind and its value. The answer is the expected loss in cents with its interval, per step and for the job, with the sample behind each step and the method version. When any step's kind is below the minimum the answer is 422 not_enough_data with each step's counts, and no band is given for the job. Nothing is stored.
referencestringBody
Your own reference for the job, echoed back
stepsobject[]Bodyrequired
The job's steps
steps[].keystringBodyrequired
Your key for the step
steps[].stepKindstringBodyrequired
A step kind from the work ontology, such as project.waterproof
steps[].valueCentsintegerBodyrequired
The step's value in cents: what is paid for it
curl -X POST "https://www.build4seasons.com/api/v1/risk/jobs" \
-H "authorization: Bearer $FOURS_KEY" \
-H "content-type: application/json" \
-d '{"reference":"FILE-2291","steps":[{"key":"waterproof","stepKind":"project.waterproof","valueCents":118000},{"key":"shower","stepKind":"project.shower","valueCents":236000},{"key":"paint","stepKind":"project.paint","valueCents":64000}]}'The answer200
{
"livemode": false,
"sample": true,
"method": "step-risk/1",
"asOf": "2026-01-01T00:00:00.000Z",
"notice": "Sample data from the sandbox's made-up ledger, run through the real method. It describes no real work. Read from 4 Seasons' own work ledger by the method named here. It is not a rating, a quote or an offer of cover or credit, and no outside firm has agreed to rely on it.",
"reference": "FILE-2291",
"intervalLevel": 0.9,
"windowDays": 365,
"valueCents": 418000,
"answered": true,
"expectedLossCents": {
"mean": 9494,
"low": 3085,
"high": 20791
},
"lossPer1000": {
"mean": 22.71,
"low": 7.38,
"high": 49.74
},
"smallestSample": 47,
"steps": [
{
"key": "waterproof",
"stepKind": "project.waterproof",
"valueCents": 118000,
"status": "ok",
"verified": 64,
"followed": 64,
"laterFailures": 6,
"needed": 30,
"costBasis": "own",
"costedFailures": 6,
"lossPer1000": {
"mean": 32.87,
"low": 14.07,
"high": 60.5
},
"expectedLossCents": {
"mean": 3879,
"low": 1661,
"high": 7138
}
},
{
"key": "shower",
"stepKind": "project.shower",
"valueCents": 236000,
"status": "ok",
"verified": 58,
"followed": 58,
"laterFailures": 3,
"needed": 30,
"costBasis": "all_kinds",
"costedFailures": 12,
"lossPer1000": {
"mean": 22.05,
"low": 5.96,
"high": 51.5
},
"expectedLossCents": {
"mean": 5204,
"low": 1407,
"high": 12155
}
},
{
"key": "paint",
"stepKind": "project.paint",
"valueCents": 64000,
"status": "ok",
"verified": 47,
"followed": 47,
"laterFailures": 0,
"needed": 30,
"costBasis": "all_kinds",
"costedFailures": 12,
"lossPer1000": {
"mean": 6.42,
"low": 0.26,
"high": 23.41
},
"expectedLossCents": {
"mean": 411,
"low": 17,
"high": 1498
}
}
]
}With a step below the minimum422
{
"error": {
"code": "not_enough_data",
"message": "Not enough verified work yet on this step kind (project.floor). No band is given for the job until every step has 30 followed instances and a cost and a value on record."
},
"livemode": false,
"sample": true,
"method": "step-risk/1",
"asOf": "2026-01-01T00:00:00.000Z",
"notice": "Sample data from the sandbox's made-up ledger, run through the real method. It describes no real work. Read from 4 Seasons' own work ledger by the method named here. It is not a rating, a quote or an offer of cover or credit, and no outside firm has agreed to rely on it.",
"reference": "FILE-2292",
"intervalLevel": 0.9,
"windowDays": 365,
"valueCents": 270000,
"answered": false,
"steps": [
{
"key": "waterproof",
"stepKind": "project.waterproof",
"valueCents": 118000,
"status": "ok",
"verified": 64,
"followed": 64,
"laterFailures": 6,
"needed": 30,
"costBasis": "own",
"costedFailures": 6,
"lossPer1000": {
"mean": 32.87,
"low": 14.07,
"high": 60.5
},
"expectedLossCents": {
"mean": 3879,
"low": 1661,
"high": 7138
}
},
{
"key": "floor",
"stepKind": "project.floor",
"valueCents": 152000,
"status": "below_minimum",
"verified": 9,
"followed": 9,
"laterFailures": 1,
"needed": 30,
"costBasis": "all_kinds",
"costedFailures": 12,
"lossPer1000": null,
"expectedLossCents": null
}
]
}{ error: { code, message } }. Every request is counted against the key's limit per minute and logged with its path, status and time, never its body.| Status | Code | When |
|---|---|---|
| 422 | not_enough_data | A step's kind is below the minimum sample, or has no work on record. The answer lists each step with its counts and gives no band for the job. |
| 403 | risk_api_off | A live key, before 4 Seasons has opened the API to live keys. Test keys read the sandbox's sample data. |
| 403 | forbidden | The key doesn't have the risk:read scope. |
| 400 | invalid_request | The body doesn't match the schema: no steps, more than 100, or a step without a kind or a value. |
| 429 | rate_limited | More requests in a minute than the key's limit. retry-after says when to try again. |