Source: https://docs.debitura.com/api/referral-partner-api/collection-requests

# Collection requests — Referral Partner API

Base URL: `https://referral-api.debitura.com`

Authentication: `XApiKey` API key; see [authentication](https://docs.debitura.com/developer-concepts/authentication.md).

Generated from [OpenAPI](https://docs.debitura.com/openapi/referral-partner-api.json). Examples are schema illustrations, not observed responses. Complete schemas, including recursive types, are in OpenAPI.

<a id="get-collection-requests"></a>

## GET /collection-requests

`GET /collection-requests`

### Query parameters

- `externalTenantId` (string): 
- `creditorReference` (string): 

### Response 200

OK

- `id` (uuid): 
- `status` (enum): 
  Values: `awaiting_onboarding`, `awaiting_approval`, `awaiting_signature`, `awaiting_kyc`, `needs_fixing`, `submitted`, `rejected`, `expired`, `processing`.
- `solutionUrl` (string, nullable): 
- `solutionType` (enum, nullable): Next action: onboarding, approval, sdca (initial/fallback SDCA), sdca_update, power_of_attorney, jurisdiction_pricing_appendix, kyc, fix or case. Null when no action is available. Status remains awaiting_signature for agreement work. The legacy signature value can appear only in an immutable keyed replay snapshot.
  Values: `onboarding`, `approval`, `sdca`, `sdca_update`, `power_of_attorney`, `jurisdiction_pricing_appendix`, `kyc`, `fix`, `case`, `signature`.
- `externalTenantId` (string, nullable): 
- `client` (object): 
- `client.debituraClientId` (uuid, nullable): 
- `client.isNew` (boolean): 
- `client.isAttributedClient` (boolean): 
- `invoices` (array of objects, nullable): 
- `invoices[].creditorReference` (string, nullable): 
- `invoices[].status` (enum): 
  Values: `waiting`, `draft`, `created`, `rejected`.
- `invoices[].caseId` (uuid, nullable): 
- `invoices[].draftId` (uuid, nullable): 
- `invoices[].caseStatus` (string, nullable): 
- `invoices[].reason` (string, nullable): 
- `invoices[].issues` (array of objects, nullable): 
- `invoices[].issues[].field` (string, nullable): 
- `invoices[].issues[].type` (string, nullable): 
- `invoices[].issues[].message` (string, nullable): 
- `createdAt` (datetime): 
- `updatedAt` (datetime): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "status": "awaiting_onboarding",
  "solutionUrl": "https://app.debitura.com/…",
  "solutionType": "onboarding",
  "externalTenantId": "string",
  "client": {
    "debituraClientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "isNew": true,
    "isAttributedClient": true
  },
  "invoices": [
    {
      "creditorReference": "INV-2026-0042",
      "status": "waiting",
      "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "draftId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "caseStatus": "string",
      "reason": null,
      "issues": [
        {
          "field": {},
          "type": {},
          "message": {}
        }
      ]
    }
  ],
  "createdAt": "2026-10-01T14:05:00Z",
  "updatedAt": "2026-10-01T14:05:00Z"
}
```

<a id="submit-one-invoice-for-collection"></a>

## Submit one invoice for collection

`POST /collection-requests`

Available only when Starter Integration is enabled. Send exactly one invoice in the invoices array. Return navigation uses the referral partner configuration; no per-request returnUrl is supported. Client details are used only on creation; existing clients approve a new connection. solutionUrl points to the first outstanding action: onboarding, approval, signature, KYC, fixing drafts, then the case. Resubmitting a client invoice reference returns its existing case within the same data classification.

### Headers

- `Idempotency-Key` (string): 
  Max 200 characters.

### Request body (application/json)

- `externalTenantId` (string, nullable): 
- `client` (object): 
- `client.name` (string, nullable): 
- `client.registrationNumber` (string, nullable): 
- `client.address` (string, nullable): 
- `client.zipCode` (string, nullable): 
- `client.city` (string, nullable): 
- `client.state` (string, nullable): 
- `client.country` (string, nullable): 
- `client.supportEmail` (string, nullable): 
- `client.supportPhone` (string, nullable): 
- `user` (object): 
- `user.name` (string, nullable): 
- `user.email` (string, nullable): 
- `invoices` (array of objects, nullable): 
- `invoices[].currencyCode` (string, nullable): 
- `invoices[].date` (datetime, nullable): 
- `invoices[].dueDate` (datetime, nullable): 
- `invoices[].comments` (string, nullable): 
- `invoices[].claimDescription` (string, nullable): 
- `invoices[].creditorReference` (string, nullable): 
- `invoices[].debtor` (object): 
- `invoices[].debtor.type` (string, nullable): 
- `invoices[].debtor.name` (string, nullable): 
- `invoices[].debtor.contactPerson` (string, nullable): 
- `invoices[].debtor.companyRegistrationNumber` (string, nullable): 
- `invoices[].debtor.address` (string, nullable): 
- `invoices[].debtor.zipCode` (string, nullable): 
- `invoices[].debtor.city` (string, nullable): 
- `invoices[].debtor.state` (string, nullable): 
- `invoices[].debtor.stateAlpha2` (string, nullable): 
- `invoices[].debtor.countryAlpha2` (string, nullable): 
- `invoices[].debtor.country` (string, nullable): 
- `invoices[].debtor.email` (string, nullable): 
- `invoices[].debtor.phone` (string, nullable): 
- `invoices[].creditorDivisionId` (uuid, nullable): 
- `invoices[].amountToRecover` (number, nullable): 
- `invoices[].amountToRecoverOver6Months` (number, nullable): 
- `invoices[].amountToRecoverOver12Months` (number, nullable): 
- `invoices[].amountToRecoverOver24Months` (number, nullable): 
- `invoices[].claimLines` (array of objects, nullable): A single unpaid invoice belonging to the claim.
Claim lines are a pricing input only: they are used to derive the claim total and the
cumulative age buckets, and are then discarded. They are not stored and are never shown
to the collecting partner — put a per-invoice breakdown in Comments if the partner needs one.
- `invoices[].claimLines[].dueDate` (datetime, required, nullable): Payment deadline of this invoice. Provide date only without time component.
Must be on or after 2000-01-01 and must not be in the future.
- `invoices[].claimLines[].amount` (number, required): The outstanding balance on this invoice in the case currency — what the debtor still owes on it,
already net of any payments the debtor has made and net of any credit notes issued against it.
This is not the invoice's original face value.
Must be greater than zero with at most 2 decimal places; omit invoices that are fully settled.
- `invoices[].claimLines[].reference` (string, nullable): Optional: your own invoice number for this line. Used only to make validation errors readable
and to reject the same invoice being sent twice. It is not stored and not shown to anyone.
- `invoices[].isTest` (boolean): 
- `invoices[].tag` (string, nullable): 

```json
{}
```

### Response 201

Created

- `id` (uuid): 
- `status` (enum): 
  Values: `awaiting_onboarding`, `awaiting_approval`, `awaiting_signature`, `awaiting_kyc`, `needs_fixing`, `submitted`, `rejected`, `expired`, `processing`.
- `solutionUrl` (string, nullable): 
- `solutionType` (enum, nullable): Next action: onboarding, approval, sdca (initial/fallback SDCA), sdca_update, power_of_attorney, jurisdiction_pricing_appendix, kyc, fix or case. Null when no action is available. Status remains awaiting_signature for agreement work. The legacy signature value can appear only in an immutable keyed replay snapshot.
  Values: `onboarding`, `approval`, `sdca`, `sdca_update`, `power_of_attorney`, `jurisdiction_pricing_appendix`, `kyc`, `fix`, `case`, `signature`.
- `externalTenantId` (string, nullable): 
- `client` (object): 
- `client.debituraClientId` (uuid, nullable): 
- `client.isNew` (boolean): 
- `client.isAttributedClient` (boolean): 
- `invoices` (array of objects, nullable): 
- `invoices[].creditorReference` (string, nullable): 
- `invoices[].status` (enum): 
  Values: `waiting`, `draft`, `created`, `rejected`.
- `invoices[].caseId` (uuid, nullable): 
- `invoices[].draftId` (uuid, nullable): 
- `invoices[].caseStatus` (string, nullable): 
- `invoices[].reason` (string, nullable): 
- `invoices[].issues` (array of objects, nullable): 
- `invoices[].issues[].field` (string, nullable): 
- `invoices[].issues[].type` (string, nullable): 
- `invoices[].issues[].message` (string, nullable): 
- `createdAt` (datetime): 
- `updatedAt` (datetime): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "status": "awaiting_onboarding",
  "solutionUrl": "https://app.debitura.com/…",
  "solutionType": "onboarding",
  "externalTenantId": "string",
  "client": {
    "debituraClientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "isNew": true,
    "isAttributedClient": true
  },
  "invoices": [
    {
      "creditorReference": "INV-2026-0042",
      "status": "waiting",
      "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "draftId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "caseStatus": "string",
      "reason": null,
      "issues": [
        {
          "field": {},
          "type": {},
          "message": {}
        }
      ]
    }
  ],
  "createdAt": "2026-10-01T14:05:00Z",
  "updatedAt": "2026-10-01T14:05:00Z"
}
```

### Response 202

Accepted

- `id` (uuid): 
- `status` (enum): 
  Values: `awaiting_onboarding`, `awaiting_approval`, `awaiting_signature`, `awaiting_kyc`, `needs_fixing`, `submitted`, `rejected`, `expired`, `processing`.
- `solutionUrl` (string, nullable): 
- `solutionType` (enum, nullable): Next action: onboarding, approval, sdca (initial/fallback SDCA), sdca_update, power_of_attorney, jurisdiction_pricing_appendix, kyc, fix or case. Null when no action is available. Status remains awaiting_signature for agreement work. The legacy signature value can appear only in an immutable keyed replay snapshot.
  Values: `onboarding`, `approval`, `sdca`, `sdca_update`, `power_of_attorney`, `jurisdiction_pricing_appendix`, `kyc`, `fix`, `case`, `signature`.
- `externalTenantId` (string, nullable): 
- `client` (object): 
- `client.debituraClientId` (uuid, nullable): 
- `client.isNew` (boolean): 
- `client.isAttributedClient` (boolean): 
- `invoices` (array of objects, nullable): 
- `invoices[].creditorReference` (string, nullable): 
- `invoices[].status` (enum): 
  Values: `waiting`, `draft`, `created`, `rejected`.
- `invoices[].caseId` (uuid, nullable): 
- `invoices[].draftId` (uuid, nullable): 
- `invoices[].caseStatus` (string, nullable): 
- `invoices[].reason` (string, nullable): 
- `invoices[].issues` (array of objects, nullable): 
- `invoices[].issues[].field` (string, nullable): 
- `invoices[].issues[].type` (string, nullable): 
- `invoices[].issues[].message` (string, nullable): 
- `createdAt` (datetime): 
- `updatedAt` (datetime): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "status": "awaiting_onboarding",
  "solutionUrl": "https://app.debitura.com/…",
  "solutionType": "onboarding",
  "externalTenantId": "string",
  "client": {
    "debituraClientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "isNew": true,
    "isAttributedClient": true
  },
  "invoices": [
    {
      "creditorReference": "INV-2026-0042",
      "status": "waiting",
      "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "draftId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "caseStatus": "string",
      "reason": null,
      "issues": [
        {
          "field": {},
          "type": {},
          "message": {}
        }
      ]
    }
  ],
  "createdAt": "2026-10-01T14:05:00Z",
  "updatedAt": "2026-10-01T14:05:00Z"
}
```

### Response 422

Unprocessable Content

- `id` (uuid): 
- `status` (enum): 
  Values: `awaiting_onboarding`, `awaiting_approval`, `awaiting_signature`, `awaiting_kyc`, `needs_fixing`, `submitted`, `rejected`, `expired`, `processing`.
- `solutionUrl` (string, nullable): 
- `solutionType` (enum, nullable): Next action: onboarding, approval, sdca (initial/fallback SDCA), sdca_update, power_of_attorney, jurisdiction_pricing_appendix, kyc, fix or case. Null when no action is available. Status remains awaiting_signature for agreement work. The legacy signature value can appear only in an immutable keyed replay snapshot.
  Values: `onboarding`, `approval`, `sdca`, `sdca_update`, `power_of_attorney`, `jurisdiction_pricing_appendix`, `kyc`, `fix`, `case`, `signature`.
- `externalTenantId` (string, nullable): 
- `client` (object): 
- `client.debituraClientId` (uuid, nullable): 
- `client.isNew` (boolean): 
- `client.isAttributedClient` (boolean): 
- `invoices` (array of objects, nullable): 
- `invoices[].creditorReference` (string, nullable): 
- `invoices[].status` (enum): 
  Values: `waiting`, `draft`, `created`, `rejected`.
- `invoices[].caseId` (uuid, nullable): 
- `invoices[].draftId` (uuid, nullable): 
- `invoices[].caseStatus` (string, nullable): 
- `invoices[].reason` (string, nullable): 
- `invoices[].issues` (array of objects, nullable): 
- `invoices[].issues[].field` (string, nullable): 
- `invoices[].issues[].type` (string, nullable): 
- `invoices[].issues[].message` (string, nullable): 
- `createdAt` (datetime): 
- `updatedAt` (datetime): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "status": "awaiting_onboarding",
  "solutionUrl": "https://app.debitura.com/…",
  "solutionType": "onboarding",
  "externalTenantId": "string",
  "client": {
    "debituraClientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "isNew": true,
    "isAttributedClient": true
  },
  "invoices": [
    {
      "creditorReference": "INV-2026-0042",
      "status": "waiting",
      "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "draftId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "caseStatus": "string",
      "reason": null,
      "issues": [
        {
          "field": {},
          "type": {},
          "message": {}
        }
      ]
    }
  ],
  "createdAt": "2026-10-01T14:05:00Z",
  "updatedAt": "2026-10-01T14:05:00Z"
}
```

