WHL Collections SaaS — API Reference v1.4.0¶

⚠ SUPERSEDED — see docs/engineering/API_REFERENCE.md for the canonical internal API reference.

The doc below is preserved for reference but is no longer maintained. The engineering version is more recent (705 LOC vs 472), explicitly scoped to internal engineers, and authoritative per docs/DOC_AUTHORITY_REGISTRY.md. New endpoint changes land there.

354 endpoints across 54 route modules. All routes require Bearer token auth unless marked PUBLIC.

Base URL: https://demo.wernerharmoniclabs.com or http://localhost:9033

Interactive docs: /docs (Swagger) | /redoc (ReDoc)

Health & Monitoring (PUBLIC)¶

Method	Endpoint	Description
GET	`/api/health`	Basic health check
GET	`/api/health/deep`	Deep health (7 subsystems)
GET	`/api/health/liveness`	Cloud Run liveness probe
GET	`/api/health/readiness`	Cloud Run readiness probe
GET	`/api/health/detailed`	Detailed system info
GET	`/api/monitoring/overview`	Full monitoring dashboard
GET	`/api/monitoring/dashboard`	Monitoring UI
GET	`/api/monitoring/volume`	Request volume metrics
GET	`/api/monitoring/latency`	Response latency metrics
GET	`/api/monitoring/errors`	Error rate breakdown
GET	`/api/version`	API version info

Authentication¶

Method	Endpoint	Description
POST	`/api/login`	Username/password login
GET	`/api/login/me`	Current user info
POST	`/api/login/refresh`	Refresh JWT token
GET	`/api/login/html`	Login page HTML
POST	`/auth/token`	API key auth
POST	`/auth/api-keys`	Create API key
GET	`/auth/api-keys`	List API keys
DELETE	`/auth/api-keys/{key_id}`	Revoke API key
GET	`/auth/me`	Token introspection

OAuth2 / SSO (PUBLIC)¶

Method	Endpoint	Description
GET	`/api/oauth/providers`	List enabled SSO providers
GET	`/api/oauth/google/login`	Redirect to Google consent
GET	`/api/oauth/google/callback`	Google OAuth callback
GET	`/api/oauth/microsoft/login`	Redirect to Microsoft consent
GET	`/api/oauth/microsoft/callback`	Microsoft OAuth callback

Queue Management¶

Method	Endpoint	Description
POST	`/api/queue/ingest`	Upload CSV portfolio
POST	`/api/queue/ingest/json`	Upload JSON portfolio
GET	`/api/queue/next/{agent_id}`	Get next account for agent
GET	`/api/queue/batch/{agent_id}`	Get batch of accounts
GET	`/api/queue/account/{account_id}`	Full account card
POST	`/api/queue/account/{account_id}/disposition`	Log disposition
GET	`/api/queue/stats`	Queue statistics
GET	`/api/queue/health`	Queue health
GET	`/api/queue/leaderboard`	Agent performance ranking
GET	`/api/queue/gaps`	Portfolio gap analysis
GET	`/api/queue/dashboard-breakdowns`	Chart breakdowns
GET	`/api/queue/search`	Full-text account search
GET	`/api/queue/random`	Random demo account

Agents¶

Method	Endpoint	Description
GET	`/api/agents/sync-manifest`	Agent roster manifest
GET	`/api/rankings`	Agent rankings
POST	`/api/rankings/upload`	Upload agent rankings CSV
GET	`/api/agent/{agent_id}/stats`	Agent performance stats
GET	`/api/agent/{agent_id}/queue`	Agent's assigned queue
GET	`/api/agent/{agent_id}/promises`	Agent's promises to pay
GET	`/api/agent/{agent_id}/activity`	Agent activity log

Method	Endpoint	Description
GET	`/api/widget/{account_id}`	HTML account widget
POST	`/api/widget/{account_id}/disposition`	Log disposition
GET	`/api/widget/{account_id}/alerts`	Account alerts
GET	`/api/widget/search`	Quick search
POST	`/api/widget/config`	Save widget config
GET	`/api/widget/config/{tenant_id}`	Get widget config

Payments¶

