Cases

Create up to 100 RobinReturn cases in one request and read a case's status back over the Partner API.

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

POST /api/v1/cases            scope: cases:write
Idempotency-Key: <your-unique-key>      (optional, recommended)
Content-Type: application/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": "<fileKey from the upload step>",
      "attestation": {
        "b2b": true,
        "under10k": true,
        "within6years": true,
        "undisputed": true,
        "attestedBy": "Jane Smith"
      }
    }
  ]
}

Fields

Field	Required	Notes
`debtorName`	yes	1–300 characters
`debtorEmail`	yes	valid email
`invoiceRef`	yes	1–100 characters; unique per company (duplicate guard)
`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	limited-company number — 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.

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": "…" } ]
}

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. Recovery only starts once the eligibility attestation gate is satisfied; for API cases, automatic progression additionally requires RobinReturn to have enabled auto-attestation for your account (agreed at access approval). Otherwise the case waits for an in-dashboard confirmation.

Read a case

GET /api/v1/cases/{id}        scope: cases:read

{
  "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. The status values mirror the case lifecycle described in Case statuses.