Recoveries

The recovery ledger is the money history of a case: funds identified, freezes, payment plans, settlements, payments received, costs and remittances. RecovAI uses it to work out how much has been recovered and how much is still owed.

Method	Path	What it does
`GET`	`/cases/{id}/recoveries`	Read the ledger
`POST`	`/cases/{id}/recoveries`	Add an entry
`POST`	`/recoveries/{id}/reverse`	Reverse an entry

Read the ledger

GET/cases/{id}/recoveriesRead onlyAPI key

Example

curl https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/recoveries \
  -H "X-API-Key: $RECOVAI_API_KEY"

<?php
$ch = curl_init('https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/recoveries');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($result['error'] . ': ' . ($result['details'] ?? ''));
}

const res = await fetch('https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/recoveries', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.details ?? ''}`);

import os
import requests

r = requests.get(
    "https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/recoveries",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    timeout=60,
)
data = r.json()
if not r.ok:
    raise RuntimeError(f"{data['error']}: {data.get('details', '')}")

Response `200 OK`

{
  "entries": [
    {
      "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
      "case_id": "5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a",
      "type": "partial_recovery",
      "label": "Partial recovery received",
      "amount": 12000,
      "currency": "USD",
      "status": "confirmed",
      "occurred_at": "2026-10-10T00:00:00.000Z",
      "details": { "payment_method": "ach", "reference": "PMT-0001" },
      "idempotency_key": "servicing-PMT-0001",
      "reverses_id": null,
      "reversed_entry": null,
      "actor": null,
      "submission": null,
      "evidence_document": null,
      "created_at": "2026-10-14T16:20:00.000Z"
    }
  ],
  "summary": {
    "identified": 0,
    "frozen": 0,
    "redirected": 0,
    "committed": 0,
    "recovered": 12000,
    "costs": 0,
    "remitted": 0,
    "net_recovered": 12000,
    "awaiting_remittance": 12000,
    "remaining_balance": 36250,
    "recovery_rate": 24.9,
    "active_entries": 1,
    "reversal_count": 0
  },
  "currency": "USD"
}

actor is null for entries recorded with an API key.

Summary fields

Field	Meaning
`identified`, `frozen`, `redirected`	Totals of `funds_identified`, `freeze` and `redirect` entries.
`committed`	Total of `payment_plan` and `settlement` entries.
`recovered`	Total of `partial_recovery` and `full_recovery` entries.
`costs`, `remitted`	Totals of `cost` and `remittance` entries.
`net_recovered`	`recovered` minus `costs`.
`awaiting_remittance`	`recovered` not yet remitted.
`remaining_balance`	Case balance minus `recovered`, never below 0.
`recovery_rate`	`recovered` as a percentage of the case balance.
`active_entries`	Entries counted in the totals.
`reversal_count`	Entries that have been reversed. Reversed entries are left out of every total.

Add an entry

POST/cases/{id}/recoveriesChanges dataAPI key

Field	Type	Required	Description
`type`	string	yes	One of the entry types.
`amount`	number	yes	USD, at least `0.01`, two decimals at most.
`currency`	string		Only `USD`.
`occurred_at`	timestamp		When it happened. Defaults to now; cannot be in the future.
`payment_method`	string		`ach`, `wire`, `check`, `card`, `processor_transfer` or `other`.
`reference`	string		Your payment or transaction reference.
`counterparty`	string		Who paid or was paid.
`note`	string		Up to 4,000 characters.
`evidence_document_id`	UUID		A document on this case that proves the entry.
`submission_id`	UUID		The notice this recovery came from, if any.
`idempotency_key`	string		8–100 characters. Re-sending with the same key returns the original entry instead of recording it twice.

curl https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/recoveries \
  -H "X-API-Key: $RECOVAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "partial_recovery",
    "amount": 12000,
    "occurred_at": "2026-10-10T00:00:00Z",
    "payment_method": "ach",
    "reference": "PMT-0001",
    "idempotency_key": "servicing-PMT-0001"
  }'

<?php
$ch = curl_init('https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/recoveries');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode([
        'type' => 'partial_recovery',
        'amount' => 12000,
        'occurred_at' => '2026-10-10T00:00:00Z',
        'payment_method' => 'ach',
        'reference' => 'PMT-0001',
        'idempotency_key' => 'servicing-PMT-0001',
    ]),
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY'), 'Content-Type: application/json'],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($result['error'] . ': ' . ($result['details'] ?? ''));
}

const res = await fetch('https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/recoveries', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "type": "partial_recovery",
    "amount": 12000,
    "occurred_at": "2026-10-10T00:00:00Z",
    "payment_method": "ach",
    "reference": "PMT-0001",
    "idempotency_key": "servicing-PMT-0001"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.details ?? ''}`);