Method	Endpoint	Description
GET	`/api/payments/stats`	Payment statistics
GET	`/api/payments/broken-promises`	Broken PTP list
POST	`/api/payments/plans`	Create payment plan
GET	`/api/payments/plans`	List payment plans
GET	`/api/payments/plans/{plan_id}`	Get plan details
POST	`/api/payments/plans/{plan_id}/payment`	Record installment

Payment Plans¶

Method	Endpoint	Description
POST	`/api/payment-plans`	Create plan
GET	`/api/payment-plans/account/{account_id}`	Plans for account
GET	`/api/payment-plans/overdue/all`	All overdue plans
GET	`/api/payment-plans/{plan_id}`	Plan details
PUT	`/api/payment-plans/{plan_id}`	Update plan
DELETE	`/api/payment-plans/{plan_id}`	Cancel plan
POST	`/api/payment-plans/{plan_id}/payment`	Record payment

Compliance¶

Method	Endpoint	Description
GET	`/api/compliance`	Compliance events
GET	`/api/compliance/dashboard`	Compliance dashboard
GET	`/api/compliance/summary`	Risk summary
GET	`/api/compliance/check/{account_id}`	Check account compliance
GET	`/api/compliance/risk-score/{account_id}`	Risk score
GET	`/api/compliance/time-check`	TCPA time-of-day check
GET	`/api/compliance/state-rules/{state}`	State-specific rules
POST	`/api/compliance/record-attempt`	Log contact attempt
POST	`/api/compliance/auto-remediate`	Auto-fix violations
POST	`/api/compliance/acknowledge`	Acknowledge finding
POST	`/api/compliance/schedule-check`	Schedule compliance scan
GET	`/api/compliance/scan-history`	Scan history
POST	`/api/compliance/dnc/add`	Add to DNC list
POST	`/api/compliance/dnc/remove`	Remove from DNC
GET	`/api/compliance/dnc/check/{phone}`	Check DNC status
GET	`/api/compliance/docs`	Compliance documents
GET	`/api/compliance/docs/{doc_id}`	Get document

Compliance Gate (named public product endpoint)¶

The pre-execution gate. External systems (dialers, CRMs, batch workers, IVRs) call this before executing any regulated outbound contact action. Wraps the 12-gate governance pipeline. Fails closed on any internal error.

Method	Endpoint	Description
POST	`/api/gate/contact-intent`	Evaluate a contact intent — returns ALLOW or BLOCK with audit id

Request body:

{
  "account_id": "ACC-001",
  "phone": "(818) 555-1234",
  "channel": "phone",
  "action_type": "call",
  "source_system": "five9"
}

tenant_id is read from the JWT — never from the body. Phone is normalized to E.164 (+1XXXXXXXXXX) at intake before evaluation.

Response (always 200, never 4xx for gate decisions):

{
  "allow": false,
  "decision": "BLOCK",
  "reason": "Blocked by: COMPLIANCE",
  "blocked_by": ["COMPLIANCE"],
  "audit_id": 482,
  "evaluation_id": 1537,
  "account_id": "ACC-001",
  "tenant_id": "agency-prod",
  "channel": "phone",
  "source_system": "five9",
  "next_allowed_at": null,
  "expires_at": "2026-05-06T18:00:00Z"
}

audit_id is the row id in the SHA-256 hash-chained audit_log table — the caller can correlate the gate decision with its tamper-proof ledger entry. next_allowed_at is a coarse retry hint (only populated for G7 TIMING blocks). expires_at is the freshness window for the decision (24h). On any internal error the response is decision: "BLOCK" with blocked_by: ["SYSTEM_ERROR"] — fail-closed by design.

Disputes¶

Method	Endpoint	Description
POST	`/api/disputes`	Create dispute
GET	`/api/disputes`	List disputes
GET	`/api/disputes/stats`	Dispute statistics
GET	`/api/disputes/types`	Dispute type catalog
GET	`/api/disputes/statuses`	Status catalog
GET	`/api/disputes/{dispute_id}`	Get dispute
PUT	`/api/disputes/{dispute_id}`	Update dispute
POST	`/api/disputes/{dispute_id}/resolve`	Resolve dispute
POST	`/api/disputes/{dispute_id}/escalate`	Escalate dispute

Letters & Physical Mail¶

