Skip to main content

Test Cases

Create cases in production without triggering real collection activity by setting IsTest: true.

How It Works​

When you create a case with IsTest: true, Debitura validates and persists it as test data. Test cases suppress real collection routing and production email effects, but deliberate test behavior still occurs: test-mode webhooks and timeline events let you exercise an integration end to end. Test cases cannot be converted to production cases.

The behavior diverges after creation depending on which API you are using:

Customer API​

  • May be assigned through normal partner matching — test classification suppresses production effects; it does not guarantee that collectionPartner is empty
  • Visible in your own case listing by default — no opt-in needed; creditors own their test data and see it alongside production cases
  • No emails sent to debtor, creditor, or partners

Collection Partner API​

  • Self-assigned to the managing partner (routing isolation) — test cases you submit are automatically assigned to your own partner account. They never escape into the global routing pipeline or appear on any other partner's work queue.
  • Hidden from GET /cases by default — opt in with ?includeTestCases=true to include test cases the caller owns. This keeps production work queues clean during integration development.
  • Direct-by-ID endpoints work without the opt-in — if you created the case, these work on it directly without ?includeTestCases=true:
    • GET /cases/{id} and GET /cases/case-reference/{caseReference}
    • POST /cases/{id}/start and POST /cases/{id}/close
    • GET /cases/{id}/chats and PUT /cases/{id}/fees
  • No emails or notifications fire to creditors or debtors

Listing test cases on the Collection Partner API​

GET /cases?includeTestCases=true
XApiKey: YOUR_API_KEY

Returns your normal case list plus any test cases where you are the collection partner. Combine with other filters as needed:

GET /cases?includeTestCases=true&statuses=Active&pageSize=50
XApiKey: YOUR_API_KEY

Example​

POST /cases
Content-Type: application/json
XApiKey: YOUR_API_KEY

{
  "isTest": true,
  "currencyCode": "USD",
  "amountToRecover": 1500.00,
  "date": "2025-08-01",
  "debtor": {
    "type": "Company",
    "name": "Test Company Ltd",
    "address": "123 Test Street",
    "city": "London",
    "countryAlpha2": "GB"
  }
}

Tagging Test Cases​

Use the tag field to attach a label to a test case at creation time. Tags scope cleanup — you can delete all cases sharing the same tag with a single DELETE /test/cases?tag=... call. This is the recommended pattern for CI pipelines where parallel runs must not interfere with each other's cleanup.

suite-run-{uuid}

The tag field is supported on both POST /cases (Customer API) and POST /managed-cases (Collection Partner API).

POST /cases
Content-Type: application/json
XApiKey: YOUR_API_KEY

{
  "isTest": true,
  "tag": "suite-run-a3f9c12e",
  "currencyCode": "USD",
  "amountToRecover": 1500.00,
  "date": "2025-08-01",
  "debtor": {
    "type": "Company",
    "name": "Test Company Ltd",
    "address": "123 Test Street",
    "city": "London",
    "countryAlpha2": "GB"
  }
}

Identifying Test Cases​

In API responses, test cases include "isTestCase": true:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isTestCase": true,
  "lifecycle": "Active"
}

Use the isTestCase field to filter test data in your application.

Advancing Test Cases​

Use POST /test/cases/{id}/advance to jump a test case to a known lifecycle state synchronously. This is the fastest way to drive a case through your integration without waiting for real business processes to run.

POST /test/cases/{id}/advance
Content-Type: application/json
XApiKey: YOUR_API_KEY

{
  "to": "Closed:Paid",
  "amount": 1500.00
}

Valid to values are Active, Closed:Paid (requires amount), and Closed:NoPayment. The advance endpoint fires real webhooks and timeline events. See CI Testing for the full response shape, all guards, and the advance-state caveat.

Cleanup​

Test cases support two hard-delete operations that cascade to related case data (including payments, chats, files, timeline entries, and webhook delivery records). The separately persisted webhook-event history returned by GET /webhooks/events is not deleted.

Delete by tag​

DELETE /test/cases?tag=suite-run-a3f9c12e
XApiKey: YOUR_API_KEY

Deletes all test cases with this tag. Returns 204 No Content. Idempotent — returns 204 even if no cases match the tag. Both endpoints reject the request if any matched case has Classification == Production — live cases are never affected.

Delete a single case​

DELETE /test/cases/{id}
XApiKey: YOUR_API_KEY
note

These are hard deletes — the case and all related records are permanently removed, not soft-deleted. Do not use the same tag across runs you want to keep.

Debitura may also periodically clean up old test cases. Do not rely on test cases persisting indefinitely.

Applies To​

For a complete CI test loop guide, see CI Testing.