Quickstart · about five minutes
Sign in to your dashboard, switch to Test and make a test key. It starts with 4s_test_ and is shown once. Everything below runs in the sandbox: no real money, no ledger, no real rail.
export FOURS_KEY=4s_test_…By your own id for them. Calling again with the same id returns the same executor. In the sandbox they come with a verified pay account.
curl -X POST "https://www.build4seasons.com/api/v1/settlement/executors" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: executor-tech-77" \
-H "content-type: application/json" \
-d '{"externalRef":"tech-77","name":"Sample Plumbing Co","email":"dispatch@example.com"}'{
"id": "844df2fc-9526-4633-ac1f-779e47281496",
"object": "settlement_executor",
"livemode": false,
"kind": "own",
"externalRef": "tech-77",
"name": "Sample Plumbing Co",
"executor": "person",
"machine": null,
"payoutRail": null,
"rails": {
"whop": false,
"stripe": true
},
"ready": true,
"createdAt": "2026-11-10T14:22:00.000Z"
}Each step names a step kind, the standard it is judged on, and its pay in cents. Your reference works anywhere an id does.
POST/settlement/jobs
curl -X POST "https://www.build4seasons.com/api/v1/settlement/jobs" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: claim-881" \
-H "content-type: application/json" \
-d '{"title":"Leak under the kitchen sink","reference":"CLAIM-881","site":{"address":"1180 Sample Ave NE","city":"Atlanta","county":"Fulton","state":"GA","zip":"30306"},"owner":{"name":"Sample Homeowner"},"workSpec":{"family":"repair.leak","steps":[{"key":"fix","name":"Find and repair the leak","kind":"task.leak-repair","payoutCents":20000},{"key":"inspect","name":"Final inspection","kind":"inspection.final-building","payoutCents":7500}]}}'{
"id": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"object": "settlement_job",
"livemode": false,
"number": "SJ-1001",
"reference": "CLAIM-881",
"title": "Leak under the kitchen sink",
"status": "open",
"site": {
"zip": "30306",
"city": "Atlanta",
"state": "GA",
"county": "Fulton",
"address": "1180 Sample Ave NE"
},
"owner": {
"name": "Sample Homeowner"
},
"family": "repair.leak",
"loan": null,
"steps": [
{
"id": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"key": "fix",
"seq": 1,
"name": "Find and repair the leak",
"stepKind": {
"id": "task.leak-repair",
"version": 1
},
"proofPlan": [
{
"shot": "leak-before",
"label": "Where the water was coming from"
},
{
"shot": "leak-after",
"label": "The repair, dry"
}
],
"measurements": [],
"payoutCents": 20000,
"executorId": null,
"status": "open",
"rounds": 0,
"verdict": null,
"verifiedAt": null,
"release": null
},
{
"id": "46096d88-9562-400c-a506-21e937630643",
"key": "inspect",
"seq": 2,
"name": "Final inspection",
"stepKind": {
"id": "inspection.final-building",
"version": 1
},
"proofPlan": [
{
"shot": "result-card",
"label": "Inspection card or result"
}
],
"measurements": [],
"payoutCents": 7500,
"executorId": null,
"status": "open",
"rounds": 0,
"verdict": null,
"verifiedAt": null,
"release": null
}
],
"createdAt": "2026-11-10T14:23:00.000Z",
"completedAt": null
}All steps not yet verified, or the ones you name.
curl -X POST "https://www.build4seasons.com/api/v1/settlement/jobs/CLAIM-881/executors" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: claim-881-attach" \
-H "content-type: application/json" \
-d '{"executor":"844df2fc-9526-4633-ac1f-779e47281496"}'{
"id": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"object": "settlement_job",
"livemode": false,
"number": "SJ-1001",
"reference": "CLAIM-881",
"title": "Leak under the kitchen sink",
"status": "open",
"site": {
"zip": "30306",
"city": "Atlanta",
"state": "GA",
"county": "Fulton",
"address": "1180 Sample Ave NE"
},
"owner": {
"name": "Sample Homeowner"
},
"family": "repair.leak",
"loan": null,
"steps": [
{
"id": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"key": "fix",
"seq": 1,
"name": "Find and repair the leak",
"stepKind": {
"id": "task.leak-repair",
"version": 1
},
"proofPlan": [
{
"shot": "leak-before",
"label": "Where the water was coming from"
},
{
"shot": "leak-after",
"label": "The repair, dry"
}
],
"measurements": [],
"payoutCents": 20000,
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"status": "open",
"rounds": 0,
"verdict": null,
"verifiedAt": null,
"release": null
},
{
"id": "46096d88-9562-400c-a506-21e937630643",
"key": "inspect",
"seq": 2,
"name": "Final inspection",
"stepKind": {
"id": "inspection.final-building",
"version": 1
},
"proofPlan": [
{
"shot": "result-card",
"label": "Inspection card or result"
}
],
"measurements": [],
"payoutCents": 7500,
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"status": "open",
"rounds": 0,
"verdict": null,
"verifiedAt": null,
"release": null
}
],
"createdAt": "2026-11-10T14:23:00.000Z",
"completedAt": null
}Photos go as the SHA-256 of each file, with the shot from the step's proof plan and when and where it was taken. X-4S-Simulate picks the sandbox reviewer's answer: happy, fail_verification or review.
curl -X POST "https://www.build4seasons.com/api/v1/settlement/jobs/CLAIM-881/steps/inspect/proof" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: claim-881-inspect-1" \
-H "x-4s-simulate: happy" \
-H "content-type: application/json" \
-d '{"photos":[{"shot":"result-card","sha256":"3149459194e3c5db180c80619fff8f085b69cdb2671ba90508fd73b11cfdbad3","capturedAt":"2026-11-10T14:02:00.000Z","lat":33.7849,"lng":-84.3497,"accuracyM":6}],"inspection":{"result":"pass","inspector":"Sample County inspector","at":"2026-11-10T14:04:00.000Z","corrections":[]}}'{
"id": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"object": "settlement_job",
"livemode": false,
"number": "SJ-1001",
"reference": "CLAIM-881",
"title": "Leak under the kitchen sink",
"status": "completed",
"site": {
"zip": "30306",
"city": "Atlanta",
"state": "GA",
"county": "Fulton",
"address": "1180 Sample Ave NE"
},
"owner": {
"name": "Sample Homeowner"
},
"family": "repair.leak",
"loan": null,
"steps": [
{
"id": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"key": "fix",
"seq": 1,
"name": "Find and repair the leak",
"stepKind": {
"id": "task.leak-repair",
"version": 1
},
"proofPlan": [
{
"shot": "leak-before",
"label": "Where the water was coming from"
},
{
"shot": "leak-after",
"label": "The repair, dry"
}
],
"measurements": [],
"payoutCents": 20000,
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"status": "verified",
"rounds": 1,
"verdict": {
"verdict": "accept",
"confidence": 0,
"ruleVersion": "oracle-1/task.leak-repair@1/r1",
"reasons": [
"waiting on photo checks"
],
"waitingOn": [
"Waiting on evidence"
],
"decidedBy": "human",
"at": "2026-11-10T14:04:00.000Z"
},
"verifiedAt": "2026-11-10T14:04:00.000Z",
"release": {
"id": "1a6a6ac0-63b3-4d90-a685-c5d6de69bba7",
"object": "settlement_release",
"livemode": false,
"jobId": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"stepId": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"drawId": null,
"kind": "step",
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"amountCents": 20000,
"feeCents": 200,
"status": "sent",
"rail": "stripe",
"heldReason": null,
"createdAt": "2026-11-10T14:04:00.000Z",
"sentAt": "2026-11-10T14:04:00.000Z"
}
},
{
"id": "46096d88-9562-400c-a506-21e937630643",
"key": "inspect",
"seq": 2,
"name": "Final inspection",
"stepKind": {
"id": "inspection.final-building",
"version": 1
},
"proofPlan": [
{
"shot": "result-card",
"label": "Inspection card or result"
}
],
"measurements": [],
"payoutCents": 7500,
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"status": "verified",
"rounds": 1,
"verdict": {
"verdict": "accept",
"confidence": 1,
"ruleVersion": "oracle-1/inspection.final-building@1/r1",
"reasons": [],
"waitingOn": [
"The inspector's result moves an inspection; the oracle only records it"
],
"decidedBy": "oracle",
"at": "2026-11-10T14:04:00.000Z"
},
"verifiedAt": "2026-11-10T14:04:00.000Z",
"release": {
"id": "7ed67060-40f5-4b06-af81-b8ca6125f3ab",
"object": "settlement_release",
"livemode": false,
"jobId": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"stepId": "46096d88-9562-400c-a506-21e937630643",
"drawId": null,
"kind": "step",
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"amountCents": 7500,
"feeCents": 75,
"status": "sent",
"rail": "stripe",
"heldReason": null,
"createdAt": "2026-11-10T14:04:00.000Z",
"sentAt": "2026-11-10T14:04:00.000Z"
}
}
],
"createdAt": "2026-11-10T14:23:00.000Z",
"completedAt": "2026-11-10T14:04:00.000Z"
}Each verified step has one release: its pay, the fee, the rail and when it left.
curl "https://www.build4seasons.com/api/v1/settlement/releases?job=CLAIM-881&limit=50" \
-H "authorization: Bearer $FOURS_KEY"{
"object": "list",
"livemode": false,
"data": [
{
"id": "1a6a6ac0-63b3-4d90-a685-c5d6de69bba7",
"object": "settlement_release",
"livemode": false,
"jobId": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"stepId": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"drawId": null,
"kind": "step",
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"amountCents": 20000,
"feeCents": 200,
"status": "sent",
"rail": "stripe",
"heldReason": null,
"createdAt": "2026-11-10T14:04:00.000Z",
"sentAt": "2026-11-10T14:04:00.000Z"
},
{
"id": "7ed67060-40f5-4b06-af81-b8ca6125f3ab",
"object": "settlement_release",
"livemode": false,
"jobId": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"stepId": "46096d88-9562-400c-a506-21e937630643",
"drawId": null,
"kind": "step",
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"amountCents": 7500,
"feeCents": 75,
"status": "sent",
"rail": "stripe",
"heldReason": null,
"createdAt": "2026-11-10T14:04:00.000Z",
"sentAt": "2026-11-10T14:04:00.000Z"
}
],
"hasMore": false,
"nextCursor": null
}The signed Verified Work Record of the job. Hand it to anyone; they can check it themselves.
curl "https://www.build4seasons.com/api/v1/settlement/jobs/CLAIM-881/record" \
-H "authorization: Bearer $FOURS_KEY"{
"object": "work_record",
"livemode": false,
"record": {
"job": {
"id": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"kind": "work_order",
"title": "Leak under the kitchen sink",
"market": null,
"number": "SJ-1001",
"status": "completed",
"closedAt": "2026-11-10T14:04:00.000Z",
"openedAt": "2026-11-10T14:23:00.000Z",
"reference": "CLAIM-881"
},
"home": {
"id": null,
"zip": "30306",
"unit": null,
"address": "1180 Sample Ave NE"
},
"steps": [
{
"pay": {
"paidAt": "2026-11-10T14:04:00.000Z",
"status": "paid",
"releasedAt": "2026-11-10T14:04:00.000Z"
},
"ref": "settlement_step:3e697db8-5927-4893-a87c-35f0ab27fcde",
"seq": 1,
"area": null,
"proof": {
"parts": [],
"checks": [],
"photos": [
{
"id": "82d0e655-966a-4473-a9ae-835ef3266456:0",
"shot": "leak-before",
"round": 1,
"sha256": "9354dad2dfaf58260ded1e93774b419ed44dbcbfc9360510b4daaaf4a5a8419f",
"source": "settlement_api",
"takenBy": "executor",
"capturedAt": "2026-11-10T14:02:00.000Z"
},
{
"id": "82d0e655-966a-4473-a9ae-835ef3266456:1",
"shot": "leak-after",
"round": 1,
"sha256": "ee6d88c6e7d74c82b2342053411412a1c68ffdcd67cb5cb643dce07a14ac5281",
"source": "settlement_api",
"takenBy": "executor",
"capturedAt": "2026-11-10T14:02:00.000Z"
}
],
"measurements": []
},
"trade": "plumbing",
"units": 1,
"rework": 0,
"outcome": "Find and repair the leak",
"verdict": {
"by": "person",
"oracle": {
"at": "2026-11-10T14:04:00.000Z",
"id": "82d0e655-966a-4473-a9ae-835ef3266456",
"applied": "verified",
"checker": null,
"verdict": "accept",
"decidedBy": "human",
"confidence": 0,
"ruleVersion": "oracle-1/task.leak-repair@1/r1"
},
"result": "pass",
"judgements": [
{
"at": "2026-11-10T14:04:00.000Z",
"source": "settlement_review",
"verdict": "pass",
"superseded": false,
"reasonCodes": [],
"reviewerRole": "reviewer"
}
]
},
"executor": {
"id": "844df2fc-9526-4633-ac1f-779e47281496",
"kind": "trade_partner",
"name": "Sample Plumbing Co",
"license": null,
"credentials": [],
"supervisorOfRecord": null
},
"stepKind": {
"id": "task.leak-repair",
"version": 1
},
"startedAt": "2026-11-10T14:01:00.000Z",
"finishedAt": "2026-11-10T14:04:00.000Z",
"activeMinutes": null
},
{
"pay": {
"paidAt": "2026-11-10T14:04:00.000Z",
"status": "paid",
"releasedAt": "2026-11-10T14:04:00.000Z"
},
"ref": "settlement_step:46096d88-9562-400c-a506-21e937630643",
"seq": 2,
"area": null,
"proof": {
"parts": [],
"checks": [],
"photos": [
{
"id": "4a8be774-edaf-4993-a79c-66a3e973afb6:0",
"shot": "result-card",
"round": 1,
"sha256": "3149459194e3c5db180c80619fff8f085b69cdb2671ba90508fd73b11cfdbad3",
"source": "settlement_api",
"takenBy": "executor",
"capturedAt": "2026-11-10T14:02:00.000Z"
}
],
"measurements": []
},
"trade": "inspection",
"units": 1,
"rework": 0,
"outcome": "Final inspection",
"verdict": {
"by": "oracle",
"oracle": {
"at": "2026-11-10T14:04:00.000Z",
"id": "4a8be774-edaf-4993-a79c-66a3e973afb6",
"applied": "verified",
"checker": null,
"verdict": "accept",
"decidedBy": "oracle",
"confidence": 1,
"ruleVersion": "oracle-1/inspection.final-building@1/r1"
},
"result": "pass",
"judgements": []
},
"executor": {
"id": "844df2fc-9526-4633-ac1f-779e47281496",
"kind": "trade_partner",
"name": "Sample Plumbing Co",
"license": null,
"credentials": [],
"supervisorOfRecord": null
},
"stepKind": {
"id": "inspection.final-building",
"version": 1
},
"startedAt": "2026-11-10T14:04:00.000Z",
"finishedAt": "2026-11-10T14:04:00.000Z",
"activeMinutes": null
}
],
"assets": [],
"schema": "4s.work-record/v1",
"totals": {
"open": 0,
"steps": 2,
"failed": 0,
"passed": 2,
"payReleased": 2,
"passedFirstTime": 2
},
"changes": [],
"permits": [],
"workSpec": {
"label": "Leak under the kitchen sink",
"family": "repair.leak",
"version": "settlement:fix@task.leak-repair,inspect@inspection.final-building",
"ontology": "f18580d1380ea9cf",
"configCode": null,
"rateRelease": null
},
"integrity": {
"trigger": "step_verified",
"issuedAt": "2026-11-10T14:04:00.000Z",
"recordId": "d54a2681-c1bf-4cb8-a793-990243ebf015",
"sequence": 4,
"signature": {
"alg": "ed25519",
"keyId": "4s-wr-5f088511120bf1e4",
"value": "TsispkZ69AePced3n1cbhnLGJ83tApCsLiQdiMNheS1K81hKERJWB1pfRQkqAMjaO3U_VnXpriaiHwkNdW6FDg"
},
"contentHash": "sha256:c726a069efb8a7b0395b98f74600fed2cabd7506f6832f82e506f7719c2e28ed"
},
"materials": []
}
}Add an endpoint in the dashboard (its signing secret is shown once) and check each delivery's signature before you trust it. The webhook catalogue lists every event.
import { createHmac, timingSafeEqual } from "node:crypto";
// header: the 4s-signature request header. body: the raw request body, as received.
export function verify4s(secret: string, body: string, header: string, toleranceSec = 300): boolean {
const parts = header.split(",").map((p) => p.split("=") as [string, string]);
const t = Number(parts.find(([k]) => k === "t")?.[1]);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest();
// During a secret rotation there are two v1 values: either one is enough.
return parts.some(([k, v]) => k === "v1" && v.length === 64 && timingSafeEqual(Buffer.from(v, "hex"), expected));
}