Source: https://docs.debitura.com/referral-partners/getting-started/quickstart-onboard-first-client

# Full quickstart: onboard a client and submit a case

Onboard your first client and submit a test case in under 5 minutes, with the Full Integration. Building the Starter Integration? Use the [Starter quickstart](https://docs.debitura.com/referral-partners/getting-started/starter-quickstart.md) instead.

<a id="prerequisites"></a>

## Prerequisites

-   A test API key (see [Authentication](https://docs.debitura.com/referral-partners/getting-started/authentication.md)) — verify it works by calling `GET /me`
-   Familiarity with the [two-API architecture](https://docs.debitura.com/referral-partners/getting-started/how-it-works.md)

All commands below use the **test environment**. See [Environments](https://docs.debitura.com/referral-partners/getting-started/environments.md) for URLs.

<a id="step-1-create-a-client"></a>

## Step 1: Create a client

Call `POST /clients` on the Referral Partner API to create a creditor account linked to your partnership.

```bash
curl -X POST https://testreferral-api.debitura.com/clients \
  -H "Content-Type: application/json" \
  -H "XApiKey: YOUR_TEST_API_KEY" \
  -d '{
    "externalTenantId": "quickstart-test-001",
    "client": {
      "name": "Quickstart Test Company",
      "country": "GB",
      "supportEmail": "support@example.com"
    },
    "users": [
      {
        "email": "admin@example.com",
        "name": "Test User",
        "isOnboardingUser": true
      }
    ]
  }'
```

<a id="expected-response-202-accepted"></a>

### Expected response: `202 Accepted`

```json
{
  "externalTenantId": "quickstart-test-001",
  "onboardingDone": false,
  "isAttributedClient": true,
  "client": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "companyName": "Quickstart Test Company"
  },
  "onboardingLinks": {
    "url": "https://testreferral.debitura.com/onboarding/companydetails/abc123"
  }
}
```

A `202` means the client was created but needs to complete onboarding (sign the SDCA). In production, you'd redirect your user to `onboardingLinks.url`.

**For this quickstart:** open the URL in your browser and complete the signup flow manually.

<a id="step-2-wait-for-onboarding-completion"></a>

## Step 2: Wait for onboarding completion

After the user completes the SDCA signing, you'll receive a webhook event (if configured) or you can poll:

```bash
curl https://testreferral-api.debitura.com/clients/quickstart-test-001 \
  -H "XApiKey: YOUR_TEST_API_KEY"
```

Look for the `onboardingDone` field. Once it's `true`, the client can submit cases.

<a id="step-3-mint-a-bearer-token"></a>

## Step 3: Mint a bearer token

Generate a JWT token scoped to this client. You'll use this token with the **Customer API** to submit cases.

```bash
curl -X POST https://testreferral-api.debitura.com/oauth/token \
  -H "Content-Type: application/json" \
  -H "XApiKey: YOUR_TEST_API_KEY" \
  -d '{
    "externalTenantId": "quickstart-test-001"
  }'
```

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 1800,
  "externalTenantId": "quickstart-test-001",
  "creditorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

The token is valid for 30 minutes. Save the `accessToken` value.

<a id="step-4-submit-a-test-case"></a>

## Step 4: Submit a test case

Use the bearer token to call the **Customer API** (different base URL):

```bash
curl -X POST https://testcustomer-api.debitura.com/cases \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "isTest": true,
    "currencyCode": "EUR",
    "amountToRecover": 1500.00,
    "date": "2025-01-15",
    "dueDate": "2025-02-15",
    "claimDescription": "Quickstart test invoice",
    "debtor": {
      "type": "Company",
      "name": "Test Debtor GmbH",
      "contactPerson": "Jane Doe",
      "address": "Teststrasse 1",
      "city": "Berlin",
      "zipCode": "10115",
      "countryAlpha2": "DE",
      "email": "debtor@example.com"
    }
  }'
```

The case is automatically attributed to your partnership. Set `"isTest": true` to create a test case that won't trigger real collection activity.

This quickstart uses one amount for one invoice. Before mapping production claims, choose the right [claim amount and age mode](https://docs.debitura.com/developer-concepts/claim-amount-and-age.md).

<a id="step-5-verify-attribution"></a>

## Step 5: Verify the test case

Read the created case by its returned `id` using the same client bearer token on the Customer API:

```bash
curl https://testcustomer-api.debitura.com/cases/YOUR_CASE_ID \
  -H "Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN"
```

Check the reference, amount, currency, lifecycle and `isTestCase: true`. The Referral Partner API’s case list and detail exclude test/demo cases, so they can return an empty list or `404` for this case even when the Customer API readback succeeds. Use referral reporting for production cases; keep this quickstart on `isTest: true`.

<a id="whats-next"></a>

## What's Next

You've completed the core flow: create client, onboard, mint token, submit a test case and read it back.

**Build out your integration:**

-   [Client Onboarding](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding.md) — Handle all `POST /clients` response scenarios (201, 202, 409)
-   [Webhooks](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md) — Real-time events instead of polling
-   [Preview Pricing](https://docs.debitura.com/referral-partners/integration-guides/preview-case-pricing.md) — Show success fees before clients commit
-   [Revenue Tracking](https://docs.debitura.com/referral-partners/integration-guides/revenue-tracking.md) — Build earning dashboards

**Clean up after testing:**

-   [Reset Test Clients](https://docs.debitura.com/referral-partners/getting-started/environments.md#reset-test-clients) — Delete test data to re-run onboarding