Financial — TokenID

Get financial summary

GET/api/v1/financial/summary

Returns the aggregated financial opportunity breakdown for your account.

Response

{
  "recoverable_confirmed_usd": 142.50,
  "recoverable_review_usd": 38.20,
  "prevented_usd": 210.00,
  "preventable_modeled_usd": 95.40,
  "unexplained_critical_usd": 18.75,
  "unexplained_review_usd": 9.30,
  "total_financial_opportunity_usd": 514.15
}

Fields

Field	Description
`recoverable_confirmed_usd`	Billing errors confirmed by reconciliation — billable back to the provider
`recoverable_review_usd`	Potential errors flagged for human review
`prevented_usd`	Spend blocked by enforcement rules before reaching the provider
`preventable_modeled_usd`	Modeled savings if enforcement rules were applied to historical spend
`unexplained_critical_usd`	Critical anomalies with no matching provider explanation
`unexplained_review_usd`	Lower-confidence unexplained spend
`total_financial_opportunity_usd`	Sum of all above

Review queue

GET/api/v1/financial/review-queue

Returns violations queued for human review, ordered by dollar impact.

Resolve a dispute

PATCH/api/v1/financial/disputes/{dispute_id}

Mark a dispute as resolved.

{
  "resolution": "confirmed",
  "notes": "Provider confirmed billing error, credit issued."
}

Export disputes

GET /api/v1/financial/disputes/export

Returns a CSV of all disputes. Use ?status=open to filter.

Claims lifecycle

A claim is a billing dispute filed against a provider. TokenID generates a claim from confirmed reconciliation evidence, then tracks it from draft through submitted_to_provider to a terminal state — credit_issued, denied, or partial. Status transitions require the admin role.

Valid status values: draft, submitted_to_provider, provider_acknowledged, under_review, credit_approved, credit_issued, denied, partial, escalated.

Get a claim

GET/api/v1/claims/{claim_id}

Returns the full claim record including status, totals, external ticket reference, and evidence blob URLs.

curl https://token.audit.id/api/v1/claims/01HXY… \
  -H "Authorization: Bearer td_live_xxxx"

{
  "id": "01HXY…",
  "org_id": "01H00…",
  "period_start": "2026-04-01",
  "period_end": "2026-04-30",
  "provider": "anthropic",
  "total_recoverable_cents": 14250,
  "confidence_tier": "HIGH",
  "status": "draft",
  "submitted_at": null,
  "resolved_at": null,
  "external_ticket_id": null,
  "credit_issued_cents": null,
  "notes": null,
  "evidence_pdf_blob_url": "https://…/evidence.pdf",
  "evidence_csv_blob_url": "https://…/evidence.csv",
  "created_at": "2026-05-02T08:00:00Z",
  "evidence": { "pricing_snapshot": { /* … */ } }
}

Submit a claim

POST/api/v1/claims/{claim_id}/submit

Transitions the claim from draft to submitted_to_provider and stamps submitted_at. Returns the updated claim. 409 if the claim is not in draft.

curl -X POST https://token.audit.id/api/v1/claims/01HXY…/submit \
  -H "Authorization: Bearer td_live_xxxx"

Update claim status

PATCH/api/v1/claims/{claim_id}/status

Transition a claim to a new status. Used to record provider responses, denials, and issued credits.

Field	Type	Required	Description
`status`	string	Yes	Target status (see valid values above).
`denial_reason`	string	When status = `denied`	Free-text reason recorded on the outcome row.
`external_ticket_id`	string	No	Provider's support ticket reference.
`credit_issued_cents`	integer	When status = `credit_issued` or `partial`	Credit amount in cents.
`violation_type`	string	When status = `denied`	Violation taxonomy key, used by the weight-recompute job.

curl -X PATCH https://token.audit.id/api/v1/claims/01HXY…/status \
  -H "Authorization: Bearer td_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"status":"credit_issued","credit_issued_cents":14250,"external_ticket_id":"ANT-12345"}'

Returns the updated claim. 400 for unknown status, 409 for illegal transitions.

Get a support-ticket draft

GET/api/v1/claims/{claim_id}/ticket-draft

Generates a ready-to-paste support ticket draft (subject, body, suggested resolution, evidence references) for an escalated claim. Idempotent — re-generates from live data on every call. 409 if the claim is not in escalated status.

{
  "org_id": "01H00…",
  "claim_id": "01HXY…",
  "subject": "Billing discrepancy — Anthropic — Apr 2026",
  "body": "Hello Anthropic billing team, …",
  "suggested_resolution": "Issue a credit of $142.50 …",
  "evidence_refs": ["https://…/evidence.pdf", "https://…/evidence.csv"],
  "generated_at": "2026-05-21T08:00:00Z"
}

Pricing table

GET/api/v1/pricing/table

Returns the per-model unit pricing TokenID uses for cost computation. This is the same table the SDK fetches on startup. No authentication required — rates are public information.

curl https://token.audit.id/api/v1/pricing/table

Response

{
  "version": "v1-2026-05-15",
  "pricing": {
    "claude-opus-4-7": {
      "in_per_mtok": 15.0,
      "out_per_mtok": 75.0,
      "cache_read": 1.5,
      "cache_creation": 18.75
    },
    "gpt-4o": {
      "in_per_mtok": 2.5,
      "out_per_mtok": 10.0,
      "cache_read": 1.25,
      "cache_creation": 0.0
    }
  }
}

Field	Description
`version`	Snapshot version string, derived from the latest `updated_at`. Increments whenever any rate changes.
`pricing`	Map keyed by canonical model family.
`pricing.<model>.in_per_mtok`	USD per million input tokens.
`pricing.<model>.out_per_mtok`	USD per million output tokens.
`pricing.<model>.cache_read`	USD per million cache-read tokens.
`pricing.<model>.cache_creation`	USD per million cache-creation tokens.

For the full record set including provider and updated_at timestamps, use GET /api/v1/pricing instead.