Quickstart · test keys
Get a test key
Sign up at /developers/sign-up and confirm your email. Your first test key is on the page that opens, shown once. It starts 4s_test_. More are on Keys.
Send proof
POST the step, where the work is and the proof to /api/v1/verifications. Nothing moves and nothing changes on our side.
Check the answer
The decision is signed with the Work Record key. POST it to /api/v1/work-records/verify, or check it offline with our public keys.
curl https://www.build4seasons.com/api/v1/verifications \
-H "Authorization: Bearer $FOURS_TEST_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: step-12-try-1" \
-d '{
"step": {
"kind": "project.add-ons",
"reference": "your-step-12"
},
"job": {
"reference": "your-job-881",
"site": {
"lat": 33.7488,
"lng": -84.3877
}
},
"proof": {
"photos": [
{
"shot": "after",
"sha256": "9999999999999999999999999999999999999999999999999999999999999999",
"capturedAt": "2026-11-14T14:02:11Z",
"lat": 33.7489,
"lng": -84.3876,
"accuracyM": 8
}
]
},
"amountCents": 120000
}'Our checks passed and the release engine would let the money move now.
Our checks passed. The money would move after the window in the reasons.
Our checks could not decide on their own. A person has to look at the proof before money moves. Nobody at 4 Seasons looks unless you ask for a review, below. Otherwise a person on your side decides.
Something stops the money: no proof yet, proof that was sent back, a failed inspection or a failed reading.
sha256. With job.site and each photo's lat and lng, the answer also says whether the photos were taken at the work.{ "reference": { "job": "SJ-1042", "step": "tile" } } instead. It reads a step of one of your own settlement jobs.curl https://www.build4seasons.com/api/v1/verifications/$VERIFICATION_ID/review \
-H "Authorization: Bearer $FOURS_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"photoLinks": [
{
"sha256": "8888888888888888888888888888888888888888888888888888888888888888",
"url": "https://files.your-app.example/photos/after-14.jpg"
}
],
"note": "The grout line is by the tub."
}'review to the body, or later with the call above. Send a link to each photo you sent with the proof, so the reviewer can see it. A link we can't open slows the review down.verification.reviewed webhook and on GET /api/v1/verifications/{id}. It is release or hold, the reason in the reviewer's words, their role at 4 Seasons, and the versions of the proof standard and the dispute rules they held it to. It is signed like the decision, and the verify route checks it the same way.The kit is plain TypeScript with no network calls of its own. Your server registers each install's key and fetches a nonce before each photo. The app takes the photo from the live camera and seals the SHA-256 of its bytes, the device's time, the nonce, the job and step, and the place when the person allows it, signed with the install's own key. It isn't on a package registry yet.
import { captureWeb, currentLocation, deviceRegistration, openCamera, webSigner } from "@payonproof/capture";
// Once per install. The private key is made non-extractable and kept in IndexedDB.
const signer = await webSigner();
const registration = await deviceRegistration(signer, { platform: "web", label: "Crew tablet" });
// Send registration to your server, which registers it with 4 Seasons.
// For each photo: a nonce from your server first, then the live camera.
await openCamera(video);
const photo = await captureWeb(video, {
signer,
nonce,
job: "your-job-881",
step: "your-step-12",
shot: "after",
location: await currentLocation(),
});
// Upload photo.bytes and photo.seal to your server as they are.A sealed photo counts as live only when all six checks pass
The seal's signature checks with the public key you registered for its deviceKeyId.
That key is on your account, in this key's mode, and not revoked.
We issued the nonce to your account in this mode, for that install if you tied it to one, and it was never used before.
The photo's sha256 on the request is the one that was sealed.
The device's capture time is after the nonce was issued and before it ran out, and the photo is verified within the most a capture may age.
The sealed job and step match the request's, when both name one.
Idempotency-Key on a retry, so the retry gets the first answer back."attestation": "not_connected" and "protectionConfirmed": false. A software key is marked as one.The capture block from a real sealed run
Sent with "capture": { "schema": "4s.capture/v1", … } on the photo. It sits inside the signed decision.
{
"photos": 1,
"sealed": 1,
"live": 1,
"attestation": "not_connected",
"results": [
{
"index": 0,
"shot": "after",
"live": true,
"checks": {
"signature": true,
"device": true,
"nonce": true,
"hash": true,
"time": true,
"reference": true
},
"protection": "browser",
"protectionConfirmed": false,
"problems": []
}
],
"text": "1 of the 1 photos counts as taken live. Each was sealed on a registered device after a nonce we issued and is unchanged since. Platform attestation is not connected, so a key's protection is as the app reports it. Live is about when and on which device a photo was taken. What it shows is still for the proof checks and the release engine, and a person looks where the reasons say so."
}Send proof for one step; get the release decision, its reasons and the proof standard version, signed
For software that runs its own payments. Send the step (a kind from /pay-on-proof/standard.json), the job context and the proof (photo SHA-256 fingerprints with time and place, readings, an inspection result), or a reference to a step of one of your settlement jobs. The proof checks and the release decision are the ones 4 Seasons runs on its own jobs. outcome is release, release_after, needs_review or hold. needs_review means a person has to look before money moves. Nobody at 4 Seasons looks unless you ask: send review (with a link to each photo) and one of our people decides, billed when they decide. A photo taken outside the 4 Seasons apps counts as taken live only when it carries a seal from the capture kit and every check on it passes (registered key, our unused nonce, matching hash, time inside the nonce's window); capture says which checks passed. Nothing else moves, and nothing is changed apart from using up those nonces. The answer is signed with the Work Record key (schema 4s.verification-decision/v1). POST it to /api/v1/work-records/verify to check it.
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/verifications" \
-H "authorization: Bearer $FOURS_KEY" \
-H "content-type: application/json" \
-d '{"step":{"kind":"project.add-ons","reference":"your-step-12"},"job":{"reference":"your-job-881","site":{"lat":33.7488,"lng":-84.3877}},"proof":{"photos":[{"shot":"after","sha256":"9999999999999999999999999999999999999999999999999999999999999999","capturedAt":"2026-11-14T14:02:11Z","lat":33.7489,"lng":-84.3876,"accuracyM":8}]},"amountCents":120000}'The answer201
{
"schema": "4s.verification-decision/v1",
"verificationId": "ver_a05ee009a924564bd612ca36",
"livemode": false,
"decidedAt": "2026-11-14T15:00:00.000Z",
"outcome": "needs_review",
"releaseDecision": "needs_person",
"reasons": [
{
"code": "check_waiting",
"blocks": true,
"text": "Upgrades is waiting for its check."
}
],
"checks": {
"status": "review",
"verdict": "reject",
"confidence": 0.95,
"ruleVersion": "oracle-1/project.add-ons@1/r1",
"gate": [
"The oracle's send-backs haven't shown enough precision on this rule version"
],
"problems": []
},
"who": {
"checksAutomated": true,
"needsPerson": true,
"personDecidedAt": null,
"text": "Our checks ran without a person and could not decide this on their own. A person has to look at the proof before money moves. Nobody at 4 Seasons looks unless you ask for a review. Your team decides, or you ask for a review and one of our people decides."
},
"proofStandard": {
"release": 1,
"effective": "2026-11-13",
"engine": "oracle-1",
"kind": "project.add-ons",
"kindVersion": 1,
"generic": false
},
"inputHash": "sha256:f8da5b67c734ed4e6fbb5a274d2e1cf6787a60c9a669930f683fbb3856665357",
"reference": {
"job": "your-job-881",
"step": "your-step-12"
},
"capture": {
"photos": 1,
"sealed": 0,
"live": 0,
"attestation": "not_connected",
"results": [],
"text": "None of the 1 photos came with a seal from the capture kit, so none counts as taken live. Live is about when and on which device a photo was taken. What it shows is still for the proof checks and the release engine, and a person looks where the reasons say so."
},
"integrity": {
"verificationId": "ver_a05ee009a924564bd612ca36",
"issuedAt": "2026-11-14T15:00:00.000Z",
"contentHash": "sha256:1db4fd4afe2fc27fc51a692871c1fe1816ba5ba2bb158b6c910a62cc84d6aee4",
"signature": {
"alg": "ed25519",
"keyId": "4s-wr-5f088511120bf1e4",
"value": "QBjROIc8j_vRHycWqlYCwghJNP4vn2rwf2AZFlfevt-kV8FZJS2nTvJxRAYPea17FByOlnpzaHMJ0E-E3iKMAA"
}
}
}A decision as it was signed, and its review by a 4 Seasons person when you asked for one
review is null when none was asked for. While a review waits, it says when it is due by under the target (developer.review.target_hours). Once decided, review.decision is the signed review (schema 4s.verification-review/v1): release or hold, the reviewer's role at 4 Seasons, how many minutes it took, and the proof standard and dispute rules versions it was held to. Not billed.
idstringPathrequired
curl "https://www.build4seasons.com/api/v1/verifications/{id}" \
-H "authorization: Bearer $FOURS_KEY" \
-H "content-type: application/json" \
-d '{"note":"GET /api/v1/verifications/ver_fab8c02534bb88bc9412a0c9"}'The answer200
{
"object": "verification",
"id": "ver_fab8c02534bb88bc9412a0c9",
"decision": {
"who": {
"text": "Our checks ran without a person and could not decide this on their own. A person has to look at the proof before money moves. Nobody at 4 Seasons looks unless you ask for a review. Your team decides, or you ask for a review and one of our people decides.",
"needsPerson": true,
"checksAutomated": true,
"personDecidedAt": null
},
"checks": {
"gate": [
"The oracle's send-backs haven't shown enough precision on this rule version"
],
"status": "review",
"verdict": "reject",
"problems": [],
"confidence": 0.95,
"ruleVersion": "oracle-1/project.add-ons@1/r1"
},
"schema": "4s.verification-decision/v1",
"capture": {
"live": 0,
"text": "None of the 1 photos came with a seal from the capture kit, so none counts as taken live. Live is about when and on which device a photo was taken. What it shows is still for the proof checks and the release engine, and a person looks where the reasons say so.",
"photos": 1,
"sealed": 0,
"results": [],
"attestation": "not_connected"
},
"outcome": "needs_review",
"reasons": [
{
"code": "check_waiting",
"text": "Upgrades is waiting for its check.",
"blocks": true
}
],
"livemode": false,
"decidedAt": "2026-11-14T15:00:00.000Z",
"inputHash": "sha256:1bd9118c1b19e4e04b9a2526478321b40864a81945e085bf9659f4367c2a4495",
"integrity": {
"issuedAt": "2026-11-14T15:00:00.000Z",
"signature": {
"alg": "ed25519",
"keyId": "4s-wr-5f088511120bf1e4",
"value": "coz8OKUPQ2A8T6D1eGcaHgZXFsqFjiI89giv6YjDSM6zPMDgTDlFRGvwpE9WO4NCbuhL6hNlbk_96Jz2MaMvDA"
},
"contentHash": "sha256:ceb19f6d4423fbb0084bb8ed3b3b24e53bf0fc0749cf08ac3079091f37b1675a",
"verificationId": "ver_fab8c02534bb88bc9412a0c9"
},
"reference": {
"job": "your-job-881",
"step": "your-step-14"
},
"proofStandard": {
"kind": "project.add-ons",
"engine": "oracle-1",
"generic": false,
"release": 1,
"effective": "2026-11-13",
"kindVersion": 1
},
"verificationId": "ver_fab8c02534bb88bc9412a0c9",
"releaseDecision": "needs_person"
},
"review": {
"object": "verification_review",
"id": "vrv_4d8fa1f7c9b0ad8dc1974f7f",
"verificationId": "ver_fab8c02534bb88bc9412a0c9",
"livemode": false,
"status": "decided",
"requestedAt": "2026-11-14T15:01:00.000Z",
"targetHours": 24,
"dueBy": "2026-11-15T15:01:00.000Z",
"priceCents": null,
"billed": "on_decision",
"text": "A person at 4 Seasons (Founder) looked at the proof and decided it can be released. It took 1 hour 42 minutes from when you asked. The checks before it ran without a person.",
"decision": {
"note": "The after photo shows the full wall, sealed, with even grout lines.",
"text": "A person at 4 Seasons (Founder) looked at the proof and decided it can be released. It took 1 hour 42 minutes from when you asked. The checks before it ran without a person.",
"schema": "4s.verification-review/v1",
"minutes": 102,
"outcome": "release",
"livemode": false,
"reviewId": "vrv_4d8fa1f7c9b0ad8dc1974f7f",
"reviewer": {
"role": "Founder",
"person": true
},
"decidedAt": "2026-11-14T16:43:00.000Z",
"integrity": {
"issuedAt": "2026-11-14T16:43:00.000Z",
"signature": {
"alg": "ed25519",
"keyId": "4s-wr-5f088511120bf1e4",
"value": "a-AwFdmLSsDC0-_m1k50s_uAj8jU_Cyaf0DCvn_DQPIDfwrOU5A1RMC-Bw4aQWBHkwKQt3mXziK6OxyX19lICA"
},
"contentHash": "sha256:b2f81537cdd66890d36d3f27d8e1605628d1b2b814cdd842aa6b7b7efa7ff11c",
"verificationId": "ver_fab8c02534bb88bc9412a0c9"
},
"standards": {
"disputeRules": {
"path": "/pay-on-proof/rules",
"version": "c83fe2dc21b0"
},
"proofStandard": {
"kind": "project.add-ons",
"path": "/pay-on-proof/standard",
"release": 1,
"effective": "2026-11-13",
"kindVersion": 1
}
},
"requestedAt": "2026-11-14T15:01:00.000Z",
"targetHours": 24,
"withinTarget": true,
"verificationId": "ver_fab8c02534bb88bc9412a0c9",
"verificationContentHash": "sha256:ceb19f6d4423fbb0084bb8ed3b3b24e53bf0fc0749cf08ac3079091f37b1675a"
}
}
}Ask a 4 Seasons person to review a needs_review decision
A person in 4 Seasons operations looks at the proof and decides release or hold. Send a link to each photo you sent with the proof, so they can see it. Asking again returns the same review. 409 not_needs_review for any other outcome. The answer comes by the verification.reviewed webhook and on GET /api/v1/verifications/{id}. A review is billed as its own product when the reviewer decides it, never when it is asked for; test reviews are never billed.
idstringPathrequired
Idempotency-KeystringHeader
Honored when sent: a retry with the same key and body gets the first answer back.
photoLinksobject[]Body
A link to each photo you sent with the proof, so our reviewer can see it
photoLinks[].sha256stringBody
The photo's SHA-256, as sent with the proof
photoLinks[].urlstringBody
An https link our reviewer can open the photo at
notestringBody
Anything the reviewer should know
curl -X POST "https://www.build4seasons.com/api/v1/verifications/{id}/review" \
-H "authorization: Bearer $FOURS_KEY" \
-H "content-type: application/json" \
-d '{"photoLinks":[{"sha256":"8888888888888888888888888888888888888888888888888888888888888888","url":"https://files.your-app.example/photos/after-14.jpg"}],"note":"The grout line is by the tub."}'The answer202
{
"object": "verification_review",
"id": "vrv_4d8fa1f7c9b0ad8dc1974f7f",
"verificationId": "ver_fab8c02534bb88bc9412a0c9",
"livemode": false,
"status": "queued",
"requestedAt": "2026-11-14T15:01:00.000Z",
"targetHours": 24,
"dueBy": "2026-11-15T15:01:00.000Z",
"priceCents": null,
"billed": "on_decision",
"text": "It is waiting for a 4 Seasons reviewer. We aim to decide within 24 hours of when you asked. The answer comes by the verification.reviewed webhook and on GET, with how long it really took.",
"decision": null
}Register an install's capture key
The proof capture kit (packages/capture). Your server sends the install's public key (ECDSA P-256, SPKI, base64url) as the kit's deviceRegistration() makes it. The answer's deviceKeyId is the id the install's seals carry. Registering the same key again answers with the same device. protection is recorded as your app reports it: platform attestation (App Attest, Play Integrity) is not connected, so protectionConfirmed is false. Free.
publicKeystringBodyrequired
The install's public key: ECDSA P-256, SubjectPublicKeyInfo DER, base64url. deviceRegistration() in the kit makes this body
protection"hardware" | "browser" | "software"Bodyrequired
Where the private key lives, as your app knows it: hardware (Secure Enclave, Android Keystore), browser (non-extractable WebCrypto) or software. Recorded as your claim; attestation is not connected
platform"web" | "ios" | "android" | "other"Bodyrequired
labelstringBody
Your name for the install, such as a crew phone
curl -X POST "https://www.build4seasons.com/api/v1/capture/devices" \
-H "authorization: Bearer $FOURS_KEY" \
-H "content-type: application/json" \
-d '{"publicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEludjefqMmHxZ2cULvicCYoj5Ijj7z9yS-QB9_OsMEsmntiDca58x8EPhQPJ0sG_7uQjBzA6BwePiEtEAgLDz1w","protection":"browser","platform":"web","label":"Crew tablet 2"}'The answer201
{
"id": "8447f901-0abd-4dba-84aa-2023538c6cdd",
"deviceKeyId": "cdk_500bb1a968e628624111bb0dbb5aca7e",
"livemode": false,
"protection": "browser",
"protectionConfirmed": false,
"attestation": "not_connected",
"platform": "web",
"label": "Crew tablet 2",
"createdAt": "2026-11-14T13:00:00.000Z",
"revokedAt": null
}Your registered capture keys in this mode
No parameters.
curl "https://www.build4seasons.com/api/v1/capture/devices" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"data": [
{
"id": "8447f901-0abd-4dba-84aa-2023538c6cdd",
"deviceKeyId": "cdk_500bb1a968e628624111bb0dbb5aca7e",
"livemode": false,
"protection": "browser",
"protectionConfirmed": false,
"attestation": "not_connected",
"platform": "web",
"label": "Crew tablet 2",
"createdAt": "2026-11-14T13:00:00.000Z",
"revokedAt": null
}
]
}Revoke an install's capture key
By the device's id or its deviceKeyId. From then on its seals don't count as live, including ones not yet verified.
idstringPathrequired
curl -X DELETE "https://www.build4seasons.com/api/v1/capture/devices/{id}" \
-H "authorization: Bearer $FOURS_KEY"The answer200
{
"id": "dbe77957-9f2e-47e8-be1f-970285c917ee",
"deviceKeyId": "cdk_d4bcf709a0ebf6d2e670ef432b8d7555",
"livemode": false,
"protection": "browser",
"protectionConfirmed": false,
"attestation": "not_connected",
"platform": "web",
"label": null,
"createdAt": "2026-11-14T17:56:15.842Z",
"revokedAt": "2026-11-14T16:00:00.000Z"
}Issue capture nonces, one per photo, before the photos are taken
Each nonce is good for a capture for the nonce lifetime in the settings registry (developer.capture.nonce_minutes) and counts once. A sealed photo counts as live only when it was taken after its nonce was issued and before it ran out, and is verified within developer.capture.max_age_hours. Give deviceKeyId to tie the nonces to one install. Free: not metered.
countintegerBody
Nonces to issue, one per photo
deviceKeyIdstringBody
Tie the nonces to one registered install: a seal from any other key won't count
curl -X POST "https://www.build4seasons.com/api/v1/capture/nonces" \
-H "authorization: Bearer $FOURS_KEY" \
-H "content-type: application/json" \
-d '{"count":1,"deviceKeyId":"cdk_500bb1a968e628624111bb0dbb5aca7e"}'The answer201
{
"nonces": [
{
"nonce": "cn_yy4oNp59vAVAM2foFvbD83lZAPqvJxwz",
"issuedAt": "2026-11-14T14:00:00.000Z",
"expiresAt": "2026-11-14T14:10:00.000Z"
}
],
"livemode": false,
"deviceKeyId": "cdk_500bb1a968e628624111bb0dbb5aca7e"
}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" \
-d '{"note":"The decision exactly as you received it"}'The answer200
{
"valid": true,
"schemaOk": true,
"hashOk": true,
"signatureOk": true,
"contentHash": "sha256:1db4fd4afe2fc27fc51a692871c1fe1816ba5ba2bb158b6c910a62cc84d6aee4",
"keyId": "4s-wr-5f088511120bf1e4",
"problems": [
"Made with a test key: a sandbox decision."
],
"schema": "4s.verification-decision/v1",
"onFile": {
"matches": true,
"livemode": false
}
}400invalid_request
The body doesn't match the schema. The message names the field. For a review, also a photo with no link.
401unauthorized
No key, or a key we don't know.
403forbidden
The key doesn't have the verification:write scope.
403no_account
The key isn't on a developer account.
403live_not_enabled
A live key on an account 4 Seasons hasn't turned live on for yet. Test keys work.
404not_found
A reference to a job or step, a verification id or a capture device that isn't one of yours in this mode.
409not_needs_review
A review asked for on a decision that isn't needs_review. Only those go to a person.
409key_in_use
A capture key already registered to another account or mode. Make a new key on the install.
409key_revoked
A capture key you revoked. Make a new key on the install and register it.
429rate_limited
More requests in a minute than the key allows. The retry-after header says when to try again.
Limits are per key per minute, with x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset on every answer. The whole API is described at /api/v1/openapi.json.