Skip to main content

Quickstart

Onboard your first client and submit a test case in under 5 minutes.

Prerequisites​

All commands below use the test environment. See Environments for URLs.

Step 1: Create a client​

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

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
      }
    ]
  }'

Expected response: 202 Accepted​

{
  "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.

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:

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.

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.

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"
  }'
{
  "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.

Step 4: Submit a test case​

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

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.

Step 5: Verify attribution​

Check the case appears in your cross-client case list:

curl https://testreferral-api.debitura.com/cases \
  -H "XApiKey: YOUR_TEST_API_KEY"

You should see the case you just created. This endpoint (on the Referral Partner API, with your API key) shows cases across all your linked clients — useful for building partner dashboards.

What's Next​

You've completed the core flow: create client, onboard, mint token, submit case, verify attribution.

Build out your integration:

Clean up after testing: