API Reference

DebtRecoup exposes a same-origin JSON API for the Vue application, embedded payment portal, integrations, webhooks, and administrator tooling.

This page documents the implemented API surface at a practical level. For request and response schemas, use the running application's OpenAPI output.

Runtime URLs

Surface	Local URL	Notes
Application API	http://localhost:8080/api/v1	Main authenticated API used by the app.
OpenAPI JSON	http://localhost:8080/v1/openapi.json	Generated from the Spring controllers.
Swagger UI	http://localhost:8080/docs	Interactive API explorer when enabled for the environment.
Webhooks	http://localhost:8080/webhooks	Provider callbacks are outside /api/v1.
Payment portal script	http://localhost:8080/portal/payment.js	Public embed script for the payment portal.

The frontend uses axios.defaults.baseURL = '/api/v1', so browser requests are normally sent to the same host as the application.

Authentication

DebtRecoup supports browser sessions and bearer-token API access.

Browser Login

The login form posts to POST /api/v1/login with an X-TENANT-ID header and JSON credentials:

curl -i -X POST 'http://localhost:8080/api/v1/login' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: <tenant-id>' \
  --data '{"username":"<email>","password":"<password>"}'

A successful login returns a JWT in the response body and sets an accessToken HTTP-only cookie. Authenticated browser requests then use that cookie.

Personal Access Tokens

Users can manage personal access tokens through:

Method	Path	Purpose
GET	/api/v1/user/tokens	List the current user's tokens.
POST	/api/v1/user/tokens	Generate a token.
POST	/api/v1/user/tokens/{id}/rotate	Rotate a token.
DELETE	/api/v1/user/tokens/{id}	Delete a token.

When using a personal access token, send it as a bearer token and include the tenant header:

Authorization: Bearer debt_recoup_pat_...
X-TENANT-ID: <tenant-id>

JWT Bearer Tokens

The access token returned by login can also be supplied as:

Authorization: Bearer <jwt>

For JWT requests, the server reads the tenant from the token. For personal access tokens, the tenant header is required.

Endpoint Groups

The current API is organized around these controller groups.

Area	Representative Paths	Notes
Authentication	/login, /join, /forgot-password, /reset-password, /whoami, /logout	Login, invitation join, password reset, current-user lookup.
Users	/users, /users/{id}/permissions, /users/{id}/preferences, /user, /user/tokens	User administration and profile/token management.
Accounts	/accounts, /accounts/search, /accounts/{id}, /accounts/{id}/status, /accounts/{id}/notes, /accounts/{id}/logs	Account search, detail, notes, status changes, logs, callbacks, and duplicate handling.
Debtor Details	/accounts/{id}/debtor, /accounts/{id}/debtor/employer, /accounts/{id}/debtor/attorney, /accounts/{id}/debtor/payment-methods, /accounts/{id}/debtor/relatives	Debtor profile, legal, employer, payment method, and relative data.
Account Communications	/accounts/{id}/communication, /accounts/{id}/emails, /accounts/{id}/calls, /accounts/{id}/text-messages	Account-level communication history.
Account Documents	/accounts/{accountId}/documents	Upload and list account documents.
Account Fees	/accounts/{accountId}/fees, /accounts/{accountId}/fees/{feeId}	List, add, and remove account fees.
Payments	/payments, /payments/{id}, /payments/collector-summary, /payments/void, /payments/{id}/charge-back, /payments/plans	Payment search, posting, approval, chargebacks, voids, plans, and collector summary data.
Payment Admin	/payment-processors, /payments/portal	Processor setup and tenant payment portal settings.
Payment Portal	/portal/payment/find, /portal/payment/login, /portal/payment/pay, /portal/payment/contact	Public debtor payment portal endpoints.
Communications	/communications, /communications/preview, /communications/bulk, /communications/providers, /communications/call-dispositions	Email, SMS/MMS, calls, provider setup, previews, and approvals.
Templates	/templates, /templates/file, /templates/preview, /templates/{id}/download	Message and document templates.
Documents	/documents, /documents/file, /documents/{id}/view, /documents/{id}/download/original, /documents/{id}/download/signed, /documents/{id}/download/audit	Document upload, viewing, and signature-related downloads.
E-Signatures	/signatures, /signatures/{id}/logs, /signatures/providers	Signature requests, status logs, and DocuSeal provider setup.
Imports	/imports, /imports/file, /imports/{id}/status, /imports/{id}/test, /imports/{id}/import, /imports/{id}/skipped	Account import definitions, upload, testing, execution, resume/history support, and skipped rows.
Account Exports	/accounts/export/columns, /accounts/export/templates, /accounts/export/csv	Export column metadata, templates, and CSV generation.
Administration	/company, /company/stats, /clients, /clients/{id}/portfolios, /status, /fields, /triggers	Company profile, clients and portfolios, account statuses, custom fields, and automation triggers.
Dashboards	/dashboards, /dashboards/{id}	Embedded dashboard configuration.
Notifications	/notifications, /notifications/token, /notifications/unread-count, /notifications/mark-all-as-read	In-app notifications and notification websocket token support.
Jobs and Tenants	/jobs/{id}, /tenants, /tenants/jobs, /tenants/allow/{id}, /tenants/disallow/{id}	Background job status plus root-only tenant administration.
Subscription	/subscription	Current tenant subscription details for Billing.
Utilities	/feedback, /to-short	Feedback submission and short-link conversion.
Webhooks	/webhooks/eztexting, /webhooks/docuseal, /webhooks/ccai	External provider callbacks.

Many endpoints require object-level permissions in addition to authentication. Use the application UI and OpenAPI schema to confirm the exact request body, allowed transitions, and permission behavior for a workflow.

Request Conventions

Authenticated JSON requests usually include:

Content-Type: application/json
Accept: application/json

Browser requests also include the CSRF header when Spring's CSRF cookie is present:

X-XSRF-TOKEN: <value from XSRF-TOKEN cookie>

CSRF is ignored for login, transfer, payment portal routes, webhooks, import file upload routes, OAuth callbacks, bearer-token requests, and Chrome extension requests.

Errors

DebtRecoup uses normal HTTP statuses such as:

Status	Meaning
200 / 201	Request succeeded.
204	Delete succeeded with no response body.
400	Request validation failed.
401	Authentication is missing or invalid.
403	The user is authenticated but lacks permission.
404	The requested resource was not found.
500	Server error.

Error response bodies vary by endpoint and exception path. Do not assume a single global { success, data, error } envelope.

External Boundaries

Some workflows depend on external providers:

Boundary	API Surface
EZ Texting	Communication provider setup and /webhooks/eztexting.
DocuSeal	E-signature providers, signature requests, and /webhooks/docuseal.
Cloud Contact AI	Message provider delivery callbacks through /webhooks/ccai.
Slack	Notification provider OAuth under /api/v1/oauth/slack and /api/v1/oauth/callback/slack.
Embedded analytics	Dashboard routes load configured dashboard content rather than implementing report logic directly in the docs site.

Related Pages

• Account Tabs
• Payment Processing
• Fee Management
• E-Signatures
• Communication Providers
• Subscription Billing