Source: https://docs.debitura.com/referral-partners/getting-started/starter-quickstart

# Quickstart: your first collection request

Send one invoice for a new, fictional client in test, open the link Debitura returns, then read the request back. This is the whole Starter Integration loop.

**Use this when:** you're building the [Starter Integration](https://docs.debitura.com/referral-partners.md#two-ways-to-integrate). **You'll need:** a test `XApiKey` (see [Get started](https://docs.debitura.com/referral-partners/getting-started.md)) and `curl`.

<a id="step-1-send-the-invoice"></a>

## Step 1: Send the invoice

Choose your own identifiers: `externalTenantId` is your ID for the client, and `creditorReference` is the invoice number. The `Idempotency-Key` makes a retry safe.

```bash
curl -X POST https://testreferral-api.debitura.com/collection-requests \
  -H "XApiKey: $DEBITURA_TEST_KEY" \
  -H "Idempotency-Key: quickstart-inv-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "externalTenantId": "quickstart-client-1",
    "client": {
      "name": "Quickstart Client Ltd",
      "country": "GB",
      "supportEmail": "you@your-company.example"
    },
    "user": {
      "name": "Quickstart User",
      "email": "you@your-company.example"
    },
    "invoices": [{
      "creditorReference": "QS-INV-0001",
      "debtor": {
        "type": "Company",
        "name": "Example Debtor Ltd",
        "countryAlpha2": "GB",
        "address": "10 Example Street",
        "city": "London"
      },
      "amountToRecover": 1500.00,
      "currencyCode": "GBP",
      "date": "2026-06-01T00:00:00Z",
      "dueDate": "2026-06-30T00:00:00Z",
      "isTest": true
    }]
  }'
```

The client is new, so Debitura creates it and answers `202 Accepted`. Onboarding comes next:

```json
{
  "id": "33333333-3333-4333-8333-000000000042",
  "status": "awaiting_onboarding",
  "solutionType": "onboarding",
  "solutionUrl": "https://testreferral.debitura.com/Onboarding/CompanyDetails/55555555-5555-4555-8555-555555555555",
  "externalTenantId": "quickstart-client-1",
  "invoices": [{ "creditorReference": "QS-INV-0001", "status": "waiting" }]
}
```

Store the `id`. In your product, this is the moment the button opens `solutionUrl`.

<a id="step-2-open-the-solutionurl"></a>

## Step 2: Open the solutionUrl

Open `solutionUrl` in a browser and complete onboarding as your client would, on Debitura's pages with your branding.

Signing asks for a verification code sent by email. Test emails only reach domains Debitura has whitelisted for you, so use an email address on such a domain. Alternatively, ask your partnership contact for a demo-flagged test partner; there, the code is always `123456`.

<a id="step-3-read-the-request-back"></a>

## Step 3: Read the request back

```bash
curl https://testreferral-api.debitura.com/collection-requests/33333333-3333-4333-8333-000000000042 \
  -H "XApiKey: $DEBITURA_TEST_KEY"
```

When nothing is left for the client to do, the request is `submitted` and the invoice has a case:

```json
{
  "id": "33333333-3333-4333-8333-000000000042",
  "status": "submitted",
  "solutionType": "case",
  "solutionUrl": "https://…  (the client's case page)",
  "invoices": [{ "creditorReference": "QS-INV-0001", "status": "created", "caseId": "…" }]
}
```

If the status is still `awaiting_…` (another agreement, or KYC for this debtor's country), the response carries a new `solutionUrl`. Open it and read again. That loop is your integration.

<a id="what-you-built"></a>

## What you built

One request, one link and one read. In production, a button replaces the curl, and the [`collection_request.updated` webhook](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md#collection_requestupdated) replaces the manual read.

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

## What's next

-   [Build the collection button](https://docs.debitura.com/referral-partners/integration-guides/starter-integration.md): every status, retries, failures and webhooks
-   [Who does what](https://docs.debitura.com/referral-partners/concepts/responsibility-matrix.md): what Debitura handles for you on Starter
-   [Go live](https://docs.debitura.com/referral-partners/going-live-checklist.md): the Starter checklist