Get Account Usage Summary for Authenticated User for each feature

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):

1. postpay
2. subscription
3. Pay-as-you-go
4. 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.