import os
import requests

r = requests.post(
    "https://api.recovai.ai/cases/5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a/recoveries",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    json={
        "type": "partial_recovery",
        "amount": 12000,
        "occurred_at": "2026-10-10T00:00:00Z",
        "payment_method": "ach",
        "reference": "PMT-0001",
        "idempotency_key": "servicing-PMT-0001",
    },
    timeout=60,
)
data = r.json()
if not r.ok:
    raise RuntimeError(f"{data['error']}: {data.get('details', '')}")

Response `201 Created`

The new entry, plus the whole ledger (entries, summary, currency) as in Read the ledger. A replayed request returns 200 OK with "replayed": true.

Errors

Status	`error`	Meaning
400	`invalid_submission`	`submission_id` is not on this case.
400	`invalid_evidence`	`evidence_document_id` is not on this case.
409	`case_closed`	A closed case only accepts `partial_recovery`, `full_recovery`, `cost` and `remittance`.
409	`idempotency_conflict`	The key was already used for a different entry.
422	`future_ledger_date`	`occurred_at` is in the future.
422	`remittance_exceeds_recovery`	You cannot remit more than has been recovered.

Entries cannot be edited or deleted. To correct one, reverse it and record a new entry.

Reverse an entry

POST/recoveries/{id}/reverseChanges dataAPI key

Cancels a ledger entry by adding a linked reversal entry. The original stays visible in the history but no longer counts in any total.

Field	Type	Required	Description
`reason`	string	yes	Why it is being reversed, 3–2,000 characters. Shown on the case timeline.

curl https://api.recovai.ai/recoveries/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/reverse \
  -H "X-API-Key: $RECOVAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Payment returned by the bank (NSF)."
  }'

<?php
$ch = curl_init('https://api.recovai.ai/recoveries/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/reverse');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode([
        'reason' => 'Payment returned by the bank (NSF).',
    ]),
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY'), 'Content-Type: application/json'],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($result['error'] . ': ' . ($result['details'] ?? ''));
}

const res = await fetch('https://api.recovai.ai/recoveries/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/reverse', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "reason": "Payment returned by the bank (NSF)."
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.details ?? ''}`);

import os
import requests

r = requests.post(
    "https://api.recovai.ai/recoveries/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/reverse",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    json={
        "reason": "Payment returned by the bank (NSF).",
    },
    timeout=60,
)
data = r.json()
if not r.ok:
    raise RuntimeError(f"{data['error']}: {data.get('details', '')}")

Response `201 Created`

The new reversal entry (with type: "reversal" and reverses_id pointing at the original), plus the whole updated ledger.

Errors

Status	`error`	Meaning
404	`recovery_not_found`	No such entry in your workspace.
409	`already_reversed`	The entry was already reversed.
409	`reversal_not_reversible`	A reversal cannot be reversed; record a new entry instead.

Entry types

Value	Meaning
`funds_identified`	Funds found that could be recovered.
`freeze`	Funds frozen.
`redirect`	Payments redirected.
`payment_plan`	A payment plan agreed.
`settlement`	A settlement agreed.
`partial_recovery`	Money received, part of the balance.
`full_recovery`	Money received, the full balance.
`cost`	A cost incurred on the case.
`remittance`	Money passed on to the client.

Recoveries

Read the ledger

Example

Response 200 OK

Summary fields

Add an entry

Response 201 Created

Errors

Reverse an entry

Response 201 Created

Errors

Entry types

Response `200 OK`

Response `201 Created`

Response `201 Created`