Contractor investigation API.

All requests require a Bearer token sent as Authorization. Generate keys from the API Keys dashboard. Keys are hashed at rest with SHA-256; only the prefix is recoverable.

Authorization: Bearer bsk_live_…

Queue a new contractor investigation. Returns 202 Accepted with a report_id and a status_url to poll.

curl -X POST https://buildsafe.app/api/public/v1/investigations \
  -H "Authorization: Bearer bsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Construction LLC",
    "state": "TX",
    "license_number": "1234567",
    "city": "Austin",
    "owner_name": "Jane Doe",
    "phone": "+15125550100",
    "website": "https://acme-construction.example"
  }'

# 202 Accepted
{
  "report_id": "rpt_8f3a…",
  "status": "queued",
  "plan": "growth",
  "status_url": "https://buildsafe.app/api/public/v1/investigations/rpt_8f3a…"
}

Poll until status is complete. Most reports finish in under 5 minutes; the API holds the request open for 60s per poll.

{
  "report_id": "rpt_8f3a…",
  "status": "complete",
  "trust_score": 84,
  "verdict": { "verdict": "Proceed With Caution", "rationale": "…" },
  "evidence_dashboard": [
    { "row": "License Board", "status": "verified", "finding": "Active · Class B", "source_url": "https://www.tdlr.texas.gov/…" },
    { "row": "OSHA Citations", "status": "verified", "finding": "None on record", "source_url": "https://www.osha.gov/…" }
  ],
  "modules": {
    "license": { /* … */ },
    "court": { /* … */ },
    "permits": { /* … */ },
    "subcontractor_network": { /* … */ },
    "osha": { /* … */ },
    "dol_whd": { /* … */ },
    "bbb": { /* … */ },
    "yelp_google": { /* … */ },
    "review_nlp": { /* … */ },
    "sos": { /* … */ },
    "news_social": { /* … */ },
    "snapshot_diff": { /* … */ }
  }
}

Optional. Provide a callback_url on create and BuildSafe will POST the final payload with an HMAC SHA-256 signature in X-BuildSafe-Signature using your webhook secret. Always verify before processing.

Quotas are enforced on a 30-day rolling window per key. When a key exceeds its plan, 429 quota_exceeded is returned with X-BuildSafe-Quota-Reset. Other errors follow standard HTTP codes with a JSON error object.

{ "error": "quota_exceeded", "plan": "starter", "monthly_quota": 50, "used": 50, "resets_at": "2026-07-15T00:00:00Z" }