Skip to main content

Advance a test case to a known lifecycle state.

POST 
/test/cases/:id/advance

Drives a test case to a well-known lifecycle state in a single call.

Purpose: Enables CI pipelines and integrators to exercise the full collection lifecycle — including real webhooks and events — without manual intervention.

Target States:

  • Active — Activates the case from PendingVerification or PendingVerificationInternal. No-op if already Active or Closed.
  • Closed:Paid — Records a payment for amount and closes the case as Paid. Activates the case first if needed. amount is required.
  • Closed:NoPayment — Closes the case with PreLegalExhaustedNoPayment. Activates the case first if needed.

Guards:

  • Returns 400 if the case is not a test case (Classification != Test).
  • Returns 400 if amount is missing when to is Closed:Paid.
  • Returns 400 if to is not one of the valid values.
  • Returns 400 if the case is already closed with a different close code (e.g. already Closed:NoPayment when requesting Closed:Paid).
  • Returns 404 if the case is not found or not owned by the calling partner.

No-op behaviour: If the case is already at the requested state, the call returns 200 with advanced: false and the current state — no changes are made.

Webhooks: Transitions use the real internal service pipeline. Webhook delivery per target:

  • → Active: fires case.updated to Creditor, ReferralPartner, and Collection Partner subscriptions.
  • → Closed:Paid: fires payment.created to Creditor and Collection Partner; fires case.updated and case.closed to Creditor, ReferralPartner, and Collection Partner subscriptions.
  • → Closed:NoPayment: fires case.updated and case.closed to Creditor, ReferralPartner, and Collection Partner subscriptions.

Note: case.closed is delivered to Collection Partner subscriptions on both close paths.

All events carry classification: test and are only delivered to webhook subscriptions registered with classification: test.

How to Test:

  1. Create a test case — POST /managed-cases with isTest: true (optionally a tag for scoped cleanup). Note the returned id.

  2. Register a test webhook subscription — subscribe to the events you want to assert on (case.updated, payment.created, case.closed) with classification: test and point the URL to your test receiver (e.g. a local ngrok tunnel or a CI webhook sink).

  3. Advance to Active — POST /test/cases/{id}/advance with { "to": "Active" }. Expect { advanced: true, state: "Active" } and a case.updated event on your Collection Partner subscription.

  4. Advance to Closed:Paid — POST /test/cases/{id}/advance with { "to": "Closed:Paid", "amount": 1000.00 }. Expect { advanced: true, state: "Closed:Paid" } and a payment.created event on your Collection Partner subscription.

    • Alternatively: advance straight from any pre-active state — the endpoint activates the case first automatically.

  5. Verify final state — GET /cases/{id} and assert lifecycle: Closed and closeCode: Paid.

  6. Test no-op — Call the same advance again. Expect { advanced: false, state: "Closed:Paid" } and no new webhook events.

  7. Test mismatch error — With the case closed as Paid, call { "to": "Closed:NoPayment" }. Expect 400 with a message describing the conflict.

  8. Test Closed:NoPayment path — Create a fresh test case, call { "to": "Closed:NoPayment" } directly (no amount needed). Expect case.updated and case.closed on your Collection Partner subscription.

  9. Reset between runs — Delete the test case via DELETE /test/cases/{id} (or DELETE /test/cases?tag={tag} to clear a whole tag) or create a new one per test run to keep assertions clean.

Request​

Responses​

Advance result (advanced=true if state changed, advanced=false if already there)