SubTrack API

Read-only JSON API for your account's compliance data. Generate a token from Admin → API access inside the app.

Authentication

Send your token as a bearer token on every request:

curl /api/v1/subs \
  -H "Authorization: Bearer st_YOUR_TOKEN"

Tokens are shown once at creation and stored hashed — if you lose one, revoke it and generate another.

Rate limits

60 requests per minute per token. Exceeding it returns 429 with a Retry-After header (seconds). Design for polling no more than once a minute — the data changes at human speed.

GET /api/v1/subs

Every subcontractor with license info, compliance status, and full coverage detail.

compliant means checked against your requirements and passing. If you have not set coverage requirements, requirements_set is false and current certificates report not_checked rather than compliant — their dates are current and nothing further was asked of them, which is a different fact. issues lists the specific failures behind an expiring_soon or action_needed.

{
  "requirements_set": true,
  "subs": [
    {
      "id": "…",
      "name": "Desert Sky Electric LLC",
      "trade": "Electrical",
      "contact_email": "dispatch@desertskyelectric.com",
      "phone": "(602) 555-0101",
      "address": null,
      "license_number": "ROC 999001",
      "license_state": "AZ",
      "license_type": "CR-11 Electrical Contractor",
      "status": "compliant",           // compliant | not_checked | expiring_soon | action_needed
      "requirements_exempt": false,    // exempt subs skip requirement checks, expiry still tracked
      "issues": [],                    // why it is not compliant, e.g. "No current auto coverage on file"
      "coverages": [
        {
          "coverage_type": "license",  // general_liability | workers_comp | auto | umbrella | license | other
          "carrier": null,
          "policy_number": "ROC 999001",
          "license_type": "CR-11 Electrical Contractor",
          "effective_on": "2023-01-15",
          "expires_on": "2027-12-31",
          "limits": [{ "label": "Bond Amount", "amount": "$9,000" }],
          "additional_insured": null,
          "waiver_of_subrogation": null,
          "extracted_by": "ocr"        // ocr | manual
        }
      ]
    }
  ]
}

GET /api/v1/summary

Account-level counts — the dashboard's summary tiles as numbers.

{ "total_subs": 10, "requirements_set": true, "compliant": 6, "not_checked": 0, "expiring_soon": 2, "action_needed": 2 }

compliant and not_checked are mutually exclusive: every subcontractor whose certificates are current lands in exactly one, depending on requirements_set. The four counts always sum to total_subs.

Errors

401 — missing, malformed, or revoked token
429 — rate limit exceeded; retry after Retry-After seconds
404 — unknown endpoint

Versioning

The API is versioned in the path (/api/v1). Fields may be added without notice; existing fields won't change meaning or disappear within v1.