<a id="get-collection-requests-id"></a>

## GET /collection-requests/{id}

`GET /collection-requests/{id}`

### Path parameters

- `id` (uuid, required): 

### Response 200

OK

- `id` (uuid): 
- `status` (enum): 
  Values: `awaiting_onboarding`, `awaiting_approval`, `awaiting_signature`, `awaiting_kyc`, `needs_fixing`, `submitted`, `rejected`, `expired`, `processing`.
- `solutionUrl` (string, nullable): 
- `solutionType` (enum, nullable): Next action: onboarding, approval, sdca (initial/fallback SDCA), sdca_update, power_of_attorney, jurisdiction_pricing_appendix, kyc, fix or case. Null when no action is available. Status remains awaiting_signature for agreement work. The legacy signature value can appear only in an immutable keyed replay snapshot.
  Values: `onboarding`, `approval`, `sdca`, `sdca_update`, `power_of_attorney`, `jurisdiction_pricing_appendix`, `kyc`, `fix`, `case`, `signature`.
- `externalTenantId` (string, nullable): 
- `client` (object): 
- `client.debituraClientId` (uuid, nullable): 
- `client.isNew` (boolean): 
- `client.isAttributedClient` (boolean): 
- `invoices` (array of objects, nullable): 
- `invoices[].creditorReference` (string, nullable): 
- `invoices[].status` (enum): 
  Values: `waiting`, `draft`, `created`, `rejected`.
- `invoices[].caseId` (uuid, nullable): 
- `invoices[].draftId` (uuid, nullable): 
- `invoices[].caseStatus` (string, nullable): 
- `invoices[].reason` (string, nullable): 
- `invoices[].issues` (array of objects, nullable): 
- `invoices[].issues[].field` (string, nullable): 
- `invoices[].issues[].type` (string, nullable): 
- `invoices[].issues[].message` (string, nullable): 
- `createdAt` (datetime): 
- `updatedAt` (datetime): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "status": "awaiting_onboarding",
  "solutionUrl": "https://app.debitura.com/…",
  "solutionType": "onboarding",
  "externalTenantId": "string",
  "client": {
    "debituraClientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "isNew": true,
    "isAttributedClient": true
  },
  "invoices": [
    {
      "creditorReference": "INV-2026-0042",
      "status": "waiting",
      "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "draftId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
      "caseStatus": "string",
      "reason": null,
      "issues": [
        {
          "field": {},
          "type": {},
          "message": {}
        }
      ]
    }
  ],
  "createdAt": "2026-10-01T14:05:00Z",
  "updatedAt": "2026-10-01T14:05:00Z"
}
```