Cases
Create up to 100 RobinReturn cases in one request and read a case's status back over the Partner API.
Last updated
Create cases with POST /api/v1/cases (up to 100 per request) and read a case's status with
GET /api/v1/cases/{id}.
Create cases
Requires the cases:write scope. The Idempotency-Key header is optional but recommended — see
Idempotency.
curl -X POST https://app.robinreturn.co.uk/api/v1/cases \
-H "Authorization: Bearer $RR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: batch-2026-10-08-0001" \
--data @- <<'JSON'
{
"cases": [
{
"debtorName": "Acme Trading Ltd",
"debtorEmail": "billing@acme.test",
"debtorCompanyNo": "01234567",
"debtorAddress": "1 High St, Anytown, AN1 2BC",
"invoiceRef": "INV-2026-001",
"invoiceDate": "2026-01-15",
"dueDate": "2026-02-14",
"principalAmount": 1450.00,
"description": "Consultancy, January 2026",
"invoiceFileKey": "REPLACE_WITH_THE_FILEKEY_FROM_THE_UPLOAD_STEP",
"attestation": {
"b2b": true,
"under10k": true,
"within6years": true,
"undisputed": true,
"attestedBy": "Jane Smith"
}
}
]
}
JSONFields
| Field | Required | Notes |
|---|---|---|
debtorName | yes | 1–300 characters |
debtorEmail | yes | valid email |
invoiceRef | yes | 1–100 characters; not unique — see the duplicate guard below |
invoiceDate | yes | YYYY-MM-DD or ISO datetime; must not be after dueDate |
dueDate | yes | YYYY-MM-DD or ISO datetime; must be in the past |
principalAmount | yes | GBP, greater than 0 and at most 10,000 |
invoiceFileKey | yes | the fileKey from Uploads, under your company prefix |
attestation | yes | all four flags must be true; attestedBy names the authorised person |
debtorCompanyNo | no | Companies House number, 2–10 letters or digits — confirms registered details, gates jurisdiction |
debtorAddress, description | no | optional context |
The attestation is a legal eligibility assertion (the debt is B2B, at most £10,000, within the
six-year limitation window, and undisputed). It is recorded for the audit trail; all four answers
must be true.
invoiceRef is checked by a duplicate guard. A case is rejected with code DUPLICATE when your
company already has a case carrying an identical invoiceRef — a live case chasing it, or a
DRAFT from an earlier submission — and the rejection's existingReference names that case.
Settled, closed and withdrawn cases do not block, so a legitimate re-invoice stays possible.
Matching is exact, case-sensitive and untrimmed, so INV-001, inv-001 and INV-001 are three
different references. Still send an Idempotency-Key on every batch: it makes a
retry return the original answer, and the guard does not protect two identical requests sent at
the same time.
Response
The response never silently drops a case — every input is either created or rejected with a code.
{
"created": [ { "index": 0, "invoiceRef": "INV-2026-001",
"id": "…", "reference": "RR-2026-000123" } ],
"rejected": [ { "index": 1, "invoiceRef": "INV-2026-002",
"code": "DUPLICATE", "message": "…",
"existingReference": "RR-2026-000077" },
{ "index": 2, "invoiceRef": "INV-2026-003",
"code": "VALIDATION", "message": "…",
"issues": [ { "path": "debtorCompanyNo",
"message": "Enter a valid Companies House company number" } ] } ]
}existingReference is present only on DUPLICATE, and issues only on VALIDATION.
Status: 201 when at least one case was created, 200 when none were. See Errors for the full list of rejection codes.
Creating a case does not start chasing
A created case begins at DRAFT, and the Partner API cannot move it out of DRAFT. The whole
/api/v1 surface is POST /api/v1/uploads, POST /api/v1/cases and GET /api/v1/cases/{id}:
there is no status-transition endpoint, and no scope that would grant one.
The eligibility attestation gate is already satisfied at creation — your four answers are recorded on the case as an attestation event by the same shared core the dashboard wizard uses. What the case is actually waiting for is a person in the RobinReturn dashboard starting the first reminder, either by claiming the free first reminder on a new account or by paying for the reminder bundle. Until someone does that, the case sits at DRAFT indefinitely.
No account setting changes this. If an “automatic attestation” option was mentioned when your API
access was approved, it has no runtime effect today: granted and un-granted accounts behave
identically, and both still need the dashboard step. Build for that — hand the case reference to
whoever owns the account, and poll GET /api/v1/cases/{id} to observe the status leaving DRAFT.
Read a case
Requires the cases:read scope. Use the id from created[].
curl https://app.robinreturn.co.uk/api/v1/cases/REPLACE_WITH_CASE_ID \
-H "Authorization: Bearer $RR_API_KEY"{
"id": "…", "reference": "RR-2026-000123", "status": "DRAFT",
"debtorName": "Acme Trading Ltd", "principalAmount": "1450.00",
"currency": "GBP", "createdAt": "…", "updatedAt": "…"
}A case belonging to another company returns 404 — it is never revealed. Each status value is
listed, with its dashboard label and what happens next, in Case statuses.