API reference · generated from the routes
/api/v1, amounts in integer cents, errors as { error: { code, message } }.Check a work record you hold
Public. Send the record as received: whether its hash and our signature check out, whether we issued it, and whether a newer snapshot of the job exists.
No parameters.
curl -X POST "https://www.build4seasons.com/api/v1/work-records/verify" \
-H "content-type: application/json" \
--data-binary @work-record.jsonThe answer200
{
"valid": true,
"schemaOk": true,
"hashOk": true,
"signatureOk": true,
"contentHash": "sha256:c726a069efb8a7b0395b98f74600fed2cabd7506f6832f82e506f7719c2e28ed",
"keyId": "4s-wr-5f088511120bf1e4",
"problems": [
"Signed with the development key: fine for testing, never valid in production"
],
"key": {
"known": true,
"dev": true,
"current": true
},
"onFile": null
}Your webhook endpoints
No parameters.
curl "https://www.build4seasons.com/api/v1/webhooks" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"endpoints": [
{
"id": "90d930d5-d484-48ea-ad4e-2e83a2411fdd",
"url": "https://hooks.example.com/4s/settlement",
"events": [
"settlement.step_verified",
"settlement.release_sent"
],
"active": true,
"createdAt": "2026-11-10T14:21:00.000Z"
}
]
}Add an endpoint; its signing secret is returned once
Idempotency-KeystringHeader
Honored when sent: a retry with the same key and body gets the first answer back.
urlstringBodyrequired
eventsstring[]Bodyrequired
curl -X POST "https://www.build4seasons.com/api/v1/webhooks" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: hook-settlement-1" \
-H "content-type: application/json" \
-d '{"url":"https://hooks.example.com/4s/settlement","events":["settlement.step_verified","settlement.release_sent"]}'The answer201
{
"endpoint": {
"id": "90d930d5-d484-48ea-ad4e-2e83a2411fdd",
"url": "https://hooks.example.com/4s/settlement",
"events": [
"settlement.step_verified",
"settlement.release_sent"
],
"secret": "whsec_example_only_never_real_00000000"
}
}Remove an endpoint
idstringPathrequired
The endpoint's id
curl -X DELETE "https://www.build4seasons.com/api/v1/webhooks/90d930d5-d484-48ea-ad4e-2e83a2411fdd" \
-H "authorization: Bearer $FOURS_KEY"The answer204
(no body)A new signing secret; the old one keeps signing for graceHours
idstringPathrequired
The endpoint's id
Idempotency-KeystringHeader
Honored when sent: a retry with the same key and body gets the first answer back.
graceHoursintegerBody
curl -X POST "https://www.build4seasons.com/api/v1/webhooks/90d930d5-d484-48ea-ad4e-2e83a2411fdd/rotate-secret" \
-H "authorization: Bearer $FOURS_KEY" \
-H "content-type: application/json" \
-d '{"graceHours":24}'The answer200
{
"endpoint": {
"id": "90d930d5-d484-48ea-ad4e-2e83a2411fdd",
"url": "https://hooks.example.com/4s/settlement",
"secret": "whsec_example_only_never_real_00000000",
"previousSecretExpiresAt": "2026-11-10T14:34:00.000Z"
}
}Deliveries to your endpoints: status, attempts, latency
endpointstringQuery
Endpoint id
status"pending" | "retrying" | "succeeded" | "failed" | "cancelled"Query
Delivery status
limitstringQuery
1 to 200
curl "https://www.build4seasons.com/api/v1/webhooks/deliveries?endpoint=90d930d5-d484-48ea-ad4e-2e83a2411fdd&limit=20" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"deliveries": [
{
"id": "a443d993-8ce3-48e5-a890-65c0172ce0f9",
"endpointId": "90d930d5-d484-48ea-ad4e-2e83a2411fdd",
"url": "https://hooks.example.com/4s/settlement",
"eventId": "evt_sr_ca48a404c8704a359411_sent",
"type": "settlement.release_sent",
"livemode": false,
"status": "pending",
"attempts": 0,
"lastStatusCode": null,
"lastLatencyMs": null,
"lastError": null,
"nextAttemptAt": null,
"replayOf": null,
"attemptLog": [],
"createdAt": "2026-11-10T14:28:00.000Z",
"deliveredAt": null
},
{
"id": "3ba4c860-62bb-47a0-ad5f-15356b173ed4",
"endpointId": "90d930d5-d484-48ea-ad4e-2e83a2411fdd",
"url": "https://hooks.example.com/4s/settlement",
"eventId": "evt_ss_94ca8548cd54492990b9_r1_verified",
"type": "settlement.step_verified",
"livemode": false,
"status": "pending",
"attempts": 0,
"lastStatusCode": null,
"lastLatencyMs": null,
"lastError": null,
"nextAttemptAt": null,
"replayOf": null,
"attemptLog": [],
"createdAt": "2026-11-10T14:26:00.000Z",
"deliveredAt": null
},
{
"id": "413918b2-9e1c-44cb-a989-1c80c38b9b1c",
"endpointId": "90d930d5-d484-48ea-ad4e-2e83a2411fdd",
"url": "https://hooks.example.com/4s/settlement",
"eventId": "evt_sr_e23b2512011c499dbe3f_sent",
"type": "settlement.release_sent",
"livemode": false,
"status": "pending",
"attempts": 0,
"lastStatusCode": null,
"lastLatencyMs": null,
"lastError": null,
"nextAttemptAt": null,
"replayOf": null,
"attemptLog": [],
"createdAt": "2026-11-10T14:25:00.000Z",
"deliveredAt": null
}
]
}One delivery with its body and every attempt
idstringPathrequired
The delivery's id
curl "https://www.build4seasons.com/api/v1/webhooks/deliveries/a443d993-8ce3-48e5-a890-65c0172ce0f9" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"delivery": {
"id": "a443d993-8ce3-48e5-a890-65c0172ce0f9",
"endpointId": "90d930d5-d484-48ea-ad4e-2e83a2411fdd",
"url": "https://hooks.example.com/4s/settlement",
"eventId": "evt_sr_ca48a404c8704a359411_sent",
"type": "settlement.release_sent",
"livemode": false,
"status": "pending",
"attempts": 0,
"lastStatusCode": null,
"lastLatencyMs": null,
"lastError": null,
"nextAttemptAt": null,
"replayOf": null,
"attemptLog": [],
"createdAt": "2026-11-10T14:28:00.000Z",
"deliveredAt": null,
"body": {
"id": "evt_sr_ca48a404c8704a359411_sent",
"data": {
"release": {
"id": "7ed67060-40f5-4b06-af81-b8ca6125f3ab",
"kind": "step",
"rail": "stripe",
"jobId": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"drawId": null,
"object": "settlement_release",
"sentAt": "2026-11-10T14:04:00.000Z",
"status": "sent",
"stepId": "46096d88-9562-400c-a506-21e937630643",
"feeCents": 75,
"livemode": false,
"createdAt": "2026-11-10T14:04:00.000Z",
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"heldReason": null,
"amountCents": 7500
}
},
"type": "settlement.release_sent",
"created": "2026-11-10T14:27:00.000Z",
"livemode": false
}
}
}Send the event again (same event id)
idstringPathrequired
The delivery's id
Idempotency-KeystringHeader
Honored when sent: a retry with the same key and body gets the first answer back.
curl -X POST "https://www.build4seasons.com/api/v1/webhooks/deliveries/a443d993-8ce3-48e5-a890-65c0172ce0f9/replay" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: replay-1"The answer201
{
"delivery": {
"id": "3859a77d-2002-41d4-a875-96aeb39e17a8",
"endpointId": "90d930d5-d484-48ea-ad4e-2e83a2411fdd",
"url": null,
"eventId": "evt_sr_ca48a404c8704a359411_sent",
"type": "settlement.release_sent",
"livemode": false,
"status": "pending",
"attempts": 0,
"lastStatusCode": null,
"lastLatencyMs": null,
"lastError": null,
"nextAttemptAt": null,
"replayOf": "a443d993-8ce3-48e5-a890-65c0172ce0f9",
"attemptLog": [],
"createdAt": "2026-11-10T14:33:00.000Z",
"deliveredAt": null
}
}Your settlement account: brand, fee on settled volume, whether live money moves, balance
Your tenant: name, brand, the fee on settled volume (basis points), the most one step may pay, whether live money moves yet, and your funded balance (cents).
No parameters.
curl "https://www.build4seasons.com/api/v1/settlement" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"object": "settlement_tenant",
"livemode": false,
"id": "093c39bb-e14c-4e66-a89d-7fd6dfa53c7b",
"name": "Sample Warranty Co",
"kind": "warranty",
"brand": {
"name": "Sample Warranty Co",
"color": null,
"logoUrl": null
},
"feeBps": 100,
"maxStepPayoutCents": 2500000,
"drawsEnabled": false,
"moneyMoves": true,
"balanceCents": null
}Your executors and whether each one's pay account is ready
Your executors: your own contractors and any 4 Seasons network pros you were given, with whether each one's pay account is ready on each rail. Newest first, a page at a time.
limitstringQuery
1 to 100
startingAfterstringQuery
nextCursor from the page before; the answer has hasMore and nextCursor
curl "https://www.build4seasons.com/api/v1/settlement/executors?limit=25" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"object": "list",
"livemode": false,
"data": [
{
"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"
}
],
"hasMore": false,
"nextCursor": null
}Add one of your contractors
Add one of your contractors 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.
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
externalRefstringBodyrequired
Your own id for this contractor
namestringBodyrequired
emailstringBody
payoutRail"whop" | "stripe"Body
Stripe Connect is the only rail; whop is retired and ignored for new pay
machineobjectBody
Set when the executor is a machine. Its proof comes as telemetry, which is always labelled machine proof and a person decides on it
machine.makerstringBody
Who made the machine
machine.modelstringBody
machine.serialstringBody
The maker's serial number for this unit
machine.ownerAccountstringBody
Your id for the account that owns the machine. Its pay goes to this executor's 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"}'The answer201
{
"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"
}Where your contractor opens their pay account on our rails
The hosted page where your contractor opens their pay account on our rails (Stripe Connect by default, or Whop): identity, bank and tax details. Pay goes there once the rail verifies them; you get settlement.executor_verified.
idstringPathrequired
The executor's id
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
rail"stripe" | "whop"Body
returnUrlstringBodyrequired
refreshUrlstringBodyrequired
curl -X POST "https://www.build4seasons.com/api/v1/settlement/executors/844df2fc-9526-4633-ac1f-779e47281496/onboarding" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: executor-tech-77-onboard" \
-H "content-type: application/json" \
-d '{"rail":"stripe","returnUrl":"https://app.example.com/pay/done","refreshUrl":"https://app.example.com/pay/again"}'The answer200
{
"object": "onboarding_link",
"livemode": false,
"rail": "stripe",
"url": "https://app.example.com/pay/done?sandbox_onboarding=844df2fc-9526-4633-ac1f-779e47281496",
"executor": {
"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"
}
}Your settlement jobs, newest first
Your jobs, newest first, a page at a time.
status"open" | "in_progress" | "completed" | "cancelled"Query
Only this status
referencestringQuery
Your reference
limitstringQuery
1 to 100
startingAfterstringQuery
nextCursor from the page before; the answer has hasMore and nextCursor
curl "https://www.build4seasons.com/api/v1/settlement/jobs?status=completed&limit=10" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"object": "list",
"livemode": false,
"data": [
{
"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"
}
],
"hasMore": false,
"nextCursor": null
}Create a job from a Work Spec
A job from a Work Spec: the site, the property owner (named on lien waivers), your reference, and its steps, each with a key, a name, a step kind from the work ontology (the standard the Verification Oracle judges it on; unknown kinds use the generic standard) and the executor's pay for it in cents. Optionally one executor for every step. With a loan (where draws are switched on): the loan number, the construction budget, the contractor paid and a draw schedule whose draws add up to the budget to the cent; the job's money is then released draw by draw on your conditions.
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
titlestringBodyrequired
referencestringBodyrequired
siteobjectBodyrequired
site.addressstringBodyrequired
site.unitstringBody
site.citystringBody
site.countystringBody
site.statestringBodyrequired
site.zipstringBodyrequired
ownerobjectBodyrequired
owner.namestringBodyrequired
workSpecobjectBodyrequired
workSpec.familystringBody
workSpec.stepsobject[]Bodyrequired
workSpec.steps[].keystringBodyrequired
workSpec.steps[].namestringBodyrequired
workSpec.steps[].kindstringBody
workSpec.steps[].tradestringBody
workSpec.steps[].unitsnumberBody
workSpec.steps[].payoutCentsintegerBodyrequired
executoruuidBody
loanobjectBody
loan.referencestringBody
loan.borrowerobjectBody
loan.borrower.namestringBody
loan.budgetCentsintegerBody
loan.payeeobjectBody
loan.payee.executoruuidBody
loan.payee.mode"contractor" | "joint_with_borrower"Body
loan.drawsobject[]Body
loan.draws[].keystringBody
loan.draws[].namestringBody
loan.draws[].milestonesstring[]Body
loan.draws[].amountCentsintegerBody
loan.draws[].inspectionobjectBody
loan.draws[].inspection.stepstringBody
loan.draws[].inspection.namestringBody
loan.draws[].inspection.permitstringBody
loan.draws[].lenderSignoffbooleanBody
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}]}}'The answer201
{
"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
}A job: steps, proof plans, verdicts and releases
The job with each step's proof plan, status, the Oracle's latest verdict and what it waits on, and the step's release (amount, fee, rail, held reason).
idstringPathrequired
The job's id, its number (SJ-1001) or your reference
curl "https://www.build4seasons.com/api/v1/settlement/jobs/SJ-1001" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"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"
}Give steps to an executor
Give steps to one of your executors (all steps not yet verified when steps is left out). A verified step keeps the executor it was paid to.
idstringPathrequired
The job's id, its number (SJ-1001) or your reference
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
executoruuidBodyrequired
stepsstring[]Body
Step keys; all steps not yet verified when left out
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"}'The answer200
{
"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
}Proof for a step; pay is released only once it's verified
Proof that a step is done: photos (SHA-256 of each file, the shot from the step's proof plan, when and where taken), readings, an inspection result, parts. The Verification Oracle judges it on the step kind's standard; where it can't decide alone a person at 4 Seasons does. Only a verified step's pay is released, over our pay rails, from your funded balance. Returns the job.
idstringPathrequired
The job's id, its number (SJ-1001) or your reference
stepstringPathrequired
The step's key from your Work Spec
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
X-4S-Simulate"happy" | "fail_verification" | "review"Header
Test keys only. happy: the sandbox reviewer accepts. fail_verification: the first round is sent back. review: left for a person.
photosobject[]Body
photos[].shotstringBody
photos[].sha256stringBody
photos[].capturedAtdate-timeBody
photos[].latnumberBody
photos[].lngnumberBody
photos[].accuracyMnumberBody
measurementsobject[]Body
measurements[].idstringBody
measurements[].valuenumberBody
measurements[].unitstringBody
measurements[].atdate-timeBody
inspectionobjectBody
inspection.result"pass" | "fail"Body
inspection.inspectorstringBody
inspection.atdate-timeBody
inspection.correctionsstring[]Body
partsobject[]Body
parts[].serialstringBody
parts[].lotstringBody
parts[].modelstringBody
parts[].namestringBody
telemetryobject[]Body
telemetry[].schemastringBody
telemetry[].deviceKeyIdstringBody
The machine's key, registered like a capture device (POST /api/v1/capture/devices)
telemetry[].protection"hardware" | "browser" | "software"Body
telemetry[].machineobjectBody
telemetry[].machine.makerstringBody
telemetry[].machine.modelstringBody
telemetry[].machine.serialstringBody
telemetry[].jobstringBody
telemetry[].stepstringBody
telemetry[].measurementstringBody
The step kind's measurement this log is for, by id (the proof standard lists them)
telemetry[].unitstringBody
telemetry[].fromdate-timeBody
telemetry[].todate-timeBody
telemetry[].samplesintegerBody
telemetry[].minnumberBody
telemetry[].maxnumberBody
telemetry[].lastnumberBody
telemetry[].signaturestringBody
base64url raw ECDSA P-256 SHA-256 signature over telemetryPayload
startedAtdate-timeBody
finishedAtdate-timeBody
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":[]}}'The answer200
{
"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"
}The job's signed Verified Work Record
The job's Verified Work Record, signed: each step's proof hashes, the Oracle's verdict and rule version, who did it, and whether its pay was released and paid. Check it with verify_work_record or POST /api/v1/work-records/verify.
idstringPathrequired
The job's id, its number (SJ-1001) or your reference
curl "https://www.build4seasons.com/api/v1/settlement/jobs/CLAIM-881/record" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"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": []
}
}The lien waiver for each release on the job
The Georgia statutory lien waiver for each release on the job (interim, and final on an executor's last step), with its text and SHA-256, whether it's signed and whether the pay reached them.
idstringPathrequired
The job's id, its number (SJ-1001) or your reference
curl "https://www.build4seasons.com/api/v1/settlement/jobs/CLAIM-881/lien-waivers" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"object": "list",
"livemode": false,
"data": [
{
"id": "5f2c5683-e2d3-46c9-ad77-0e4f85fcd41d",
"object": "lien_waiver",
"livemode": false,
"releaseId": "1a6a6ac0-63b3-4d90-a685-c5d6de69bba7",
"stepId": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"kind": "interim",
"formVersion": "GA-44-14-366-2021.1",
"amountCents": 20000,
"paid": true,
"signed": false,
"signedBy": null,
"signedOn": null,
"text": "WAIVER AND RELEASE OF LIEN AND PAYMENT BOND RIGHTS UPON INTERIM PAYMENT\n\nSTATE OF GEORGIA\nCOUNTY OF FULTON\n\nTHE UNDERSIGNED MECHANIC AND/OR MATERIALMAN HAS BEEN EMPLOYED BY SAMPLE WARRANTY CO LLC (NAME OF CONTRACTOR) TO FURNISH LABOR: FIND …",
"sha256": "d5240d44ece74834144eba473863cc0743304038abd6242cf15b43d81be1e20d"
},
{
"id": "2ad527d8-5a39-4454-a8e4-da451811b9ee",
"object": "lien_waiver",
"livemode": false,
"releaseId": "7ed67060-40f5-4b06-af81-b8ca6125f3ab",
"stepId": "46096d88-9562-400c-a506-21e937630643",
"kind": "final",
"formVersion": "GA-44-14-366-2021.1",
"amountCents": 7500,
"paid": true,
"signed": false,
"signedBy": null,
"signedOn": null,
"text": "WAIVER AND RELEASE OF LIEN AND PAYMENT BOND RIGHTS UPON FINAL PAYMENT\n\nSTATE OF GEORGIA\nCOUNTY OF FULTON\n\nTHE UNDERSIGNED MECHANIC AND/OR MATERIALMAN HAS BEEN EMPLOYED BY SAMPLE WARRANTY CO LLC (NAME OF CONTRACTOR) TO FURNISH LABOR: FINAL I…",
"sha256": "0523924437b04c73569f9c61e21f35573ecd8c6eaccdfad90a58a477494ed10b"
}
]
}The executor's electronic signature on a waiver
Record the executor's electronic signature on a waiver: the name they typed in your app, and their title.
idstringPathrequired
The waiver's id
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
namestringBodyrequired
The name the executor typed to sign
titlestringBody
curl -X POST "https://www.build4seasons.com/api/v1/settlement/lien-waivers/5f2c5683-e2d3-46c9-ad77-0e4f85fcd41d/sign" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: waiver-sign-1" \
-H "content-type: application/json" \
-d '{"name":"Sam Sample","title":"Owner"}'The answer200
{
"id": "5f2c5683-e2d3-46c9-ad77-0e4f85fcd41d",
"object": "lien_waiver",
"livemode": false,
"releaseId": "1a6a6ac0-63b3-4d90-a685-c5d6de69bba7",
"stepId": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"kind": "interim",
"formVersion": "GA-44-14-366-2021.1",
"amountCents": 20000,
"paid": true,
"signed": true,
"signedBy": "Sam Sample",
"signedOn": "2026-11-10",
"text": "WAIVER AND RELEASE OF LIEN AND PAYMENT BOND RIGHTS UPON INTERIM PAYMENT\n\nSTATE OF GEORGIA\nCOUNTY OF FULTON\n\nTHE UNDERSIGNED MECHANIC AND/OR MATERIALMAN HAS BEEN EMPLOYED BY SAMPLE WARRANTY CO LLC (NAME OF CONTRACTOR) TO FURNISH LABOR: FIND …",
"sha256": "b7fbe2c362831243e7834167b41891c77c1d91b68957900d88156f31a60ed939"
}Pay released on verified steps, with the fee and the rail
Pay released on verified steps: amount, fee, status (held with the reason, sending, sent), the rail it went over.
status"held" | "sending" | "sent"Query
Only this status
jobstringQuery
One job
limitstringQuery
1 to 100
startingAfterstringQuery
nextCursor from the page before; the answer has hasMore and nextCursor
curl "https://www.build4seasons.com/api/v1/settlement/releases?job=CLAIM-881&limit=50" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"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
}A month's settlement statement (YYYY-MM)
One month: opening balance, funding received, releases and pay settled by rail, the fee on settled volume, and the closing balance.
monthstringPathrequired
YYYY-MM
curl "https://www.build4seasons.com/api/v1/settlement/statements/2026-11" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"object": "settlement_statement",
"livemode": false,
"tenant": {
"id": "093c39bb-e14c-4e66-a89d-7fd6dfa53c7b",
"name": "Sample Warranty Co"
},
"month": "2026-11",
"openingCents": 0,
"fundedCents": 0,
"releases": 2,
"settledCents": 27500,
"feeCents": 275,
"byRail": [
{
"rail": "stripe",
"releases": 2,
"cents": 27500
}
],
"closingCents": -27775
}Open committed hours by trade and week at a ZIP
Hours you could reserve at a ZIP, by trade and week, counted from what pros committed for the month on days their calendar is free, from pros qualified for the work. Each week is read on its own. A market or trade with nothing committed answers zeros and says so. A test key answers from simulated supply, marked simulated.
zipstringQuery
Where the work is
trade"general" | "tile" | "plumbing" | "electrical" | "drywall" | "flooring" | "carpentry"Query
One trade
fromstringQuery
First day, YYYY-MM-DD
weeksstringQuery
Weeks to show
minLevelstringQuery
The level the work needs
credentialsstringQuery
Comma-separated: gl_insurance, workers_comp, epa_rrp, plumbing_license, electrical_license
stepKindsstringQuery
Comma-separated step kinds
minTier"new" | "proven" | "trusted" | "top"Query
Lowest tier
X-4S-Simulate"happy" | "pro_withdraws" | "no_refill" | "no_supply"Header
Test keys only. happy: The default. Simulated pros hold the hours and confirm. pro_withdraws: One simulated pro pulls out after confirming. A simulated standby pro takes the hours, and you get settlement.capacity_refilled. no_refill: One simulated pro pulls out and the simulated bench is empty. You get settlement.capacity_short. no_supply: The area has no committed hours. Availability is zero and a reservation is refused.
curl "https://www.build4seasons.com/api/v1/settlement/capacity?zip=30306&trade=plumbing&from=2026-11-16&weeks=2" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"object": "capacity_availability",
"livemode": false,
"simulated": true,
"enabled": true,
"zip": "30306",
"market": {
"id": "atl",
"name": "Atlanta"
},
"from": "2026-11-16",
"to": "2026-11-29",
"hoursPerPart": 4,
"trades": [
{
"trade": "plumbing",
"label": "Plumbing",
"hours": 240,
"pros": 3,
"weeks": [
{
"week": "2026-11-16",
"hours": 120,
"am": 15,
"pm": 15,
"pros": 3
},
{
"week": "2026-11-23",
"hours": 120,
"am": 15,
"pm": 15,
"pros": 3
}
]
}
],
"note": null
}Your reservations, newest first
Your reservations, newest first, a page at a time, each with its hours, pros, lapse time and history.
status"held" | "converted" | "released" | "failed"Query
Only this status
limitstringQuery
1 to 100
startingAfterstringQuery
nextCursor from the page before; the answer has hasMore and nextCursor
curl "https://www.build4seasons.com/api/v1/settlement/capacity/reservations?limit=2" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"object": "list",
"livemode": false,
"data": [
{
"id": "537d7db4-324a-4466-a421-2d77b5acd74a",
"object": "capacity_reservation",
"livemode": false,
"simulated": true,
"status": "converted",
"reference": "CLAIM-881-HOURS",
"note": "Water heater swaps",
"trade": "plumbing",
"zip": "30306",
"marketId": "atl",
"window": {
"from": "2026-11-16",
"to": "2026-11-20"
},
"hoursAsked": 16,
"hoursHeld": 16,
"firstStart": "2026-11-10T14:35:00.000Z",
"lapseAt": null,
"need": {
"credentials": [
"plumbing_license"
]
},
"pros": [
{
"pro": "pro_1",
"simulated": true,
"hours": 16,
"confirmed": true,
"confirmBy": null,
"fromStandby": false,
"executorId": "060fb7da-8808-425d-a4dc-bc3bcd366a1a"
}
],
"slots": [
{
"day": "2026-11-16",
"part": "am",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
},
{
"day": "2026-11-16",
"part": "pm",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
},
{
"day": "2026-11-17",
"part": "am",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
}
],
"job": {
"kind": "settlement_job",
"id": "afa4bc72-c411-49bf-a7e7-35a6490f3696",
"at": "2026-11-10T14:04:00.000Z"
},
"release": null,
"shortfall": {
"hours": 0,
"creditCents": 0
},
"history": [
{
"type": "reserved",
"at": "2026-11-10T14:04:00.000Z",
"message": "16 hours of plumbing reserved with 1 pro from Nov 16 to Nov 17. Attach a job by Nov 13, 8:00 AM EST or the hours go back."
},
{
"type": "converted",
"at": "2026-11-10T14:04:00.000Z",
"message": "Attached to job SJ-1002. The reserved pro is now among your executors."
}
],
"createdAt": "2026-11-10T14:04:00.000Z"
},
{
"id": "c6579ccc-9f7e-41f2-a20e-b489f6ac4da9",
"object": "capacity_reservation",
"livemode": false,
"simulated": true,
"status": "released",
"reference": "CLAIM-884-HOURS",
"note": "Water heater swaps",
"trade": "plumbing",
"zip": "30306",
"marketId": "atl",
"window": {
"from": "2026-11-16",
"to": "2026-11-20"
},
"hoursAsked": 8,
"hoursHeld": 0,
"firstStart": null,
"lapseAt": null,
"need": {
"credentials": [
"plumbing_license"
]
},
"pros": [],
"slots": [
{
"day": "2026-11-16",
"part": "am",
"pro": "pro_2",
"status": "failed",
"refill": false,
"failReason": "pro_withdrew"
},
{
"day": "2026-11-16",
"part": "am",
"pro": "pro_1",
"status": "released",
"refill": true,
"failReason": null
},
{
"day": "2026-11-16",
"part": "pm",
"pro": "pro_2",
"status": "failed",
"refill": false,
"failReason": "pro_withdrew"
}
],
"job": null,
"release": {
"reason": "released",
"late": false,
"feeCents": 0,
"at": "2026-11-10T14:04:00.000Z"
},
"shortfall": {
"hours": 8,
"creditCents": 0
},
"history": [
{
"type": "reserved",
"at": "2026-11-10T14:04:00.000Z",
"message": "8 hours of plumbing reserved with 1 pro from Nov 16 to Nov 16. Attach a job by Nov 13, 8:00 AM EST or the hours go back."
},
{
"type": "refilled",
"at": "2026-11-10T14:04:00.000Z",
"message": "A pro pulled out of 8 hours reserved on Nov 16. Another qualified pro from the standby bench now holds those hours."
},
{
"type": "released",
"at": "2026-11-10T14:04:00.000Z",
"message": "You released 8 hours. They are back on the pros' open calendars."
}
],
"createdAt": "2026-11-10T14:04:00.000Z"
}
],
"hasMore": true,
"nextCursor": "cmwatgtc0_3bd64d2ffe4241c996f1c2417229d219"
}Reserve committed hours for a trade in a window
Reserve hours for a trade at a ZIP in a window, in half days of 4 hours. Every hour is held on a pro who committed it, whose calendar is free and who meets what you asked for. All of the hours or none. The reservation lapses at lapseAt unless you attach a job.
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
X-4S-Simulate"happy" | "pro_withdraws" | "no_refill" | "no_supply"Header
Test keys only. happy: The default. Simulated pros hold the hours and confirm. pro_withdraws: One simulated pro pulls out after confirming. A simulated standby pro takes the hours, and you get settlement.capacity_refilled. no_refill: One simulated pro pulls out and the simulated bench is empty. You get settlement.capacity_short. no_supply: The area has no committed hours. Availability is zero and a reservation is refused.
trade"general" | "tile" | "plumbing" | "electrical" | "drywall" | "flooring" | "carpentry"Bodyrequired
zipstringBodyrequired
Where the work is. It picks the market
fromstringBodyrequired
First day of the window
tostringBodyrequired
Last day of the window
hoursintegerBodyrequired
Hours to reserve, in half days of 4
parts"am" | "pm"[]Body
Only mornings (am, 8 to 12) or afternoons (pm, 12 to 4). Both when left out
referencestringBodyrequired
Your own id for this reservation
notestringBody
What the hours are for, in your words. Only you and 4 Seasons read it
minLevelintegerBody
The level the work needs. A pro's level is their highest certified level
stepKindsstring[]Body
Step kinds from the work ontology the pro must be qualified for, such as task.leak-repair. A licensed kind also asks for the license
credentials"gl_insurance" | "workers_comp" | "epa_rrp" | "plumbing_license" | "electrical_license"[]Body
Credentials the pro must hold, verified and current
minTier"new" | "proven" | "trusted" | "top"Body
The lowest reputation tier you accept
curl -X POST "https://www.build4seasons.com/api/v1/settlement/capacity/reservations" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: reserve-881" \
-H "content-type: application/json" \
-d '{"trade":"plumbing","zip":"30306","from":"2026-11-16","to":"2026-11-20","hours":16,"reference":"CLAIM-881-HOURS","note":"Water heater swaps","credentials":["plumbing_license"]}'The answer201
{
"id": "537d7db4-324a-4466-a421-2d77b5acd74a",
"object": "capacity_reservation",
"livemode": false,
"simulated": true,
"status": "held",
"reference": "CLAIM-881-HOURS",
"note": "Water heater swaps",
"trade": "plumbing",
"zip": "30306",
"marketId": "atl",
"window": {
"from": "2026-11-16",
"to": "2026-11-20"
},
"hoursAsked": 16,
"hoursHeld": 16,
"firstStart": "2026-11-10T14:35:00.000Z",
"lapseAt": "2026-11-10T14:20:00.000Z",
"need": {
"credentials": [
"plumbing_license"
]
},
"pros": [
{
"pro": "pro_1",
"simulated": true,
"hours": 16,
"confirmed": true,
"confirmBy": null,
"fromStandby": false,
"executorId": null
}
],
"slots": [
{
"day": "2026-11-16",
"part": "am",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
},
{
"day": "2026-11-16",
"part": "pm",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
},
{
"day": "2026-11-17",
"part": "am",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
}
],
"job": null,
"release": null,
"shortfall": {
"hours": 0,
"creditCents": 0
},
"history": [
{
"type": "reserved",
"at": "2026-11-10T14:04:00.000Z",
"message": "16 hours of plumbing reserved with 1 pro from Nov 16 to Nov 17. Attach a job by Nov 13, 8:00 AM EST or the hours go back."
}
],
"createdAt": "2026-11-10T14:04:00.000Z"
}A reservation: its hours, pros, lapse time and history
A reservation: the hours held, each pro's hours and whether they confirmed, the lapse time, the job it became, and what happened to it in order.
idstringPathrequired
The reservation's id, or your reference
curl "https://www.build4seasons.com/api/v1/settlement/capacity/reservations/537d7db4-324a-4466-a421-2d77b5acd74a" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"id": "537d7db4-324a-4466-a421-2d77b5acd74a",
"object": "capacity_reservation",
"livemode": false,
"simulated": true,
"status": "held",
"reference": "CLAIM-881-HOURS",
"note": "Water heater swaps",
"trade": "plumbing",
"zip": "30306",
"marketId": "atl",
"window": {
"from": "2026-11-16",
"to": "2026-11-20"
},
"hoursAsked": 16,
"hoursHeld": 16,
"firstStart": "2026-11-10T14:35:00.000Z",
"lapseAt": "2026-11-10T14:20:00.000Z",
"need": {
"credentials": [
"plumbing_license"
]
},
"pros": [
{
"pro": "pro_1",
"simulated": true,
"hours": 16,
"confirmed": true,
"confirmBy": null,
"fromStandby": false,
"executorId": null
}
],
"slots": [
{
"day": "2026-11-16",
"part": "am",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
},
{
"day": "2026-11-16",
"part": "pm",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
},
{
"day": "2026-11-17",
"part": "am",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
}
],
"job": null,
"release": null,
"shortfall": {
"hours": 0,
"creditCents": 0
},
"history": [
{
"type": "reserved",
"at": "2026-11-10T14:04:00.000Z",
"message": "16 hours of plumbing reserved with 1 pro from Nov 16 to Nov 17. Attach a job by Nov 13, 8:00 AM EST or the hours go back."
}
],
"createdAt": "2026-11-10T14:04:00.000Z"
}Attach a settlement job to a reservation
Attach one of your settlement jobs before the lapse time. The reserved pros become your executors, and the one holding the most hours is given the job's steps that have nobody yet.
idstringPathrequired
The reservation's id, or your reference
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
settlementJobstringBodyrequired
The settlement job the hours are for: its id, its number such as SJ-1001, or your reference
curl -X POST "https://www.build4seasons.com/api/v1/settlement/capacity/reservations/537d7db4-324a-4466-a421-2d77b5acd74a/convert" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: reserve-881-convert" \
-H "content-type: application/json" \
-d '{"settlementJob":"CLAIM-882"}'The answer200
{
"id": "537d7db4-324a-4466-a421-2d77b5acd74a",
"object": "capacity_reservation",
"livemode": false,
"simulated": true,
"status": "converted",
"reference": "CLAIM-881-HOURS",
"note": "Water heater swaps",
"trade": "plumbing",
"zip": "30306",
"marketId": "atl",
"window": {
"from": "2026-11-16",
"to": "2026-11-20"
},
"hoursAsked": 16,
"hoursHeld": 16,
"firstStart": "2026-11-10T14:35:00.000Z",
"lapseAt": null,
"need": {
"credentials": [
"plumbing_license"
]
},
"pros": [
{
"pro": "pro_1",
"simulated": true,
"hours": 16,
"confirmed": true,
"confirmBy": null,
"fromStandby": false,
"executorId": "060fb7da-8808-425d-a4dc-bc3bcd366a1a"
}
],
"slots": [
{
"day": "2026-11-16",
"part": "am",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
},
{
"day": "2026-11-16",
"part": "pm",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
},
{
"day": "2026-11-17",
"part": "am",
"pro": "pro_1",
"status": "held",
"refill": false,
"failReason": null
}
],
"job": {
"kind": "settlement_job",
"id": "afa4bc72-c411-49bf-a7e7-35a6490f3696",
"at": "2026-11-10T14:04:00.000Z"
},
"release": null,
"shortfall": {
"hours": 0,
"creditCents": 0
},
"history": [
{
"type": "reserved",
"at": "2026-11-10T14:04:00.000Z",
"message": "16 hours of plumbing reserved with 1 pro from Nov 16 to Nov 17. Attach a job by Nov 13, 8:00 AM EST or the hours go back."
},
{
"type": "converted",
"at": "2026-11-10T14:04:00.000Z",
"message": "Attached to job SJ-1002. The reserved pro is now among your executors."
}
],
"createdAt": "2026-11-10T14:04:00.000Z"
}Let reserved hours go before they start
Let reserved hours go before they start. They go back on the pros' open calendars. A release close to the work is recorded as late.
idstringPathrequired
The reservation's id, or your reference
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
curl -X POST "https://www.build4seasons.com/api/v1/settlement/capacity/reservations/c6579ccc-9f7e-41f2-a20e-b489f6ac4da9/release" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: reserve-884-release"The answer200
{
"id": "c6579ccc-9f7e-41f2-a20e-b489f6ac4da9",
"object": "capacity_reservation",
"livemode": false,
"simulated": true,
"status": "released",
"reference": "CLAIM-884-HOURS",
"note": "Water heater swaps",
"trade": "plumbing",
"zip": "30306",
"marketId": "atl",
"window": {
"from": "2026-11-16",
"to": "2026-11-20"
},
"hoursAsked": 8,
"hoursHeld": 0,
"firstStart": null,
"lapseAt": null,
"need": {
"credentials": [
"plumbing_license"
]
},
"pros": [],
"slots": [
{
"day": "2026-11-16",
"part": "am",
"pro": "pro_2",
"status": "failed",
"refill": false,
"failReason": "pro_withdrew"
},
{
"day": "2026-11-16",
"part": "am",
"pro": "pro_1",
"status": "released",
"refill": true,
"failReason": null
},
{
"day": "2026-11-16",
"part": "pm",
"pro": "pro_2",
"status": "failed",
"refill": false,
"failReason": "pro_withdrew"
}
],
"job": null,
"release": {
"reason": "released",
"late": false,
"feeCents": 0,
"at": "2026-11-10T14:04:00.000Z"
},
"shortfall": {
"hours": 8,
"creditCents": 0
},
"history": [
{
"type": "reserved",
"at": "2026-11-10T14:04:00.000Z",
"message": "8 hours of plumbing reserved with 1 pro from Nov 16 to Nov 16. Attach a job by Nov 13, 8:00 AM EST or the hours go back."
},
{
"type": "refilled",
"at": "2026-11-10T14:04:00.000Z",
"message": "A pro pulled out of 8 hours reserved on Nov 16. Another qualified pro from the standby bench now holds those hours."
},
{
"type": "released",
"at": "2026-11-10T14:04:00.000Z",
"message": "You released 8 hours. They are back on the pros' open calendars."
}
],
"createdAt": "2026-11-10T14:04:00.000Z"
}Your bulk requests, newest first, with fill rates and waitlist places
Your bulk requests, newest first, each with its weeks, fill rates and place in the waitlist.
limitstringQuery
1 to 100
curl "https://www.build4seasons.com/api/v1/settlement/capacity/bulk?limit=2" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"object": "list",
"data": [
{
"id": "5549e53f-3d4a-44f1-a251-b40bc46c9cde",
"object": "capacity_bulk_request",
"livemode": false,
"simulated": true,
"reference": "PORTFOLIO-Q1",
"status": "open",
"trade": "plumbing",
"zips": [
"30306",
"30307"
],
"marketId": "atl",
"allowPartial": true,
"waitlist": true,
"need": {},
"note": null,
"hoursPerWeek": 8,
"hoursAsked": 16,
"hoursHeld": 16,
"hoursShort": 0,
"fillRate": 1,
"weeks": [
{
"week": "2026-11-16",
"hoursAsked": 8,
"hoursHeld": 8,
"hoursLetGo": 0,
"hoursShort": 0,
"fillRate": 1,
"reservations": [
"f52e22a0-a3c2-49d2-a42b-8369fc6b74e8"
],
"waitlist": null
},
{
"week": "2026-11-23",
"hoursAsked": 8,
"hoursHeld": 8,
"hoursLetGo": 0,
"hoursShort": 0,
"fillRate": 1,
"reservations": [
"8d8694c5-4212-48d0-a007-0d75a4454f2f"
],
"waitlist": null
}
],
"priority": {
"rank": 0,
"fromSettings": 0,
"setByOps": false
},
"fees": {
"bulkCentsPerHour": 0,
"waitlistCentsPerHour": 0
},
"createdAt": "2026-11-10T14:04:00.000Z",
"cancelledAt": null
}
]
}Reserve one trade across ZIPs and weeks in one request, all or none unless partial fills are allowed
Reserve the same hours of one trade in each of a run of weeks, across a list of ZIPs in one market. Each week becomes its own reservation on pros who committed the hours. All of it or none unless allowPartial is true. With waitlist true as well, the hours still short wait in line and are held as pros commit more. The answer gives hours asked, held and the fill rate for each week, and your place in line.
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
X-4S-Simulate"happy" | "pro_withdraws" | "no_refill" | "no_supply"Header
Test keys only. happy: The default. Simulated pros hold the hours and confirm. pro_withdraws: One simulated pro pulls out after confirming. A simulated standby pro takes the hours, and you get settlement.capacity_refilled. no_refill: One simulated pro pulls out and the simulated bench is empty. You get settlement.capacity_short. no_supply: The area has no committed hours. Availability is zero and a reservation is refused.
trade"general" | "tile" | "plumbing" | "electrical" | "drywall" | "flooring" | "carpentry"Bodyrequired
zipsstring[]Bodyrequired
Where the work is. All of them must be in one market
firstWeekstringBodyrequired
Any day of the first week. Weeks run Monday to Sunday
weeksintegerBodyrequired
How many weeks in a row
hoursPerWeekintegerBodyrequired
Hours to reserve in each week, in half days of 4
allowPartialbooleanBody
Hold what is there when a week can't hold all of it. Left out or false: all of it or none
waitlistbooleanBody
Wait for the hours still short. Needs allowPartial. Filled only from hours pros commit later
parts"am" | "pm"[]Body
Only mornings (am) or afternoons (pm). Both when left out
referencestringBodyrequired
Your own id for this request. Each week's reservation is named after it
notestringBody
What the hours are for, in your words. Only you and 4 Seasons read it
minLevelintegerBody
The level the work needs. A pro's level is their highest certified level
stepKindsstring[]Body
Step kinds from the work ontology the pro must be qualified for, such as task.leak-repair. A licensed kind also asks for the license
credentials"gl_insurance" | "workers_comp" | "epa_rrp" | "plumbing_license" | "electrical_license"[]Body
Credentials the pro must hold, verified and current
minTier"new" | "proven" | "trusted" | "top"Body
The lowest reputation tier you accept
curl -X POST "https://www.build4seasons.com/api/v1/settlement/capacity/bulk" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: bulk-q1" \
-H "content-type: application/json" \
-d '{"trade":"plumbing","zips":["30306","30307"],"firstWeek":"2026-11-16","weeks":2,"hoursPerWeek":8,"allowPartial":true,"waitlist":true,"reference":"PORTFOLIO-Q1"}'The answer201
{
"id": "5549e53f-3d4a-44f1-a251-b40bc46c9cde",
"object": "capacity_bulk_request",
"livemode": false,
"simulated": true,
"reference": "PORTFOLIO-Q1",
"status": "open",
"trade": "plumbing",
"zips": [
"30306",
"30307"
],
"marketId": "atl",
"allowPartial": true,
"waitlist": true,
"need": {},
"note": null,
"hoursPerWeek": 8,
"hoursAsked": 16,
"hoursHeld": 16,
"hoursShort": 0,
"fillRate": 1,
"weeks": [
{
"week": "2026-11-16",
"hoursAsked": 8,
"hoursHeld": 8,
"hoursLetGo": 0,
"hoursShort": 0,
"fillRate": 1,
"reservations": [
"f52e22a0-a3c2-49d2-a42b-8369fc6b74e8"
],
"waitlist": null
},
{
"week": "2026-11-23",
"hoursAsked": 8,
"hoursHeld": 8,
"hoursLetGo": 0,
"hoursShort": 0,
"fillRate": 1,
"reservations": [
"8d8694c5-4212-48d0-a007-0d75a4454f2f"
],
"waitlist": null
}
],
"priority": {
"rank": 0,
"fromSettings": 0,
"setByOps": false
},
"fees": {
"bulkCentsPerHour": 0,
"waitlistCentsPerHour": 0
},
"createdAt": "2026-11-10T14:04:00.000Z",
"cancelledAt": null
}A bulk request: asked, held and short by week, and its place in the waitlist
A bulk request: hours asked, held and short in each week, the fill rate read from what is held right now, the reservations behind it, and its place in the waitlist.
idstringPathrequired
The bulk request's id, or your reference
curl "https://www.build4seasons.com/api/v1/settlement/capacity/bulk/5549e53f-3d4a-44f1-a251-b40bc46c9cde" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"id": "5549e53f-3d4a-44f1-a251-b40bc46c9cde",
"object": "capacity_bulk_request",
"livemode": false,
"simulated": true,
"reference": "PORTFOLIO-Q1",
"status": "open",
"trade": "plumbing",
"zips": [
"30306",
"30307"
],
"marketId": "atl",
"allowPartial": true,
"waitlist": true,
"need": {},
"note": null,
"hoursPerWeek": 8,
"hoursAsked": 16,
"hoursHeld": 16,
"hoursShort": 0,
"fillRate": 1,
"weeks": [
{
"week": "2026-11-16",
"hoursAsked": 8,
"hoursHeld": 8,
"hoursLetGo": 0,
"hoursShort": 0,
"fillRate": 1,
"reservations": [
"f52e22a0-a3c2-49d2-a42b-8369fc6b74e8"
],
"waitlist": null
},
{
"week": "2026-11-23",
"hoursAsked": 8,
"hoursHeld": 8,
"hoursLetGo": 0,
"hoursShort": 0,
"fillRate": 1,
"reservations": [
"8d8694c5-4212-48d0-a007-0d75a4454f2f"
],
"waitlist": null
}
],
"priority": {
"rank": 0,
"fromSettings": 0,
"setByOps": false
},
"fees": {
"bulkCentsPerHour": 0,
"waitlistCentsPerHour": 0
},
"createdAt": "2026-11-10T14:04:00.000Z",
"cancelledAt": null
}Leave the waitlist. Held hours stay until released
Stop waiting for the hours still short. The hours already held stay held; release each week's reservation to let them go.
idstringPathrequired
The bulk request's id, or your reference
Idempotency-KeystringHeaderrequired
8 to 100 letters, digits, - or _. A retry with the same key and body gets the first answer back.
curl -X POST "https://www.build4seasons.com/api/v1/settlement/capacity/bulk/5549e53f-3d4a-44f1-a251-b40bc46c9cde/cancel" \
-H "authorization: Bearer $FOURS_KEY" \
-H "idempotency-key: bulk-q1-cancel"The answer200
{
"id": "5549e53f-3d4a-44f1-a251-b40bc46c9cde",
"object": "capacity_bulk_request",
"livemode": false,
"simulated": true,
"reference": "PORTFOLIO-Q1",
"status": "cancelled",
"trade": "plumbing",
"zips": [
"30306",
"30307"
],
"marketId": "atl",
"allowPartial": true,
"waitlist": true,
"need": {},
"note": null,
"hoursPerWeek": 8,
"hoursAsked": 16,
"hoursHeld": 16,
"hoursShort": 0,
"fillRate": 1,
"weeks": [
{
"week": "2026-11-16",
"hoursAsked": 8,
"hoursHeld": 8,
"hoursLetGo": 0,
"hoursShort": 0,
"fillRate": 1,
"reservations": [
"f52e22a0-a3c2-49d2-a42b-8369fc6b74e8"
],
"waitlist": null
},
{
"week": "2026-11-23",
"hoursAsked": 8,
"hoursHeld": 8,
"hoursLetGo": 0,
"hoursShort": 0,
"fillRate": 1,
"reservations": [
"8d8694c5-4212-48d0-a007-0d75a4454f2f"
],
"waitlist": null
}
],
"priority": {
"rank": 0,
"fromSettings": 0,
"setByOps": false
},
"fees": {
"bulkCentsPerHour": 0,
"waitlistCentsPerHour": 0
},
"createdAt": "2026-11-10T14:04:00.000Z",
"cancelledAt": "2026-11-10T14:04:00.000Z"
}