Method	Endpoint	Description
GET	`/api/letters/templates`	List letter templates
POST	`/api/letters/generate`	Generate letter from template
GET	`/api/letters`	List generated letters
GET	`/api/letters/queue`	Letters queued for sending
GET	`/api/letters/stats`	Letter statistics
GET	`/api/letters/{letter_id}`	Get letter content
GET	`/api/letters/{letter_id}/pdf`	Download as PDF
POST	`/api/letters/{letter_id}/send`	Mark as sent
POST	`/api/letters/mail`	Send via Lob (physical mail)
GET	`/api/letters/mail/{delivery_id}/status`	Delivery tracking
GET	`/api/letters/mail/history`	Mail history
GET	`/api/letters/mail/cost`	Cost estimate
GET	`/api/letters/templates/custom`	Custom templates
POST	`/api/letters/templates/upload`	Upload template
GET	`/api/letters/templates/{template_id}`	Get template
DELETE	`/api/letters/templates/{template_id}`	Delete template

Consumer Portal (PUBLIC)¶

Method	Endpoint	Description
GET	`/api/consumer/lookup`	Account lookup (ID + last4 SSN)
POST	`/api/consumer/payment`	Submit payment
POST	`/api/consumer/checkout`	Stripe checkout session
POST	`/api/consumer/dispute`	File dispute
GET	`/api/consumer/disputes`	List disputes
POST	`/api/consumer/disputes/{dispute_id}/resolve`	Resolve dispute
GET	`/api/consumer/payment-history`	Payment history
GET	`/api/consumer/payment-methods`	Saved payment methods
POST	`/api/consumer/verify/send`	Send OTP email
POST	`/api/consumer/verify/check`	Verify OTP code
GET	`/api/consumer/verify/status`	Check verification status
POST	`/api/consumer/webhook/stripe`	Stripe webhook handler
DELETE	`/api/consumer/data/{account_id}`	CCPA right-to-delete

Data Enrichment — RDN¶

Method	Endpoint	Description
POST	`/api/data-enrichment/rdn/lookup/ssn`	Lookup by SSN
POST	`/api/data-enrichment/rdn/lookup/account`	Lookup by account number
GET	`/api/data-enrichment/rdn/profile/{account_id}`	Full debtor profile
GET	`/api/data-enrichment/rdn/compliance/{account_id}`	Compliance data
POST	`/api/data-enrichment/rdn/placement`	Place account
POST	`/api/data-enrichment/rdn/recall/{account_id}`	Recall account
POST	`/api/data-enrichment/rdn/webhook`	Inbound webhook

Data Enrichment — DRN¶

Method	Endpoint	Description
POST	`/api/data-enrichment/drn/search/ssn`	Skip trace by SSN
POST	`/api/data-enrichment/drn/search/dob`	Skip trace by DOB
POST	`/api/data-enrichment/drn/search/address`	Skip trace by address
GET	`/api/data-enrichment/drn/contacts/{account_id}`	Contact data
POST	`/api/data-enrichment/drn/verify/employment`	Employment verification
POST	`/api/data-enrichment/drn/verify/identity`	Identity verification
POST	`/api/data-enrichment/drn/batch`	Batch skip trace

Data Enrichment — Skip Trace¶

Method	Endpoint	Description
POST	`/api/data-enrichment/skip-trace/search`	Unified search
POST	`/api/data-enrichment/skip-trace/batch`	Batch search
POST	`/api/data-enrichment/skip-trace/ui-search`	UI search (with DB persistence)
GET	`/api/data-enrichment/skip-trace/results/{search_id}`	Get search results
POST	`/api/data-enrichment/skip-trace/apply/{search_id}`	Apply result to account
GET	`/api/data-enrichment/skip-trace/history`	Search history
GET	`/api/data-enrichment/skip-trace/cost-summary`	Cost tracking
GET	`/api/data-enrichment/skip-trace/health`	Provider health

Integrations & Connectors¶

