STVerify API Docs

Entity compliance intelligence for SBA lenders, banks, PE firms, insurers, and SaaS builders. Two live endpoints — Verify and Score — with Monitor in beta.

Authentication

All STVerify API requests require an API key passed as a Bearer token in the Authorization header.

Key formats:
  stv_live_*  — Production keys. Billed against your plan quota.
  stv_test_*  — Development keys. Free, unlimited in test mode.

Keys are scoped per product. A key with product_access: ["verify"] cannot call the /score endpoint.
Keys are shown once at creation. Store them securely — they cannot be retrieved after generation.

Example

Authorization: Bearer stv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET /verify

Point-in-time entity compliance check. Returns good standing status across all registered jurisdictions, upcoming filing due dates, registered agent status, active insurance policies, and overall compliance tier.

Parameters:
  ein          string  — Federal EIN (with or without hyphen)
  entity_id    uuid    — STVerify entity UUID
  name + state string  — Entity legal name + 2-letter state code

One of the above identifiers is required.

Example

curl -X GET \
  "https://ptgtliwllimkswtajcmy.supabase.co/functions/v1/stverify-verify?ein=20-1234567" \
  -H "Authorization: Bearer stv_live_your_key"

# Response
{
  "found": true,
  "object": "entity_verification",
  "api_version": "v1",
  "entity": {
    "id": "3a8f2c1d-4b5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "Redrock Industries LLC",
    "ein": "20-1234567"
  },
  "compliance": {
    "start_score": 88,
    "compliance_tier": "excellent",
    "good_standing": {
      "jurisdictions_in_good_standing": 7,
      "total_jurisdictions": 8,
      "good_standing_pct": 88
    },
    "annual_reports": {
      "next_due_date": "2026-09-01",
      "overdue": false
    },
    "insurance": {
      "active_policies": 5
    }
  }
}

GET /score

The Start Score™ as an API endpoint. 11-pillar compliance health index, continuously updated. Returns trend direction, pillar breakdown (optional), 12-month history (optional), and ROI context showing estimated annual penalty reduction.

Parameters:
  ein              string   — Federal EIN
  entity_id        uuid     — Entity UUID
  include_pillars  boolean  — Return all 11 pillar scores (default: false)
  include_history  boolean  — Return last 12 score snapshots (default: false)

Example

curl -X GET \
  "https://ptgtliwllimkswtajcmy.supabase.co/functions/v1/stverify-score?ein=20-1234567&include_pillars=true" \
  -H "Authorization: Bearer stv_live_your_key"

# Response
{
  "score": {
    "start_score": 88,
    "compliance_tier": "excellent",
    "trend_direction": "improving",
    "overdue_items": 1
  },
  "pillars": {
    "entity_compliance": 78,
    "hr_compliance": 85,
    "risk_insurance": 55,
    "state_tax": 82,
    "ownership_governance": 90,
    "kyc_aml": 70,
    "licenses_permits": 65,
    "ucc_liens_covenants": 80,
    "dataroom_readiness": 40,
    "sba_loans": 75,
    "financial_tax": 68
  },
  "roi_context": {
    "estimated_annual_penalty_reduction_usd": 5700,
    "methodology": "Conservative estimate based on statutory penalty data"
  }
}

Compliance Tiers

The compliance_tier field maps to Start Score ranges:

  certified       95 – 100   Top-tier compliance posture
  excellent       85 – 94    Strong compliance health
  good_standing   75 – 84    Favorable for lender review and insurance renewal
  improving       65 – 74    Active compliance progress
  developing      50 – 64    Material gaps requiring attention
  critical         0 – 49    Significant compliance exposure

Tiers are used in the Verify response, Score response, and Monitor webhook payloads.

Monitor (Beta)

Subscribe to entity compliance webhooks. Get notified when:
  
  score_change       — Start Score changes by 3+ points
  status_change      — Good standing status changes in any jurisdiction
  filing_overdue     — An annual report or filing becomes overdue
  insurance_lapse    — An insurance policy expires without renewal

Webhooks are signed with HMAC-SHA256 using your webhook_secret.
Retry policy: 3 attempts with exponential backoff (30s, 5m, 30m).

Contact api@stverify.com to join the Monitor beta.

Example

# Subscribe to an entity
curl -X POST \
  "https://ptgtliwllimkswtajcmy.supabase.co/functions/v1/stverify-monitor" \
  -H "Authorization: Bearer stv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ein": "20-1234567",
    "webhook_url": "https://yourapp.com/webhooks/stverify",
    "webhook_secret": "your_secret_here",
    "events": ["score_change", "status_change", "filing_overdue"]
  }'

# Webhook payload example
{
  "event": "score_change",
  "entity_id": "3a8f2c1d-...",
  "ein": "20-1234567",
  "previous_score": 81,
  "current_score": 88,
  "tier_change": { "from": "good_standing", "to": "excellent" },
  "fired_at": "2026-03-22T06:00:00Z"
}

Errors

STVerify uses standard HTTP status codes.

  200  OK                  Request succeeded
  400  Bad Request         Missing or invalid parameters
  401  Unauthorized        Invalid or missing API key
  403  Forbidden           Valid key but insufficient product access
  404  Not Found           Entity not found in the database
  429  Too Many Requests   Rate limit exceeded
  500  Internal Error      Server error — contact support

All error responses include a code field with a machine-readable identifier.

Example

# 401 example
{
  "error": "Missing or invalid API key. Use Authorization: Bearer stv_live_{key}",
  "code": "UNAUTHORIZED",
  "docs": "https://stverify.com/docs/authentication"
}

# 404 example
{
  "found": false,
  "code": "ENTITY_NOT_FOUND",
  "queried": { "ein": "12-3456789" }
}