How It Works

The referral partner integration uses two APIs working together. Understanding this architecture before you start coding prevents the most common integration mistakes.

Two APIs, One Integration

API	Purpose	Authentication	Base URL (test)
Referral Partner API	Client onboarding, revenue tracking, webhooks	XApiKey header	testreferral-api.debitura.com
Customer API	Case submission and management	Bearer token	testcustomer-api.debitura.com

Why two APIs? The Customer API is shared with direct clients (creditors who use Debitura without a referral partner). As a referral partner, you submit cases through the same API they use — but with bearer tokens that automatically attribute revenue to your partnership.

The Flow

Step	You call	On which API	What happens
1	POST /clients	Referral Partner	Create a creditor account, get onboarding URL
2	(user signs SDCA in browser)		Client completes onboarding
3	POST /oauth/token	Referral Partner	Get a 30-min bearer token for this client
4	POST /cases	Customer (bearer token)	Submit a case — revenue attributed automatically
5	GET /cases	Referral Partner	List all cases across all your clients

Step by step

1. Onboard a client — Call POST /clients on the Referral Partner API with your API key. This creates a creditor account in Debitura and links it to your partnership.

2. User completes onboarding — If the client needs to sign the Standard Debt Collection Agreement (SDCA), redirect them to the onboarding URL returned in the response. You'll receive a client.onboarding.contract_signed webhook when they're done.

3. Mint a bearer token — Call POST /oauth/token on the Referral Partner API with the client's externalTenantId. This returns a 30-minute JWT scoped to that client.

4. Submit cases via Customer API — Use the bearer token to call POST /cases on the Customer API. The token tells Debitura which client is submitting the case and that you referred them — revenue attribution is automatic.

5. Track across all clients — Use the Referral Partner API's GET /cases endpoint (with your API key, not a bearer token) to see cases across all your linked clients in a single call. Use GET /reporting/transactions for revenue data.

What goes where

I want to...	Use this API	Endpoint
Onboard a new client	Referral Partner	POST /clients
Check if a client is ready	Referral Partner	GET /clients/{externalTenantId}
Get a bearer token	Referral Partner	POST /oauth/token
Submit a case	Customer	POST /cases (with bearer token)
Track a specific case	Customer	GET /cases/{id} (with bearer token)
List ALL cases across clients	Referral Partner	GET /cases (with API key)
Track revenue	Referral Partner	GET /reporting/transactions
Set up webhooks	Referral Partner	POST /v1/Webhooks
Preview pricing	Referral Partner	POST /cases/preview

Key concepts to know

• externalTenantId — Your internal identifier for a client. You choose this value. Debitura uses it to correlate your client with a creditor account. All future operations reference this ID.
• Attribution — When you mint a bearer token and submit a case, the revenue is automatically attributed to your partnership. See Attribution.
• Idempotency — POST /clients is idempotent on externalTenantId. Calling it again returns the existing client status, not a duplicate.

What's Next

• Authentication — Set up your API key and understand the token model
• Environments — Test vs production URLs
• Quickstart — Try it end-to-end in 15 minutes