# Authentication
Source: https://creditor-documentation.debbiecollect.com/api-reference/authentication
Authenticate using bearer token
Authentication with an API key can be done by using a bearer token in the Authorization header. This is done using the following format `Authorization: Bearer {token}`.
```header theme={null}
Authorization: Bearer {token}
```
API keys are issued and revoked directly from the creditor portal. Go to the Developer section in the menu, click API, name the API key and select the scopes it needs. The key is only shown once, when it is created.
On the same page you will find the `tenantId` and `creditorId` used in the API calls.
## Scopes
Every endpoint requires a scope, and a key only reaches the endpoints its scopes cover. A scope is an access level and an area joined by a colon:
```
read:customers
write:case-vouchers
```
The access level follows the HTTP method — `GET` requires `read`, and every other method requires `write`. The area is named on each endpoint under **Required scope**.
Grant a key the narrowest set that covers what it does.
### Scopes available to a creditor key
A key issued from the creditor portal can hold these scopes, and no others:
| Area | Scopes |
| ------------------ | -------------------------------------------------------------------------------- |
| Customers | `read:customers`, `write:customers` |
| Cases | `read:cases`, `write:cases` |
| Case vouchers | `read:case-vouchers`, `write:case-vouchers` |
| Voucher types | `read:voucher-types` |
| Ultimate creditors | `read:ultimate-creditors` |
| Files | `write:files` |
| Documents | `write:documents` |
| Billings | `read:billings` |
| Interactions | `write:interactions.create` |
| Webhooks | `read:webhooks`, `write:webhooks` |
| Insights | `read:insights.cases`, `read:insights.case-vouchers` and the other insight areas |
Registering a direct payment is a case voucher write, so it needs
`write:case-vouchers` rather than a scope of its own.
A key is always bound to one creditor, and the endpoints in this reference only ever reach that creditor's data — its customers, its cases and its settlements.
### Sub-areas
Some areas have a sub-area, written with a dot:
```
write:interactions.create
```
**A scope grants exactly what it names.** `write:interactions` does not grant `write:interactions.create`, and `write:interactions.create` does not grant `write:interactions`. If a key needs both, give it both.
### When a scope is missing
A request made with a key that lacks the required scope is rejected with `401 Unauthorized`:
```json theme={null}
{
"statusCode": 401,
"error": "Unauthorized",
"message": "You do not have permission to access this resource",
"requestId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
```
The scopes on an existing key can be changed under Developers → API in the creditor portal without reissuing it.
# Get billing vouchers
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/billings/billing-vouchers
GET /v1/{tenantId}/billings/{billingId}/billing-vouchers
The fees (honorarer) and disbursements (udlæg) you are charged on a settlement — what you pay, next to what you are paid.
Only the fees that stand on their own are returned. A fee charged on a specific payment is part of that payment's distribution and is reported by [Get deposit distribution](/api-reference/endpoints/billings/deposit-distribution) as `collectionCommission` instead, so the two can be booked together without counting anything twice.
Together they are the whole settlement: without this endpoint, only half of the account is posted.
**Required scope:** `read:billings`
# Get deposit distribution
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/billings/deposit-distribution
GET /v1/{tenantId}/billings/{billingId}/deposit-distribution
How each payment in a settlement was split — what went to your debt collection partner, and what is yours. Every entry carries `source`, which tells you whether you already have the posting in your own books (`CREDITOR`) or whether your debt collection partner added it (`COLLECTOR`).
The fees and disbursements charged on the settlement are reported by [Get billing vouchers](/api-reference/endpoints/billings/billing-vouchers); the two do not overlap.
**Required scope:** `read:billings`
# Register case voucher allocation
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/case-vouchers/allocations
POST /v1/{tenantId}/case-vouchers/allocations
Register a payment made directly to the creditor or a credit note against a list of existing case vouchers. Set `voucherTypeId` to deposit or credit note; other types are currently rejected. All created vouchers use source `CREDITOR`.
Each item in `matches` supplies a positive `amount` in minor units and exactly one of `caseVoucherId` and `caseVoucherReferenceId`. References must be unambiguous within the supplied `creditorId`. A target may appear only once, including when supplied by ID and reference in different items. Each amount must fit within the target's remaining fixed-distribution capacity. All targets must have the same currency.
Matches are grouped by case. One allocation voucher is created per case with the sum of that case's match amounts, and one fixed distribution per target on both accounts, using the allocation voucher date. No fixed distribution crosses cases. The response is an array of the created allocation vouchers and their `targetCaseVouchers`, including each `matchedAmount`.
**Required scope:** `write:case-vouchers`
# Add case vouchers
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/customers/add-case-vouchers
POST /v1/{tenantId}/customers/{customerId}/add-case-vouchers
Add new case vouchers (e.g. unpaid invoices, reminder fees or deposits) to a customer. Based on the vouchers, the platform automatically determines whether to create a new case or add the vouchers to an existing case.
**Required scope:** `write:customers`
# Create customer
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/customers/create
POST /v1/{tenantId}/customers
Create a new customer under your creditor. A customer represents your end-customer relationship and holds the contact details of the debtor.
**Required scope:** `write:customers`
# Get customer by id
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/customers/get
GET /v1/{tenantId}/customers/{customerId}
Get a customer by customer id, including the users and cases related to the customer.
**Required scope:** `read:customers`
# Get customer by reference id
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/customers/get-by-reference
GET /v1/{tenantId}/customers/by-reference-id/{referenceId}
Get a customer by your own reference id, including the users and cases related to the customer.
**Required scope:** `read:customers`
# Add document
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/documents/create
POST /v1/{tenantId}/documents
Attach a document to one of your cases, or to your creditor. Upload the file first with [Upload file](/api-reference/endpoints/files/create) and pass the object it returns as `file`.
Set `type` to `OTHER`. The other document types decide whether a debt has a legal foundation and when it expires, and are set by your debt collection partner as the case progresses.
Consider whether the debtor should be able to see the document. `minAccessRole: "debtor"` shows it in the debtor self-service portal, which is what you want for an invoice copy, a contract or a photo that documents the claim. Leave it out to keep the document between you and your debt collection partner.
**Required scope:** `write:documents`
# Upload file
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/files/create
POST /v1/{tenantId}/files
Upload a file. The returned file id can be used as an appendix on a case voucher, for example a pdf copy of an invoice.
**Required scope:** `write:files`
# Get file
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/files/get
GET /v1/{tenantId}/files/{fileId}/{fileName}
Download a file by file id.
**Required scope:** `read:files`
`read:files` is not currently among the scopes a creditor API key can be issued with, so this endpoint cannot be called with a creditor key. Files you upload are referenced by id on case vouchers and do not need to be read back.
# Get voucher types
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/voucher-types/get
GET /v1/{tenantId}/voucher-types
Get the voucher types available on your debt collection partner, sorted by their order. Fetch the list once and cache it rather than hard-coding the ids — it also covers the types your partner has defined themselves, which are not on the [Voucher types](/api-reference/voucher-types) page.
**Required scope:** `read:voucher-types`
# Create webhook
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/webhooks/create
POST /v1/{tenantId}/webhooks
Creates a webhook for the events it is subscribed to. By default, deliveries are POSTed to the URL. Set pull=true to hold deliveries for polling through the webhook items endpoints. The response carries the verification token sent with every POST delivery.
**Required scope:** `write:webhooks`
# Delete webhook
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/webhooks/delete
DELETE /v1/{tenantId}/webhooks/{webhookId}
Deletes a webhook. It stops receiving events immediately; deliveries already made are kept.
**Required scope:** `write:webhooks`
# Get webhook
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/webhooks/get
GET /v1/{tenantId}/webhooks/{webhookId}
Gets a single webhook.
**Required scope:** `read:webhooks`
# Get webhook items
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/webhooks/get-items
GET /v1/{tenantId}/webhooks/items
Lists webhook items for the creditor the API key is issued for. Use state=PENDING to fetch unprocessed items, optionally limited to one webhook with webhookId. For polling, create the webhook with pull=true and mark each item SUCCESS after processing it. Fetch page 0 again after acknowledging a batch: acknowledged items leave the PENDING results, so increasing the page would skip items.
**Required scope:** `read:webhooks`
# Get webhooks
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/webhooks/get-list
GET /v1/{tenantId}/webhooks
Lists the webhooks that are receiving events, paginated. Stop paging when a page comes back with fewer items than pageSize. A key only ever sees the webhooks of the creditor it is issued for.
**Required scope:** `read:webhooks`
# Patch webhook item
Source: https://creditor-documentation.debbiecollect.com/api-reference/endpoints/webhooks/patch-item
PATCH /v1/{tenantId}/webhooks/items/{itemId}
Updates the state of a webhook item belonging to the creditor the API key is issued for. After successfully processing a pending item, send {"state":"SUCCESS"} to acknowledge it. The item will no longer appear when filtering by state=PENDING.
**Required scope:** `write:webhooks`
# Idempotency
Source: https://creditor-documentation.debbiecollect.com/api-reference/idempotency
Ensuring safe retries with Idempotency Keys
The Debbie API supports idempotency for non-idempotent requests through the optional `Idempotency-Key` header. This ensures that retrying the same request multiple times will produce the same result, preventing duplicate operations.
## Using Idempotency Keys
* Include an Idempotency-Key header with a unique string (we recommend UUIDs)
* Maximum key length is 64 characters
* Keys are valid for 48 hours
* Responses served from the idempotency cache include an Idempotency-Cached header
## Example
```header theme={null}
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
```
## Error Cases
* Invalid key format: 400 Bad Request
* Reusing a key for a different request: 400 Bad Request
## Best practices
* Use a new key for each unique business transaction
* Use the same key when retrying a failed request
* Store keys with request details for debugging
# Introduction
Source: https://creditor-documentation.debbiecollect.com/api-reference/introduction
Welcome to the Debbie Creditor API
The Debbie Creditor API is a RESTful interface allowing you, as a creditor, to programmatically send data to your debt collection partner and access your data in the platform. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to integrate with your own systems.
For questions about your account, cases or the collection process, please contact your debt collection partner.
For technical questions about the API, e-mail: [api-support@debbie.dk](mailto:api-support@debbie.dk)
# Pagination
Source: https://creditor-documentation.debbiecollect.com/api-reference/pagination
How list endpoints paginate results
List endpoints in the Debbie API are paginated with the `page` and `pageSize` query parameters.
## Parameters
* `page` — the page to get, starting from `0`. Defaults to `0`.
* `pageSize` — the number of items per page. Each endpoint documents its default and maximum page size.
## Response format
Paginated endpoints return the items of the requested page together with a `meta` object:
```json theme={null}
{
"meta": {
"currentPage": 0,
"pageSize": 250
},
"items": [{ "...": "..." }]
}
```
## Iterating through all pages
The response does not include a total count. To fetch all items, keep requesting the next page until a page contains fewer items than `pageSize`:
```
GET /v1/{tenantId}/{resource}?page=0&pageSize=250
GET /v1/{tenantId}/{resource}?page=1&pageSize=250
...
```
When `items.length < pageSize`, you have reached the last page.
## Best practices
* Use a fixed `pageSize` for all requests in an iteration — changing it between pages will skip or repeat items
* Requesting a page beyond the last one returns an empty `items` array
# Voucher types
Source: https://creditor-documentation.debbiecollect.com/api-reference/voucher-types
Ids for the built-in voucher types
Every case voucher has a voucher type, referenced by the `voucherTypeId` field. The built-in voucher types are listed below.
### Principals
| Type | Id |
| ---------------------------------- | -------------------------------------- |
| Invoice (Faktura) | `eb41e58e-fccf-419d-a771-cd5027fe6e87` |
| Credit note (Kreditnota) | `ef2cdc50-230f-4046-b1af-0f9c498dddd3` |
| Final statement (Opgørelse) | `42385ae0-6846-425c-a793-8d47a3b190b5` |
| On account invoice (Acontofaktura) | `2d101b6e-74f9-4a4d-9f8e-c7abe2264da0` |
| Loan (Gældsbrev) | `bf61f462-6d3c-42e8-a99a-852d4a664926` |
### Costs
| Type | Id |
| -------------------------------------- | -------------------------------------- |
| Collection cost (Inkassoomkostning) | `07960de4-303d-4793-92da-3a8cfd5da1a1` |
| Collection fee (Inkassogebyr) | `4c3ccbbf-0651-45b2-b37b-4fe736acfd7e` |
| Reminder fee (Rykkergebyr) | `3e51bf87-3c8f-4dd5-abd5-69417d113c89` |
| Compensation cost (Kompensationsgebyr) | `ed3e3d61-e1bc-4ee2-9166-adf2c41a2bbf` |
### Interests
| Type | Id |
| ----------------------------- | -------------------------------------- |
| DK interest (Procesrente) | `ca4af363-9925-436c-83d6-23b3db6ed5d2` |
| Fixed interest (Fastrente) | `299dc393-1b71-4950-860f-8fb485036722` |
| Yearly interest (Årlig rente) | `37db68dd-80be-40c7-8d2d-3619c793107f` |
### Transactions
| Type | Id |
| --------------------- | -------------------------------------- |
| Deposit (Indbetaling) | `c51f2f6a-8081-45ef-b52d-5e0569fdf12e` |
Your debt collection partner may also have defined custom voucher types, which
are not listed here. [Get voucher
types](/api-reference/endpoints/voucher-types/get) returns every type
available on their tenant, including their own — fetch it once and cache it
rather than hard-coding the ids above.
# Billing created
Source: https://creditor-documentation.debbiecollect.com/api-reference/webhooks/billings.create
webhook billings.create
Notifies when a billing has been created. A creditor webhook only receives events for the creditor it was created for.
# Case created
Source: https://creditor-documentation.debbiecollect.com/api-reference/webhooks/cases.create
webhook cases.create
Notifies when a case is created. A creditor webhook only receives events for the creditor it was created for.
# Case deleted
Source: https://creditor-documentation.debbiecollect.com/api-reference/webhooks/cases.delete
webhook cases.delete
Notifies when a case is deleted. A creditor webhook only receives events for the creditor it was created for.
# Case updated
Source: https://creditor-documentation.debbiecollect.com/api-reference/webhooks/cases.update
webhook cases.update
Notifies when a case is patched. Only the changed fields are sent. A creditor webhook only receives events for the creditor it was created for.
# Webhooks
Source: https://creditor-documentation.debbiecollect.com/api-reference/webhooks/introduction
Receive events through webhook deliveries or poll pending items
The endpoints in this reference let you push data into the platform and read it
back. Webhooks are the other direction: Debbie calls an endpoint of yours when
something happens on one of your cases, so your system does not have to poll
for it. You can also create a pull webhook and poll its pending items.
## Setting one up
Add a webhook in the creditor portal under *Developers → Webhooks*, or with
[Create webhook](/api-reference/endpoints/webhooks/create). You give it a URL
and the list of events you want.
A webhook you create is bound to your creditor and **only ever receives events
for your own cases** — there is nothing to filter on your side.
## Delivery
By default, every delivery is a `POST` with a JSON body of the shape:
```json theme={null}
{
"event": "billings.create",
"time": "2026-06-04T09:12:44.021Z",
"data": { "...": "..." }
}
```
* Debbie sends an `X-Verification-Token` header with the token issued when the
webhook was created. **Verify it on every request** before acting on the
payload.
* Any non-2xx response counts as a failure. The first delivery is attempted
immediately; a failure is then retried up to 7 more times with exponential
backoff — roughly 1, 3, 8, 21, 55, 149 and 404 minutes after the previous
attempt, about eleven hours end to end.
* Respond quickly and process asynchronously. Acknowledge with 200 as soon as
the payload is persisted rather than after your own downstream work has
finished.
* Retries mean a delivery can arrive more than once with an unchanged body, so
make the handler idempotent. Key it on the identifiers the event carries:
`billingId` for `billings.create`, and `caseId` — together with `status` — for
`cases.*`.
## Polling webhook items
For an integration that polls for events, use
[Create webhook](/api-reference/endpoints/webhooks/create) with `pull: true`,
your `creditorId` and the events you need. A public HTTP(S) `url` is still
required when creating the webhook, but pull webhooks hold items in `PENDING`
without POSTing them to that URL.
Your API key needs `read:webhooks` to fetch items and `write:webhooks` to
acknowledge them. Both operations are restricted to your creditor's webhooks.
1. [Get webhook items](/api-reference/endpoints/webhooks/get-items) with
`state=PENDING`. Add `webhookId` to poll a specific webhook:
```bash theme={null}
curl --get "https://api.debbiecollect.com/v1/{tenantId}/webhooks/items" \
-H "Authorization: Bearer {token}" \
--data-urlencode "state=PENDING" \
--data-urlencode "webhookId={webhookId}" \
--data-urlencode "page=0" \
--data-urlencode "pageSize=25"
```
The response contains an `items` array and pagination `meta`. Each item has
an `id`, `hookId`, `event`, `data` and `state`. Process the event payload in
`item.data`.
2. After successfully processing an item,
[Patch webhook item](/api-reference/endpoints/webhooks/patch-item) using
that item's `id` and `{"state":"SUCCESS"}`:
```bash theme={null}
curl --request PATCH \
"https://api.debbiecollect.com/v1/{tenantId}/webhooks/items/{itemId}" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
--data '{"state":"SUCCESS"}'
```
A successful update returns `200` with `{}`. The item no longer appears
when filtering by `state=PENDING`.
3. Fetch page `0` again after acknowledging the batch. Acknowledged items
leave the pending results, so increasing the page number would skip items.
Once no pending items remain, wait before polling again.
Keep processing idempotent using the webhook item's `id`: if processing
succeeds but acknowledgment fails, the item will appear again on the next
poll. Leave an item pending if processing fails, so it can be retried.
## Events
| Event | Why you want it |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| [`cases.create`](/api-reference/webhooks/cases.create) | A case was opened for you |
| [`cases.update`](/api-reference/webhooks/cases.update) | A case changed, including status transitions and the reason a case ended |
| [`cases.delete`](/api-reference/webhooks/cases.delete) | A case was deleted |
| [`billings.create`](/api-reference/webhooks/billings.create) | A settlement was created — fetch what it is made up of, see the [Settlements](/guides/settlements) guide |
These four are the only events a creditor webhook can subscribe to today.
There is no event for a payment landing on a case. Payments reach your books
through the settlement — `billings.create` and the two endpoints in the
[Settlements](/guides/settlements) guide — and the creditor portal shows them
as they come in. If being notified per payment matters to your integration,
tell your debt collection partner.
# Core concepts
Source: https://creditor-documentation.debbiecollect.com/core-concepts
Understand the core concepts in the Creditor API
## Concepts
### Creditors
A creditor is the company or private individual to whom money is owed — that is you. All data you create and read through this API belongs to your creditor. Your `creditorId` is shown on the API page in the creditor portal.
### Customers
Represents your end-customer relationship. A customer has a reference id, which can be the customer number, client id, membership number, patient id, or another identifier from your own system. Each customer can have one or more users attached — typically the debtor, and optionally alternative contacts.
### Cases
A case represents a specific debt or matter associated with a customer. Each customer can have multiple cases. A case is always linked to a customer and includes a list of case vouchers, which represent the amount owed. A case moves through the statuses `PENDING`, `VERIFIED` and `ENDED`. When a case is ended, an end reason describes why — for example `PAID`.
You do not create cases directly. You only create the customer and add case
vouchers to the customer. The platform automatically determines when to create
a new case or update an existing one.
### Case vouchers
A case voucher is a financial entry linked to a specific case, representing an amount that is either owed or credited. Case vouchers are used to define the financial components of a case and can include various types of entries such as invoices, credit notes, reminder fees and deposits.
Each case voucher includes key information such as the amount, currency, source, date, and a reference id (e.g. an invoice number). Amounts are in the base currency unit: 1.00 should be sent as 100. A negative amount (e.g. -100) represents a debt, while a positive amount (e.g. +100) represents a credit note or deposit.
The type of a voucher is defined by its voucher type. See the [Voucher types](/api-reference/voucher-types) page for the list of ids.
### Documents
A document is a file attached to a case or to your creditor — an invoice copy, a
contract, a photo that proves the claim. Attaching them means your debt
collection partner does not have to ask for them, and a document can optionally
be made visible to the debtor in the self-service portal.
Documents also carry legal meaning in the collection process: a signed
acknowledgement of debt or a court verdict is what gives a claim a *foundation*
and decides when it expires. Those types are set by your debt collection partner
as the case progresses; the documents you attach are of type `OTHER`.
### Attributes and case groups
*Attributes* — properties in the API — are your own fields on a case or a case
voucher, such as a meter number or a contract id. *Case groups* segment your
portfolio into product lines, business units or brands, and decide how your debt
collection partner treats and reports on the cases in them. Both are set up in
the platform by your partner, who gives you the handles and ids to send.
### Billings
A billing is a settlement between you and your debt collection partner: how the
money collected on your cases was split, and what you are charged for the work.
It is the record you post in your own books when the money comes back. See the
[Settlements](/guides/settlements) guide.
# Getting started
Source: https://creditor-documentation.debbiecollect.com/getting-started
Get started using the Creditor API
Welcome! This guide will help you quickly get up and running with the Debbie Creditor API.
## 1. Get access to the creditor portal
Your debt collection partner will invite you to the creditor portal. If you do not have access yet, please reach out to them.
## 2. Create an API key
In the creditor portal, navigate to the Developer section in the menu. From there, you can create a new API key and select the scopes it should have access to.
The API key is only shown once, when it is created. Store it in a safe place.
On the same page you will find your `tenantId` and `creditorId`. You will need both when calling the API — the `tenantId` is part of every URL, and the `creditorId` identifies you as the creditor.
## 3. Understand the core concepts
Before diving into the endpoints, we recommend reading the Core Concepts section to familiarize yourself with how customers, cases and case vouchers fit together.
## 4. Build your integration
The smallest useful integration is two endpoints:
1. [Create customer](/api-reference/endpoints/customers/create) — create the customer with the debtor's contact details.
2. [Add case vouchers](/api-reference/endpoints/customers/add-case-vouchers) — send the unpaid invoices and fees for collection.
The platform automatically determines when to create a new case or update an existing one.
## 5. Subscribe to webhooks
You can be notified when data changes instead of polling. Add a webhook with the events you want — cases, payments and billings are available — either in the creditor portal under Developers → Webhooks, or with [Create webhook](/api-reference/endpoints/webhooks/create). A webhook only receives events for your own creditor.
Every delivery carries an `X-Verification-Token` header with the token issued when the webhook was created. Compare it with the stored value and reject requests that do not match. See the [Webhooks reference](/api-reference/webhooks/introduction) for delivery behaviour and the payloads.
## 6. Build the rest of the flow
A full integration also attaches documentation, reports the payments the debtor
makes directly to you, and posts the settlement when the money comes back. The
[Invoice-to-cash integration](/guides/invoice-to-cash) guide walks through all of
it in order.
The end-to-end guide: what to send, what to store on each side, and how to
post what comes back.
# Invoice-to-cash integration
Source: https://creditor-documentation.debbiecollect.com/guides/invoice-to-cash
Hand unpaid invoices to your debt collection partner, and get the money and the bookkeeping back
This guide describes how to connect the system that issues your invoices — your
ERP, billing or subscription system — to your debt collection partner, so that
an unpaid invoice becomes a collection case without anyone retyping it, and the
money comes back with enough detail to be posted.
The integration is small. Four endpoints push data in, and one webhook plus two
endpoints bring the settlement back:
The debtor, with the contact details the collector will write to.
The unpaid invoices, and any reminder and compensation fees you have already
charged.
Invoice copies, contracts, photos — whatever proves the claim.
Money the debtor pays straight to you after handover.
What you are paid, and what you are charged.
## Before you start
1. **Get access to the creditor portal.** Your debt collection partner invites
you. If you do not have access yet, reach out to them.
2. **Create an API key.** In the portal, go to *Developers → API*, name the key
and grant it the scopes listed under [Scopes](#scopes). Authenticate with
`Authorization: Bearer {token}` — see
[Authentication](/api-reference/authentication).
3. **Note your ids.** The same page shows your `tenantId` — your debt collection
partner's tenant, which is part of every URL — and your `creditorId`, which
identifies you.
4. **Ask for the configuration ids you need.** The case group you should send
cases under, the handles of any custom attributes, and the id of any custom
voucher type. These are set up in the platform by your partner.
5. **Add a webhook.** Under *Developers → Webhooks* in the portal, or with
[Create webhook](/api-reference/endpoints/webhooks/create). It only ever
receives events for your own cases. See
[Webhooks](/api-reference/webhooks/introduction).
Make every write retryable. Every write endpoint accepts an `Idempotency-Key`
header, and case vouchers additionally take a `uniqueId` that is unique per
tenant — so a request that is replayed from a queue cannot create the same
invoice or the same payment twice.
## Identifiers to store on both sides
Getting the identifier mapping right is the most important part of the
integration. Decide up front which id lives where, and persist it.
| Store in your own system | Where it comes from | Used for |
| ------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `customerId` | `POST /customers` response `customerId` | Adding case vouchers for that debtor |
| `caseId` | `POST /customers/{customerId}/add-case-vouchers` response `caseId` | Attaching documents to the case |
| `caseVoucherId` | The same response, `caseVoucherId` | Recognising a payment you pushed yourself when it comes back on a webhook |
| Store in Debbie | Field | Used for |
| -------------------- | --------------------------------- | ------------------------------------------------------- |
| Your customer number | `referenceId` on the customer | Settlement — every payment is reported back under it |
| Your invoice number | `referenceId` on the case voucher | Registering direct payments, and posting the settlement |
`customer.referenceId` is the identifier your settlement is keyed on. It must
be the customer number from the system you post the money back into — not a
number invented for the integration. Get it wrong and the money arrives
without anything to match it to.
## 1. Create your customer
A *customer* is your relationship with the party that owes the money. It holds
one or more *users*: the people involved. Exactly one of them is the debtor.
```json POST /v1/{tenantId}/customers?creditorId={creditorId} theme={null}
{
"isCompany": false,
"referenceId": "CUST-40218",
"users": [
{
"relation": "debtor",
"contact": true,
"lang": "da",
"details": {
"name": "Mette Jensen",
"cpr": "0101801234",
"email": "mette@example.com",
"phone": { "locale": "45", "number": "12345678" },
"address": {
"address": "Søndergade 5, 2. th",
"zipcode": "8000",
"city": "Aarhus C",
"country": "DK"
}
}
}
]
}
```
* **One user must be the debtor.** `relation: "debtor"` is the party the claim
is against, and the one the debt is registered on. Anyone else on the matter —
a guardian, an administrator, a contact at a company — is
`relation: "alternative-contact"`.
* `contact: true` marks the user Debbie addresses its letters, emails and texts
to.
* `isCompany` says whether the customer is a business or a private individual.
Send `cvr` on the user for a company and `cpr` for a person.
* **`referenceId` is your customer number** — the one in the system you keep
your books in. It is what the settlement refers to, so it has to match. It
only needs to be unique within your creditor, which is why
`GET /customers/by-reference-id/{referenceId}?creditorId={creditorId}` finds
the customer again instead of you keeping a mapping table.
The response gives you the `customerId`. Store it.
See [POST Create customer](/api-reference/endpoints/customers/create) for full
details.
## 2. Add the case vouchers for collection
A *case voucher* is one financial entry on the claim. Send the unpaid invoice,
plus any reminder fees and compensation fees you have already charged, in one
request. Debbie decides itself whether that opens a new case or extends an
existing one for the same debtor.
```json POST /v1/{tenantId}/customers/{customerId}/add-case-vouchers theme={null}
{
"caseVouchers": [
{
"voucherTypeId": "eb41e58e-fccf-419d-a771-cd5027fe6e87",
"referenceId": "D12412347",
"uniqueId": "D12412347",
"amount": -450000,
"currency": "DKK",
"date": "2026-05-02",
"dueDate": "2026-05-16",
"text": "Invoice 2026-05",
"properties": { "meterNumber": "874113" }
},
{
"voucherTypeId": "3e51bf87-3c8f-4dd5-abd5-69417d113c89",
"referenceId": "D12412347-R1",
"uniqueId": "D12412347-R1",
"amount": -10000,
"currency": "DKK",
"date": "2026-06-01"
},
{
"voucherTypeId": "ed3e3d61-e1bc-4ee2-9166-adf2c41a2bbf",
"referenceId": "D12412347-K1",
"uniqueId": "D12412347-K1",
"amount": -31000,
"currency": "DKK",
"date": "2026-06-01"
}
],
"constraints": {
"caseGroupId": "0b1a0f3c-6c1d-4b8f-9b6b-6f6a1f2e7a10"
}
}
```
### Voucher types
`voucherTypeId` says what the entry is. These are the ones an invoice-to-cash
integration normally sends:
| What you are sending | `voucherTypeId` |
| ------------------------------------- | -------------------------------------- |
| Invoice (faktura) | `eb41e58e-fccf-419d-a771-cd5027fe6e87` |
| Credit note (kreditnota) | `ef2cdc50-230f-4046-b1af-0f9c498dddd3` |
| Reminder fee (rykkergebyr) | `3e51bf87-3c8f-4dd5-abd5-69417d113c89` |
| Compensation fee (kompensationsgebyr) | `ed3e3d61-e1bc-4ee2-9166-adf2c41a2bbf` |
The full list, including subscription and loan types, is on the
[Voucher types](/api-reference/voucher-types) page, and [Get voucher
types](/api-reference/endpoints/voucher-types/get) returns the same list at
runtime including any types your debt collection partner has defined
themselves. Fetch it once and cache it rather than hard-coding the ids.
### Amounts, references and duplicates
* **Amounts are integers in the minor unit, and debt is negative.** `-450000` is
a debt of 4,500.00 DKK. A positive amount is a credit note or a payment.
* **`referenceId` is your invoice number.** It is what you will refer to when
you register a direct payment, and what the settlement reports back, so send
the number your own system knows.
* **`uniqueId` stops duplicates.** It is unique across the whole tenant, so a
replayed request is rejected rather than creating the invoice twice. Setting
it to the invoice number is usually right.
### You do not send `source`
Everything you send through this API is imposed by you, and is registered with
`source: "CREDITOR"` whatever the field says. Leave it out.
This matters most for payments. A deposit registered with `source:
"COLLECTOR"` reads as money your debt collection partner received on your
behalf — the opposite of a payment made to you — and the settlement comes out
backwards. Because the source is decided by the key you are calling with, you
cannot get this wrong; do not try to set it.
### Attributes and case groups
Two mechanisms carry your own structure into the collection process:
* **Attributes (properties)** are custom fields on a case or a case voucher — a
meter number, a contract id, a subscription plan. Your debt collection partner
defines the property types in the platform and gives you the *handle* to use
as the key: `"properties": { "meterNumber": "874113" }`. Attributes can be
printed in the letters to the debtor and reported on, so anything the
collector or the debtor needs to recognise the claim belongs here.
* **Case groups** segment your portfolio — a product line, a business unit, a
brand. Pass `constraints.caseGroupId` and the case is opened in that group,
which decides how the collector treats and reports on it. The id comes from
your partner. `constraints` only applies when the vouchers open a *new* case;
it is ignored when they land on an existing one.
The response gives you one entry per voucher, each with the `caseId` it landed
on and the `caseVoucherId` it was created as. **Store the `caseId`** — you need
it for the next step.
```json theme={null}
[
{
"merged": false,
"caseId": "3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"caseVoucherId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
]
```
See [POST Add case
vouchers](/api-reference/endpoints/customers/add-case-vouchers) for full
details.
## 3. Attach the documentation
A claim that is documented is a claim that survives an objection. Attach the
invoice copy, the contract, the delivery note, the photo — whatever your
partner would otherwise have to ask you for.
Documents are attached in two calls: upload the file, then create the document
that points at it.
### Upload the file
```json POST /v1/{tenantId}/files theme={null}
{
"name": "invoice-D12412347.pdf",
"contentType": "application/pdf",
"content": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ..."
}
```
`content` is the file, base64 encoded. The response is the stored file:
```json theme={null}
{
"id": "8d9f0c1e-2b3a-4c5d-6e7f-8a9b0c1d2e3f",
"fileName": "invoice-D12412347.pdf",
"contentType": "application/pdf"
}
```
The upload calls the identifier `id`; everywhere it is referenced afterwards —
on a document, and as the `appendix` of a case voucher — the field is called
`fileId`. It is the same value. On a document only the id is read: the name
and content type are taken from the stored file.
### Create the document
```json POST /v1/{tenantId}/documents theme={null}
{
"entityId": "3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"entityType": "case",
"type": "OTHER",
"minAccessRole": "debtor",
"file": {
"fileId": "8d9f0c1e-2b3a-4c5d-6e7f-8a9b0c1d2e3f",
"fileName": "invoice-D12412347.pdf",
"contentType": "application/pdf"
}
}
```
* **`entityId` and `entityType`** say what the document belongs to. `case` with
the `caseId` you got back in step 2 is what you want for invoice copies and
anything else about a specific claim. `creditor` with your own `creditorId`
is for documents about the relationship itself — a power of attorney, a
standing agreement — and they are not tied to a case.
* **`type` is always `OTHER`.** The other document types — foundation, verdict,
settlement — decide whether a debt has a legal foundation and when it expires,
and are set by your debt collection partner as the case progresses through the
courts.
* **`minAccessRole` decides who can see it.** Consider setting it to `debtor`:
the document then shows up in the debtor's self-service portal, so someone
disputing an invoice can see the invoice. Leave it out and the document stays
between you and your collection partner.
See [POST Add document](/api-reference/endpoints/documents/create) for full
details.
## 4. Register direct payments and credit notes
Once a case is handed over, the debtor may still pay you rather than your debt
collection partner — into your own bank account, or through your own portal.
Those payments have to reach Debbie, or the collection process keeps chasing
money that has already arrived, and the settlement is wrong.
```json POST /v1/{tenantId}/case-vouchers/allocations?creditorId={creditorId} theme={null}
{
"voucherTypeId": "c51f2f6a-8081-45ef-b52d-5e0569fdf12e",
"matches": [
{ "caseVoucherReferenceId": "D12412347", "amount": 100000 },
{ "caseVoucherReferenceId": "D12412348", "amount": 20000 },
{ "caseVoucherId": "d341b682-c7b2-48b4-9152-17c3b4085089", "amount": 30000 }
],
"date": "2026-06-04",
"currency": "DKK"
}
```
* **Each match identifies an invoice.** Use `caseVoucherReferenceId` for the
`referenceId` you sent the invoice under, or `caseVoucherId` for Debbie's id.
Give exactly one per match. References must identify exactly one case voucher
within your creditor. You can mix the two identifier types in the list, but
the same target must not appear twice.
* **Amounts belong to the matches.** Each positive `amount` is in minor units
and cannot exceed the target's remaining fixed-distribution capacity.
Earlier payments and credit notes matched against it count. There is no
separate total amount on the request.
* **One payment voucher is created per case.** The two invoices in one case
share a payment voucher with their combined amount. An invoice on another
case gets a separate payment voucher. Each fixed distribution stays within
its case. The response is an array of the created vouchers and their
`targetCaseVouchers`, including each `matchedAmount`.
* **All targets must use the same currency.** Optional `currency` asserts that
currency; when omitted it is taken from the first target. No conversion is
performed.
* **Send one `Idempotency-Key` for the whole request.** Retry the same request
with the same key within 48 hours to get the original result. The operation
is atomic: if any match fails, none of the payment vouchers are created.
* **`source` is not a field here either.** A direct payment is by definition
money that never passed through your collection partner, and is always
registered as `CREDITOR`.
### Credit notes
Use the same endpoint with `voucherTypeId` set to
`ef2cdc50-230f-4046-b1af-0f9c498dddd3` to register a credit note. Send a positive
amount for each entry in `matches` and its issue date in `date`. One credit-note
voucher is created per case, with fixed distributions to the matched invoices
on that case. Its amount is the sum of that case's match amounts.
Only deposits and credit notes are currently supported.
### When the allocation is refused
Every refusal carries a `message` that says why. These are the ones to handle:
| Status | `message` | What it means |
| ------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 404 | `No case voucher found with id …` / `No case voucher found with reference id …` | The voucher does not exist within your creditor, has been deleted, or has not been handed over as part of a case yet. |
| 400 | `Reference id … matches more than one case voucher, …` | Two of your invoices share that reference id. Send `caseVoucherId` instead. |
| 400 | `Allocation is in … but case voucher … is in …` | All matched invoices must use the same currency, and optional `currency` must agree. Split different currencies into separate requests. |
| 400 | `Case voucher … is expired and can no longer be settled` | The claim has expired in Debbie. Contact your collection partner. |
| 400 | `Case voucher … is not a debt` | You referenced a payment or a credit note rather than an invoice or a fee. |
| 400 | `Amount … exceeds the … still outstanding on case voucher …` | The amount exceeds the remaining capacity after payments and credit notes already matched against the invoice. |
| 400 | `Each case voucher may only appear once in matches` | The same target occurs more than once, possibly by both ID and reference. |
| 422 | `Give exactly one of caseVoucherId and caseVoucherReferenceId`, or a field error | The body is invalid: `matches` is empty or missing, a match has both or neither identifier, an amount is not a positive integer, or an ID is not a UUID. |
A `400` or `404` will not succeed on retry with the same body; put those aside
for review rather than back on the queue.
See [POST Register case voucher
allocation](/api-reference/endpoints/case-vouchers/allocations) for full
details.
## 5. Book the settlement
When your debt collection partner settles with you, a settlement is created and
`billings.create` fires with a `billingId`. That is the trigger to fetch what
the settlement is made of — the payments and how they were split, and the fees
and disbursements you are charged — and post it.
Settlement has enough detail of its own that it has a separate guide. See
[Settlements](/guides/settlements).
## What happens in between
Between handover and settlement, the collection process is your partner's. Three
webhooks tell you what is going on without you having to ask:
| Event | What it tells you |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`cases.create`](/api-reference/webhooks/cases.create) | A case was opened for you — including the ones your debt collection partner opens without you, from an import or by hand. |
| [`cases.update`](/api-reference/webhooks/cases.update) | The case changed. A status transition carries the new status, and an ended case carries the reason — paid, written off, withdrawn — which is usually what closes the claim in your own system. |
| [`cases.delete`](/api-reference/webhooks/cases.delete) | A case was deleted. |
| [`billings.create`](/api-reference/webhooks/billings.create) | A settlement was created. See [step 5](#5-book-the-settlement). |
There is no per-payment event today: money reaching a case is accounted for in
the settlement, and visible in the creditor portal meanwhile. `billings.create`
is the one your integration has to handle.
Subscribe to them under *Developers → Webhooks* in the portal or with
[Create webhook](/api-reference/endpoints/webhooks/create); a webhook of yours
only ever carries your own creditor's events.
Do not rebuild the case balance in your own system. Interest accrues on rules
agreed with your collection partner, fees follow the collection workflow, and
expiry is recalculated as the case moves. A copy would need all of that logic
to stay correct and would drift the moment it did not. The balance lives in
Debbie — the creditor portal shows it, and `GET /customers/{customerId}` gives
you the cases and their statuses. Book money in your own system, not entries:
the payments, and the settlement.
## Scopes
Grant the API key only what the integration uses:
| Scope | Needed for |
| ------------------------------------------- | -------------------------------------------------------------- |
| `read:customers`, `write:customers` | Steps 1 and 2 |
| `read:case-vouchers`, `write:case-vouchers` | Steps 2 and 4 |
| `write:files` | Step 3, uploading the file |
| `write:documents` | Step 3, attaching it |
| `read:billings` | Step 5, reading the settlement |
| `read:webhooks`, `write:webhooks` | Managing your webhooks over the API instead of in the portal |
| `read:voucher-types` | Resolving `voucherTypeId` at runtime instead of hard-coding it |
## Checklist before going live
`customer.referenceId` is the customer number from the system that receives
the settlement, and `caseVoucher.referenceId` is your invoice number.
`Idempotency-Key` on every request, `uniqueId` on every voucher, and failed
calls go to a retry queue rather than being dropped.
`customerId`, `caseId` and the `caseVoucherId` of every voucher you created
are persisted in your own system.
Invoice copies and contracts are uploaded and attached to the case, and it
is decided per document type whether the debtor should be able to see it.
Payments into your own account are registered against the invoice they
settle, keyed on the bank transaction id.
`X-Verification-Token` is checked, `creditorId` is checked against your own,
the handler tolerates duplicate deliveries, and it responds 200 before doing
downstream work.
`billings.create` triggers a fetch of both the deposit distribution and the
billing vouchers, and the payout, the commission, the fees and the
disbursements are all posted. See [Settlements](/guides/settlements).
# Settlements
Source: https://creditor-documentation.debbiecollect.com/guides/settlements
Post a settlement: what you are paid, what you are charged, and what is already in your books
A settlement — a *billing* in the API — is the periodic account between you and
your debt collection partner. It says how the money collected on your cases was
split, and what you are charged for the work. It ends either in a payout to you
or in an amount you owe.
Posting one correctly means fetching **both** halves of it. The payments and how
they were split are one endpoint; the fees and disbursements are another. Take
only the first and the account is half posted.
This guide covers billing settlements between creditor and collector.
[Register case voucher
allocation](/api-reference/endpoints/case-vouchers/allocations) records a
creditor payment or credit note against one or more case vouchers. Its
response lists the created vouchers, one per case, rather than a billing to
post.
## The flow
Debbie calls your webhook endpoint with a `billingId`.
`GET /billings/{billingId}/deposit-distribution` — every payment in the
settlement, and how each was split between you and your collection partner.
`GET /billings/{billingId}/billing-vouchers` — the fees (honorarer) and
disbursements (udlæg) you are charged.
Revenue, commission, fees, disbursements, overpayments and the net amount.
## 1. The webhook
```json theme={null}
{
"event": "billings.create",
"time": "2026-07-01T02:15:03.221Z",
"data": {
"billingId": "9c1f2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
"id": 40218,
"date": "2026-06-30T22:00:00.000Z",
"billingAppendixId": "869cd519-beb7-4c8c-a854-760df763daad",
"creditorId": "a7fcf07c-74f2-40d9-8ea6-e67b07b14ca4",
"currency": "DKK"
}
}
```
Verify the `X-Verification-Token` header, acknowledge with 200, and do the
fetching asynchronously. A webhook of yours only ever carries your own
creditor's events. See [Webhooks](/api-reference/webhooks/introduction) for
delivery and retry behaviour, and
[Create webhook](/api-reference/endpoints/webhooks/create) to subscribe.
If you would rather not run a webhook receiver at all, the settlement is also
in the creditor portal, and the `billingId` is all these endpoints need.
## 2. The deposit distribution
```
GET /v1/{tenantId}/billings/{billingId}/deposit-distribution
```
One entry per payment in the settlement. Each says which case and customer the
payment belongs to, which entries it was distributed across, how much of it was
an overpayment, and which of the distributed amounts your collection partner
charges commission on.
```json theme={null}
{
"meta": { "currentPage": 0, "pageSize": 25 },
"items": [
{
"currency": "DKK",
"isAdjustment": false,
"depositCaseVoucher": {
"caseVoucherId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"id": 118067630,
"amount": 250000,
"source": "COLLECTOR",
"state": "PARTIAL_PAYMENT",
"paymentType": "BANK_TRANSFER",
"transactionAccountId": "6f2a1c8e-9b0d-4e3f-8a71-2c4d5e6f7a8b"
},
"customer": { "referenceId": "CUST-40218" },
"case": {
"caseId": "3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"id": 10427,
"groupId": "0b1a0f3c-6c1d-4b8f-9b6b-6f6a1f2e7a10",
"groupLabel": "Consumer"
},
"caseVouchers": [
{
"caseVoucherId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"referenceId": "D12412347",
"voucherTypeId": "eb41e58e-fccf-419d-a771-cd5027fe6e87",
"amount": 200000,
"source": "CREDITOR",
"collectionCommission": true
},
{
"caseVoucherId": "2d3e4f50-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
"referenceId": null,
"voucherTypeId": "4c3ccbbf-0651-45b2-b37b-4fe736acfd7e",
"amount": 50000,
"source": "COLLECTOR",
"collectionCommission": false
}
],
"overpayment": 0
}
]
}
```
### Reading it
* **`customer.referenceId` is your customer number** and
**`caseVouchers[].referenceId` is your invoice number** — the values you sent
in. This is what makes the settlement postable: each amount lands on the
invoice it paid.
* **`depositCaseVoucher.amount` is the payment.** `caseVouchers` is what it was
distributed to, and those amounts plus `overpayment` add up to it.
* **`overpayment`** is the part that exceeded the debt. It is owed back to the
debtor, not to you, and needs its own account.
### `source` is what tells you what is already in your books
Every entry carries `source`:
* **`CREDITOR`** — you imposed it. The invoice, the reminder fee, the
compensation fee you sent at handover, and the direct payments and credit
notes you registered yourself. **You already have these postings**, so a
distribution to them is money against a receivable you already carry.
* **`COLLECTOR`** — your debt collection partner imposed it. Collection fees,
court fees, interest calculated during collection. These do not exist in your
system until this settlement puts them there.
Do not assume the two sides line up. A `CREDITOR` entry can be settled by a
payment the collector received, and a `COLLECTOR` entry can be settled by a
payment you received yourself — the source of the payment and the source of
what it paid are independent. Read `depositCaseVoucher.source` for who
received the money and `caseVouchers[].source` for who imposed what it paid,
and post them separately. Treating one as a proxy for the other is the usual
way a settlement fails to reconcile.
### Registering payments and credit notes
Register payments received directly by you and credit notes through
[Register case voucher
allocation](/api-reference/endpoints/case-vouchers/allocations). Both
create one voucher with source `CREDITOR` per matched case and apply its amount
to the specified case vouchers through fixed distributions on that case.
Set `voucherTypeId` to select the entry:
| Entry | `voucherTypeId` |
| ----------- | -------------------------------------- |
| Payment | `c51f2f6a-8081-45ef-b52d-5e0569fdf12e` |
| Credit note | `ef2cdc50-230f-4046-b1af-0f9c498dddd3` |
Supply a `matches` array. Each match contains a positive `amount` in minor
units and exactly one of `caseVoucherId` or `caseVoucherReferenceId`, looked
up within `creditorId`. The identifiers can be mixed in the same request.
Partial amounts are supported, up to each target's remaining fixed-distribution
capacity. Each target may appear only once, and all targets must use the same
currency.
Debbie groups the matches by case, sums their amounts, and creates one payment
or credit note per case. Its fixed distributions only point to vouchers on
that same case. The response is an array containing each new `caseVoucherId`,
its `voucherTypeId`, and its `targetCaseVouchers` with the `matchedAmount` for
each target.
Send one `Idempotency-Key` for the entire request. All matches are registered
in one transaction: if any match fails, no payment or credit note is created.
A credit note reduces the invoice balance without recording cash received.
You already have that credit note in your own books; do not post its amount
again as a payment or as money paid out by your collection partner. The billing
endpoints describe the resulting billing and its charges, rather than a
complete list of the credit notes you registered.
Registering either type requires `write:case-vouchers`.
### Direct payments in the billing
By default the payments you registered yourself are **not** in the distribution,
and the commission charged on them shows up as a separate fee among the billing
vouchers instead. Add `?includeDepositsWithSourceCreditor=true` to have them
reported here, with their commission as part of the distribution.
The billing vouchers endpoint always reports that commission, whatever you
pass here. So if you take both halves of the settlement — which is what this
guide recommends — leave the parameter off. Turning it on and also reading the
billing vouchers counts the commission on your direct payments twice.
### Paging
The response is `items` plus `meta`, 25 payments per page by default. Page with
`page` and `pageSize` until a page returns fewer items than `pageSize`; there is
no total count. See [Pagination](/api-reference/pagination).
See [GET Get deposit
distribution](/api-reference/endpoints/billings/deposit-distribution) for full
details.
## 3. The billing vouchers
```
GET /v1/{tenantId}/billings/{billingId}/billing-vouchers
```
The other half: the fees and disbursements on the settlement.
Only the ones that stand on their own are returned. A fee charged on a specific
payment belongs to that payment's distribution and is reported there as
`collectionCommission`, so booking both endpoints counts nothing twice — and
misses nothing.
```json theme={null}
{
"meta": { "currentPage": 0, "pageSize": 25 },
"items": [
{
"billingVoucherId": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
"id": 8841,
"billingId": "9c1f2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
"label": "Retsafgift",
"category": "disbursement",
"voucherTypeId": "6991fa7e-5812-4948-be69-0001d1f7205f",
"amount": 75000,
"currency": "DKK",
"caseId": "3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"caseSequentialId": 10427,
"referenceId": null,
"text": null,
"createdAt": "2026-06-14T09:02:11.000Z",
"caseVoucher": null,
"depositCaseVoucher": null
}
]
}
```
* **`category`** is either `fee` — your collection partner's own charge, a
honorar — or `disbursement`, an outlay they paid on your behalf, an udlæg.
They are usually posted to different accounts, and can be fetched separately
with `?category=["fee"]` or `?category=["disbursement"]` (JSON encoded, as on
Debbie's other list filters). Both are returned when it is omitted.
* **`amount` excludes VAT**, and `vat` carries the VAT charged on the entry.
* **`label`** is what the line is called, in the language of the settlement.
* **`caseId` and `caseSequentialId`** tie the charge to a case where there is
one; a charge that is not case specific has them null.
* **`depositCaseVoucher`** is the payment that triggered the charge, where there
is one. **Commission on a direct payment you registered yourself appears
here**, with `depositCaseVoucher.source` set to `CREDITOR` — that is where it
goes when you did not pass
`includeDepositsWithSourceCreditor=true` on the distribution.
* The response is paged the same way as the distribution.
See [GET Get billing
vouchers](/api-reference/endpoints/billings/billing-vouchers) for full
details.
## 4. Posting it
Once you have both halves, a settlement decomposes into:
| What | Where it comes from |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Payments against your own receivables | Distribution entries with `caseVouchers[].source` `CREDITOR` |
| Collection entries settled out of those payments | Distribution entries with `caseVouchers[].source` `COLLECTOR` |
| Commission | `caseVouchers[].collectionCommission` on the distribution, and commission lines among the billing vouchers |
| Fees you are charged | Billing vouchers with `category` `fee` |
| Disbursements you are charged | Billing vouchers with `category` `disbursement` |
| Owed back to the debtor | `overpayment` on the distribution |
What is left is the net: paid out to you when the settlement is in your favour,
invoiced to you when it is not.
Reconcile the settlement against its total before posting it. If the parts do
not add up to the amount your debt collection partner paid out, something was
missed — most often the billing vouchers, or the direct payments landing on
whichever side of `includeDepositsWithSourceCreditor` you did not expect.
## Scopes
Both billing endpoints require `read:billings` on the API key. A key only ever
reaches its own creditor's settlements.
# Introduction
Source: https://creditor-documentation.debbiecollect.com/index
The Debbie Creditor API is a RESTful interface allowing you, as a creditor, to programmatically send data to your debt collection partner and access your data in the platform. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses.
![Hero Light]()
![Hero Dark]()
With the Creditor API you can integrate your own systems — for example your ERP
or invoicing system — directly with your debt collection partner. Typical use
cases are:
* Creating customers with contact details of the debtor
* Sending unpaid invoices, fees and deposits for collection
* Attaching documentation to a case, such as pdf copies of invoices
* Registering payments the debtor made directly to you
* Following the status of your collection cases
* Reading the settlement, so it can be posted in your own books
## Build the whole flow
The full integration, end to end: customer, invoices, documentation, direct
payments and settlement.
How a settlement is made up, and how to post it.
## Check out the API Reference
API Reference - authorization and endpoints