Source: https://docs.debitura.com/referral-partners/getting-started/how-it-works

# How the Full Integration works

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

**Use this when:** you want collection inside your own screens, with your own onboarding and status views. **You'll build:** client onboarding, token handling, case submission and webhooks. Want Debitura to handle setup instead? Use the [Starter Integration](https://docs.debitura.com/referral-partners/integration-guides/starter-integration.md); you can add the endpoints on this page to a Starter client later.

<a id="two-apis-one-integration"></a>

## 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.

<a id="the-flow"></a>

## 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 |

<a id="step-by-step"></a>

### 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.
    

<a id="what-goes-where"></a>

## 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` |

<a id="key-concepts-to-know"></a>

## 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](https://docs.debitura.com/referral-partners/concepts/attribution.md).
-   **Idempotency** — `POST /clients` is idempotent on `externalTenantId`. Calling it again returns the existing client status, not a duplicate, and creates no cases. Submit later cases through the Customer API.

Set up your [API key and token model](https://docs.debitura.com/referral-partners/getting-started/authentication.md), then review [test vs production URLs](https://docs.debitura.com/referral-partners/getting-started/environments.md). When you're ready, the [Full quickstart](https://docs.debitura.com/referral-partners/getting-started/quickstart-onboard-first-client.md) walks through the flow end-to-end in 15 minutes.