BuildPaid Partner API

Sign in to BuildPaid, then come back to this page to create a key for your organisation.

curl https://app.buildpaid.ai/api/v1/projects \
  -H "Authorization: Bearer bpk_<key id>_<secret>"

Every answer has the same shape: { "ok": true, "data": …, "meta": { "org", "api_version", "request_id", "page" } }. A refusal is { "ok": false, "code", "error", "status", "request_id", "docs" } — code is stable, error is for people. Every answer also carries an x-request-id header; quote it to support.

With a key in $KEY, these five calls read one project end to end.

H="Authorization: Bearer $KEY"; B=https://app.buildpaid.ai/api/v1
curl -s $B/me -H "$H"                              # 1. who am I: org, scopes
curl -s "$B/projects?limit=5" -H "$H"              # 2. my projects (and projects shared with me)
P=<a project id from step 2>
curl -s $B/projects/$P/readiness -H "$H"           # 3. the governed verdict: READY, BLOCKED or REVIEW, and why
curl -s $B/projects/$P/draws -H "$H"               # 4. the draws, each with its decision
curl -s "$B/projects/$P/events?limit=20" -H "$H"   # 5. the audit trail that produced it

A lender's key reads only its own organisation, until a project's GC shares that project with it. The lender sends its organisation id (from GET /api/v1/me) to the GC; the GC, signed in, shares the project read-only:

POST /api/v1/projects/<project id>/shares
{ "grantee_org": "<lender org id>", "scopes": ["read:projects", "read:draws", "read:compliance"] }

The lender's key then lists that project with shared_by naming the GC. The GC can revoke it at any time with DELETE /api/v1/projects/<id>/shares/<org>. A share never allows a write.

A lender, inspector, accounting or PM system, bank, insurer, notary provider or municipality reports what it knows about a project as a claim. BuildPaid records who said it and exactly what (a SHA-256 of the payload), checks it against its own records, and shows the result to the project's owner, who accepts or rejects it with a note. A claim never changes a draw, a change order or any other record.

Your key needs the scope for the kind of claim (claim:disbursement, claim:inspection, claim:payment, claim:milestone, claim:change_order, claim:notarization, claim:bank_receipt, claim:coverage, claim:permit); keys never get these unless they are chosen when the key is made. For a project you do not own, its GC shares it with you naming the same scope:

POST /api/v1/projects/<project id>/shares
{ "grantee_org": "<your org id>", "scopes": ["read:projects", "read:draws", "claim:disbursement"] }

Then report, with your own reference (sending the same reference again returns the same claim):

POST /api/v1/claims/disbursement
{ "project_id": "<project id>", "external_ref": "wire-2026-10-19-001", "draw_id": "<draw id>", "amount": 112500.00, "disbursed_on": "2026-10-19" }

The answer carries the claim's status: CORROBORATED (matches BuildPaid's records), CORROBORATED_WITH_NOTES, CONFLICT (for example funds reported disbursed on a draw BuildPaid holds), UNMATCHED (names something BuildPaid does not know), RECORDED (nothing to compare with) or PENDING_REVIEW (a change order: it becomes one only when a person makes it), with each check in checks[]. What each kind needs: GET /api/v1/claim-types. Claims you filed, and claims about your projects: GET /api/v1/claims?project_id=…&status=….

Every list answers meta.page = { limit, total, next_cursor }. Ask for the next page with ?cursor=<next_cursor>; limit is 1–500 (default 100). A null next_cursor is the last page. A cursor is valid only for the path that issued it. The event trail also accepts before=<id>.

A sandbox organisation with fictional GCs, lenders and subcontractors — three projects with draws, a schedule of values, change orders, compliance documents, lien waivers and their audit trail — is being prepared for pilot partners. Pilot partners receive a sandbox key on request; production keys are created on this page.

Machine-readable contract: /api/v1/openapi.json (OpenAPI 3.1)