Partner API Reference

List cases

Returns cases accessible to the partner. By default, returns cases across the calling client's organisation and all its sub-organisations.

Pass source and sourceId together to narrow to a single sub-organisation (e.g. one of the partner's neighbourhoods). Pass referenceNumber to filter to cases initiated against a specific partner reference (e.g. an appeal id) — useful for correlation lookups.

Results are paginated. Follow the rel="next" URL in the Link response header to retrieve the next page; the absence of rel="next" indicates the last page.

Get case details

Returns full details for a case, including person affected and incident information.

List evidence contributions

Returns evidence contributions submitted for the case, including preview/thumbnail URLs. To obtain download URLs for the files, fetch the individual evidence contribution via GET /cases/{caseId}/evidence-contributions/{evidenceContributionId}, or request a case bundle via POST /case-bundles for a packaged download with the signed MG11.

Results are paginated. Follow the rel="next" URL in the Link response header to retrieve the next page; the absence of rel="next" indicates the last page.

Get evidence contribution details

Returns details for a single evidence contribution, including download URLs for the file.

Request a case bundle

Requests generation of a case bundle for the specified case. The bundle includes a signed, dated MG11 exhibit form together with all submitted evidence files.

Poll GET /case-bundles/{caseBundleId} to check status. Once the status is Completed, download the bundle from the downloadUrl field on the returned resource.

Get case bundle

Returns the current state of a case bundle request. Poll this endpoint until status is Completed or Error.

Once status is Completed, the downloadUrl field will contain a URL pointing at the bundle file (signed MG11 + evidence).

Negotiate a SignalR connection for case bundle updates

Establishes a real-time connection to the case-bundles SignalR hub, where partners receive push notifications about bundle generation progress.

After a successful POST, connect using a SignalR client (e.g. @microsoft/signalr) and subscribe to the Update method. The hub will invoke Update with a CaseBundleUpdate payload as generation progresses — initial 0.0, incremental updates between 0.0 and 0.8 while documents are produced, 0.9 once the archive is compressed, and 1.0 when complete with downloadUrl populated. On failure, an update with status: Error and errorMessage populated is sent.

By default, the connection receives updates for every case bundle accessible to the calling client's organisation (and its descendants). Pass source and sourceId to scope the connection to a single sub-organisation.

For SignalR client setup, refer to the Microsoft SignalR client documentation.

Case submitted notification

Kulpa calls this endpoint on the partner's registered webhook URL when a case is submitted by a member of the public. The partner's endpoint must return 204 No Content to acknowledge receipt.

Authenticity: kulpa signs every webhook request. Two headers are sent:

• X-Kulpa-Timestamp — Unix epoch seconds at the time of dispatch.

• X-Kulpa-Signature — sha256=<hex>, where <hex> is the lowercase hex-encoded HMAC-SHA256 of the string <timestamp>.<raw request body> using the shared signing secret as the key.

Partners MUST verify the signature and reject any request whose timestamp differs by more than 5 minutes from the current time (replay protection). Pattern is identical to GitHub / Stripe / Slack webhooks; standard libraries exist in every major language.

Delivery semantics: at-least-once. Kulpa will retry on transport errors and non-2xx responses; the specific retry policy (intervals, max attempts, backoff) is subject to change. Partners MUST treat the endpoint as idempotent and de-duplicate by caseId, since the same event MAY be delivered more than once.