Scope

Use this API when you need remaining capacity, which billing mode is active, and how much of this month’s usage has already been billed — for example dashboards, pre-flight "can I run this check?" UX, or low-balance alerts.

Do not use it for per-check history, date-range reporting, or as a substitute for the check APIs themselves.

What it returns

A precomputed summary of how the authenticated account is billed for one feature, plus remaining capacity across these modes:

Checks are deducted in this order (also returned as data.billing_precedence):

• postpay
• subscription
• Pay-as-you-go
• credit pack

If several modes are enabled: true, the first one in that list is the one that will be charged next.

Request

Common feature slugs

"tin_check", "tax_transcript", "tax_transcript_individual", "transcript_eservice", "boi_reporting", "bulk_tin_check", "vendor-onboarding", "watchlist_screening", "public-records-search", "individual-tax-assessment-report", "income-verification", "business-tax-assessment-report", "business-verification", "vendor-onboarding-essentials", "tax_exempt", "sos_search", "name_lookup", "us_address_verification", "us_address_verification_v2", "watchlist_ofac", "death_master_file", "i9_verification", "fatca_giin_search"

If you pass an unknown slug, the 400 invalid_feature body includes supported_features — use that list rather than hard-coding every KYB country.

Success response (200):

{
  "success": true,
  "success_message": "Retrieved data successfully",
  "data": { }
}

{
  "last_updated_at": "2026-08-13T11:00:00+00:00",
  "latest_usage_at": "2026-08-13T10:42:11+00:00",
  "feature": "tin_check",
  "user": "[email protected]",
  "billing_precedence": ["postpay", "subscription", "Pay-as-you-go", "credit_pack"],
  "wallet_balance": {
    "amount": 125.50,
    "currency": "USD"
  },
  "entitlements": {
    "subscription": {
      "enabled": true,
      "total_allocated": 12000,
      "total_used": 4300,
      "total_expired": 0,
      "total_remaining": 7700,
      "monthly_allocated": 1000,
      "monthly_used": 240,
      "monthly_remaining": 760,
      "current_month_billing_cycle": {
        "start_date": "2026-08-01T00:00:00+00:00",
        "end_date": "2026-08-31T23:59:59+00:00"
      },
      "renewal_date": "2026-08-31T23:59:59+00:00"
    },
    "Pay-as-you-go": {
      "enabled": false,
      "current_month": "2026-08",
      "checks_used": 0
    },
    "credit_packs": {
      "enabled": true,
      "total_allocated": 500,
      "total_used": 120,
      "credits_expired": 0,
      "total_remaining": 380,
      "packs": [
        {
          "allocated": 500,
          "checks_used": 120,
          "remaining": 380,
          "valid_till": "2027-02-03T14:00:00+00:00",
          "digital_buy": true,
          "free_checks": false
        }
      ]
    },
    "postpay": {
      "enabled": false,
      "current_month": "2026-08",
      "checks_used": 0
    }
  }
}

Field notes:

Note: Do not add remaining checks across modes. Follow billing_precedence and use the first enabled mode.

Errors:

{
  "success": false,
  "errors": [
    {
      "code": "invalid_feature",
      "message": "The specified feature 'tincheck' is not supported.",
      "supported_features": ["tin_check", "giin_search", ...]
    }
  ],
  "data": null
}

{
  "detail": ["Invalid token header. No credentials provided."]
}

Retry 500 with backoff. Do not retry 400 for the same feature without changing the request. On 403, refresh the token once, then re-authenticate if refresh fails.

Freshness and rate of calling

The payload is not realtime. Summaries are rebuilt on a ~30 minute cycle and served from cache for the same window.

• Polling faster than every 30 minutes will not make remaining counts more current.
• Cache the response locally keyed by feature + calendar month (YYYY-MM).
• current_month / billing cycle is the calendar month in UTC, e.g. "2026-08". There is no from / to filter.

Integration checklist

1. Authenticate with JWT (or OAuth) and send Authorization: Bearer ….
2. Call with an exact feature slug; keep a local map of the features your product uses.
3. Treat success === true as the only success path; always inspect errors[].code on failure.
4. Use billing_precedence + entitlements.*.enabled to decide which remaining number to use.
5. Do not mix units: subscription and credit packs are check counts; Pay-as-you-go checks_used and wallet_balance are USD.
6. Call once per feature; fan out in parallel if you need several features, and cache.
7. If you get no_usage_summary, the account likely has no entitlement for that feature yet — surface a “contact support / subscribe” state rather than retrying.