Partner API
Create RobinReturn recovery cases programmatically and read their status back over the v1 REST API.
Last updated
The Partner API lets your own system create RobinReturn recovery cases programmatically and read their status back. It is pull-only with respect to your books — RobinReturn never writes into your accounting systems.
Base URL: https://app.robinreturn.co.uk
The live v1 endpoints are:
| Method | Path | Scope | Purpose |
|---|---|---|---|
POST | /api/v1/uploads | cases:write | Get a presigned URL to upload an invoice |
POST | /api/v1/cases | cases:write | Create up to 100 cases |
GET | /api/v1/cases/{id} | cases:read | Read a case's status |
Getting access
API access is not self-serve — a key creates cases in your company's name, each carrying a legal eligibility attestation, so it is granted after a short review:
Request access
As the account owner, go to Settings → Developer → Request API access. State your intended use, the scopes you need, and accept the API terms.
RobinReturn approves
An operator reviews and approves the request.
Mint a key
As the owner, create a key under Settings → Developer. The full secret is shown once — store it securely. RobinReturn keeps only a hash and can never show it again. Revoke a key any time.
How case creation works
A case must carry its original invoice document (it ships with the Letter Before Action and any court bundle), so creating a case is two steps:
- Upload the invoice → you get a
fileKey. - Create the case(s) referencing that
fileKey.
Testing your integration
There is no test environment and no test mode. Every key is a live key, and every request reaches your real account. Plan your testing around that:
- Creating a case is safe to test. A case created through the API starts at
DRAFT, and nothing is sent to the debtor until someone starts recovery in the dashboard — see Cases. - Use invoice references you will not need later. A test draft blocks its
invoiceReffrom being submitted again (DUPLICATE) until you withdraw it in the dashboard. - Withdraw test drafts when you finish, from the case page in the dashboard. The API has no delete or withdraw endpoint.
- Use a synthetic debtor with an email address you control, so a draft started by mistake cannot reach a real business.
- Rate limits apply in the same way as in production — see Rate limits.
- Registered webhooks fire for test cases too — see Webhooks.
What's available, what's planned
The endpoints above are live, and outbound status webhooks are available — registered by an owner under Settings → Developer, not through the Partner API. A full, formally-generated OpenAPI reference is planned on top of this guide — until then, this section is the authoritative public contract for the live endpoints.
In this section
- Authentication — keys, scopes, headers.
- Uploads — the presigned upload step.
- Cases — create and read cases.
- Idempotency — replayed retries and the duplicate guard.
- Rate limits — limits and back-off.
- Errors — the error model and rejection codes.
- Changelog — API versioning and changes.