Outcome API · test keys
Make a test key
Sign in to your account and open Keys. Make a test key for the Outcome API. It starts 4s_test_ and is shown once.
Quote the outcome
POST the work in plain words and the site. You get the Work Spec, the price, the questions still open and the weeks with hours to reserve. Nothing is held.
Confirm a week
POST a window, the answers you have, the site contact and acceptTerms true. The hours are reserved, the job is created and the money is held.
Follow it to the release
GET the outcome, or listen for outcome webhooks. Each step's proof is checked, and its payout is released once it is verified.
curl https://www.build4seasons.com/api/v1/outcomes \
-H "Authorization: Bearer $FOURS_TEST_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hall-bath-quote-1" \
-d '{
"outcome": "Replace the tub with a walk-in tile shower in the hall bathroom. The room is 5 by 8 feet.",
"site": { "address": "1180 Sample Ave NE", "city": "Atlanta", "state": "GA", "zip": "30306" },
"reference": "your-id-123"
}'
curl https://www.build4seasons.com/api/v1/outcomes/$OUTCOME_ID/confirm \
-H "Authorization: Bearer $FOURS_TEST_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hall-bath-confirm-1" \
-d '{
"window": "<one of windows[].id>",
"acceptTerms": true,
"contact": { "name": "Sample Homeowner", "email": "owner@sample.example" },
"answers": [{ "question": "<one of asks>", "answer": "The tile goes to the ceiling" }]
}'The steps, each with what it pays when verified and the photos that prove it.
The 4 Seasons Price and its six parts. kind is exact when the engine has nothing open, and band when it has questions. holdCents is what a confirm holds: the price, or the top of the band.
Questions that would narrow the price. Answer them at confirm with the question and your answer.
Weeks with enough reservable hours for the main trade. A test key sees simulated supply.
Each proof decision: who decided, the reasons and what it waits on.
Once every step is verified and paid: what the outcome cost from its own releases, and what the records don't hold yet.
Before work starts a 4 Seasons estimator walks the site and confirms the scope and the price in writing. 4 Seasons sets the visit with the site contact you give. In the sandbox this is skipped.
Proof the checks can't decide goes to a 4 Seasons reviewer, and the step waits for their decision. The answer gives our target for that review as people.reviewTargetHours. It is a target, not a measured time.
4 Seasons network pros do the work. The reservation holds the hours for the trade with the most hours; we schedule the other trades around it.
spend_limit and says how much is left. A person on your account can set a lower limit.Idempotency-Key. A retry with the same key and body gets the first answer back. Confirming again with the same window returns the same outcome.We take bathrooms, flooring and other interior finish work, decks and outdoor work in Atlanta. Anything else answers outcome_not_served with the reason and what we take, and nothing is stored.
/api/mcp, behind the same key and scopes.Quote an outcome
Confirm an outcome
Outcome status
Send simulated proof (sandbox)
Webhooks: subscribe to outcome.quoted, outcome.awaiting_approval, outcome.confirmed, outcome.step_changed, outcome.release_sent, outcome.completed and outcome.cancelled. The whole API is described at /api/v1/openapi.json.