Collection Partners: How to assign and use your own case reference
You can assign your own internal reference number to any Debitura case. This partner reference lets you map Debitura cases to your own system, find cases by your internal ID, and include your reference in exports and balance reports.
The most common place to set the partner reference is when you activate a case. The activation flow includes an optional field for your reference, so you can assign it right from the start rather than updating it after the fact.
What is the partner reference?
Every case in Debitura carries three reference identifiers:
Debitura reference - the auto-generated case ID (e.g.
Q8OAXF3W).Client reference - the invoice number assigned by the creditor in their own system.
Partner reference - an optional reference you assign from your own internal system.
The partner reference is free-text, up to 128 characters, and can be set, changed, or cleared at any time. It is not required.
Set the partner reference when activating a case
When you activate (start) a case, the activation flow includes an optional field for your partner reference. This is the recommended point to set it, because it ties the Debitura case to your internal system from the very beginning.
If you use the Collection Partner API, include collectionPartnerReference in the request body of the case activation request. The field is optional and accepts up to 128 characters. The activation response echoes back the reference that was stored, so you can confirm it was saved correctly.
Update the partner reference later
If you did not set a reference during activation, or need to change it, you can update it at any time from the case detail page:
Open Cases Received and click on the case you want to update.
In the case detail sidebar, find the Partner reference row. If no reference is set, it shows a dash.
Click the pencil icon next to the row. The Collection-partner reference modal opens with a single text field labelled "Reference (can be blank)".
Enter your reference and save. The reference is updated immediately.
Once set, the case headline also displays your reference: Case Q8OAXF3W (partner ref: YOUR-REF).
The collectionPartnerReference field is also accepted on API lifecycle update requests, updating the stored value when the lifecycle is changed.
Where the partner reference appears
Location | What you see |
Case detail sidebar | Displayed as the "Partner reference" row; shows a dash when empty |
Case page headline | Appended in parentheses: |
"Partner reference" column (hidden by default; enable it via the column picker). The search bar also matches partner references, so you can search by your own ID. | |
CSV export |
|
ZIP export | When you choose "Partner Ref" as the folder naming option, case folders are named by your partner reference (falls back to the Debitura reference if not set) |
For more on the balance page, see Partner Balance - fields, calculations, and common questions.
Look up a case by partner reference
You can find a case using your partner reference in two ways:
Partner Balance search bar: type your reference in the search box on the Partner Balance page. The search matches both the Debitura reference and your partner reference.
API lookup: the Collection Partner API provides endpoints to retrieve a single case or a batch of up to 100 cases by partner reference. Each lookup is scoped to your own cases only.
Rules and limits
Rule | Detail |
Required | No - the field is always optional |
Maximum length | 128 characters |
Uniqueness | Not enforced - multiple cases can share the same partner reference |
Matching | Exact string match, case-sensitive |
Format | No restrictions - any string format is accepted |
Whitespace | Leading and trailing whitespace is trimmed automatically on save |
Who can see the partner reference?
The partner reference is visible only to collection partners and Debitura admins. It is not shown to creditors (clients) as it is partner-internal data.