Method	Endpoint	Description
GET	`/api/integrations`	List all connectors
GET	`/api/integrations/status`	All connector statuses
GET	`/api/integrations/registry`	Connector registry
POST	`/api/integrations/{connector_id}/credentials`	Set credentials
POST	`/api/integrations/{connector_id}/toggle`	Enable/disable
POST	`/api/integrations/{connector_id}/sync`	Trigger sync
GET	`/api/integrations/{connector_id}/test`	Test connection
POST	`/api/integrations/{connector_id}/test-live`	Live connection test
GET	`/api/integrations/{connector_id}/connector-status`	Connector status
GET	`/api/integrations/{connector_id}/troubleshoot`	Troubleshooting guide
POST	`/api/integrations/{connector_id}/auto-fix`	Auto-fix issues
GET	`/api/integrations/{connector_id}/diagnostic-log`	Diagnostic logs
POST	`/api/integrations/{connector_id}/escalate`	Escalate issue

Dialer Connectors¶

Method	Endpoint	Description
POST	`/api/dialer/webhook/five9`	Five9 webhook
POST	`/api/dialer/webhook/convoso`	Convoso webhook
POST	`/api/dialer/webhook/generic`	Generic dialer webhook
GET	`/api/dialer/call-log`	Call log history
GET	`/api/dialer/config`	Dialer configuration
PUT	`/api/dialer/config`	Update dialer config
GET	`/api/connectors/dialer/{dialer_id}/screen-pop/{account_id}`	Screen pop data
POST	`/api/connectors/dialer/{dialer_id}/disposition`	Post-call disposition
GET	`/api/connectors/dialer/{dialer_id}/agents`	Dialer agent list
GET	`/api/connectors/dialer/{dialer_id}/metrics/{agent_id}`	Agent dialer metrics
POST	`/api/connectors/dialer/{dialer_id}/webhook`	Dialer event webhook

Billing & Subscriptions¶

Method	Endpoint	Description
GET	`/billing/plans`	Available pricing plans
POST	`/billing/subscribe`	Create subscription
POST	`/billing/checkout`	Stripe checkout session
GET	`/billing/config`	Stripe publishable key
GET	`/billing/subscription`	Current subscription
PUT	`/billing/seats`	Update seat count
GET	`/billing/invoices`	Invoice history
POST	`/billing/cancel`	Cancel subscription
POST	`/billing/reactivate`	Reactivate subscription
GET	`/billing/usage`	Usage dashboard
POST	`/billing/pilot`	Start 30-day free pilot
GET	`/billing/events`	Billing audit log
POST	`/billing/webhook`	Stripe webhook handler

Coaching & Second Voice¶

Method	Endpoint	Description
GET	`/api/coaching/agent/{agent_id}`	Agent coaching data
GET	`/api/coaching/floor`	Floor coaching overview
POST	`/api/coaching/second-voice/request`	Request second voice
GET	`/api/coaching/second-voice/queue`	Second voice queue
GET	`/api/coaching/second-voice/{request_id}`	Request details
POST	`/api/coaching/second-voice/{request_id}/respond`	Accept/decline
POST	`/api/coaching/second-voice/{request_id}/whisper`	Send whisper message
POST	`/api/coaching/second-voice/{request_id}/note`	Add coaching note
POST	`/api/coaching/second-voice/{request_id}/end`	End session
GET	`/api/coaching/second-voice/objections`	Objection library

Forecasting & ML¶

Method	Endpoint	Description
GET	`/api/forecasting/recovery`	Recovery rate forecast
GET	`/api/forecasting/settlement`	Settlement prediction
GET	`/api/forecasting/staffing`	Staffing model
GET	`/api/forecasting/aging`	Aging projection
GET	`/api/forecasting/liquidation`	Liquidation forecast
GET	`/api/forecasting/ml/monte-carlo`	Monte Carlo simulation
GET	`/api/forecasting/ml/time-series`	Holt-Winters forecast
GET	`/api/forecasting/ml/cohort`	Cohort analysis
GET	`/api/forecasting/ml/scenarios`	Scenario modeling
GET	`/api/forecasting/ml/waterfall`	Waterfall chart data

Reports & PDF¶

Method	Endpoint	Description
GET	`/api/reports/generate`	Generate report
GET	`/api/reports/templates`	Report templates
GET	`/api/reports/pdf/types`	Available PDF types
GET	`/api/reports/pdf/{report_type}`	Generate PDF report
GET	`/api/reports/pdf/preview/{report_type}`	Preview PDF
POST	`/api/reports/schedules`	Create scheduled report
GET	`/api/reports/schedules`	List schedules
GET	`/api/reports/schedules/{schedule_id}`	Get schedule
PUT	`/api/reports/schedules/{schedule_id}`	Update schedule
DELETE	`/api/reports/schedules/{schedule_id}`	Delete schedule
POST	`/api/reports/schedules/{schedule_id}/run`	Run immediately

Recordings¶

Method	Endpoint	Description
GET	`/api/recordings/search/`	Search recordings
GET	`/api/recordings/{call_id}`	Get recording
POST	`/api/recordings/{call_id}/flag`	Flag recording
POST	`/api/recordings/{call_id}/comment`	Add comment
GET	`/api/recordings/{call_id}/comments`	Get comments

Performance¶

Method	Endpoint	Description
GET	`/api/performance/leaderboard`	Performance leaderboard
GET	`/api/performance/team`	Team performance
GET	`/api/performance/agent/{agent_id}`	Agent performance
GET	`/api/performance/scorecard/{agent_id}`	Balanced scorecard
PUT	`/api/performance/scorecard/weights`	Set scoring weights

Tickets¶

Method	Endpoint	Description
POST	`/api/tickets`	Create ticket
GET	`/api/tickets`	List tickets
GET	`/api/tickets/stats`	Ticket statistics
GET	`/api/tickets/{ticket_id}`	Get ticket
PUT	`/api/tickets/{ticket_id}`	Update ticket
POST	`/api/tickets/{ticket_id}/comment`	Add comment
POST	`/api/tickets/import`	Import tickets

Webhooks (Outbound)¶

Method	Endpoint	Description
POST	`/api/webhooks`	Create webhook
GET	`/api/webhooks`	List webhooks
GET	`/api/webhooks/event-types/list`	Available event types
POST	`/api/webhooks/test`	Test webhook
GET	`/api/webhooks/{webhook_id}`	Get webhook
PUT	`/api/webhooks/{webhook_id}`	Update webhook
DELETE	`/api/webhooks/{webhook_id}`	Delete webhook
GET	`/api/webhooks/{webhook_id}/deliveries`	Delivery history

Exports¶

Method	Endpoint	Description
GET	`/api/exports/accounts`	Export accounts
GET	`/api/exports/payments`	Export payments
GET	`/api/exports/agents`	Export agents
GET	`/api/exports/compliance`	Export compliance
GET	`/api/exports/full`	Full data export
GET	`/api/exports/history`	Export history

Multi-Tenancy¶

Method	Endpoint	Description
GET	`/tenants`	List tenants
GET	`/tenants/{tenant_id}`	Get tenant
PUT	`/tenants/{tenant_id}/config`	Update tenant config
GET	`/tenants/{tenant_id}/setup-status`	Onboarding status
POST	`/tenants/{tenant_id}/users`	Add user to tenant
GET	`/tenants/{tenant_id}/users`	List tenant users
POST	`/onboard`	Start onboarding

Additional¶

Method	Endpoint	Description
GET	`/api/alerts/config`	Alert configuration
POST	`/api/alerts/config`	Update alerts
GET	`/api/approvals`	Approval queue
POST	`/api/approvals/submit`	Submit for approval
POST	`/api/approvals/{approval_id}/decide`	Approve/reject
GET	`/api/audit/trail`	Audit trail
GET	`/api/audit/stats`	Audit statistics
GET	`/api/creditor-rules`	Creditor rules
PUT	`/api/creditor-rules/{creditor_id}`	Update rule
GET	`/api/email/queue`	Email queue
POST	`/api/email/send`	Send email
GET	`/api/events/floor`	SSE event stream
GET	`/api/news/feed`	Industry news feed
GET	`/api/opportunities`	Collection opportunities
GET	`/api/retention/policy`	Data retention policy
PUT	`/api/retention/policy`	Update policy
POST	`/api/retention/purge`	Execute purge
GET	`/api/schedules`	Agent schedules
GET	`/api/theme`	Current theme
PUT	`/api/theme`	Update theme
POST	`/api/demo/setup`	Seed demo data

Generated from live route introspection. 354 endpoints total.