POST /claims

Create a recovery claim for a connected entity. Your optional message and any document_refs become the claim's first message, which kicks off Garfield's AI processing. Put any context for the AI (background on the debt, what the attachments are, instructions) in message. Idempotent on partner_claim_id (scoped per entity).

Request

Required: entity_id, partner_claim_id, defendant (with defendant.name), and at least one invoices entry. partner_claim_id is your stable case reference and the idempotency key: reuse the same value on retries (and on the matching /documents/upload-url call).

curl -X POST "$BASE/claims" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @claim.json

claim.json
{
  "entity_id": "aZ4kQ9pX2",
  "partner_claim_id": "case-2026-00412",
  "partner_user_id": "acme-crm-7741",
  "partner_invoice_ids": ["INV-1001", "INV-1002"],
  "message": "Two overdue invoices, disputed once. Invoice attached.",
  "defendant": {
    "name": "Debtor Ltd",
    "email": "accounts@debtor.example",
    "address": {
      "first_line": "1 High Street",
      "second_line": null,
      "town_city": "London",
      "county": "Greater London",
      "postcode": "EC1A 1BB",
      "country": "United Kingdom"
    },
    "is_consumer": false,
    "is_individual": false,
    "company_registration_number": "12345678"
  },
  "invoices": [
    {
      "number": "INV-1001",
      "total_amount_for_invoice": "1500.00",
      "created_date": "2026-01-10",
      "due_date": "2026-02-10",
      "summary": "Consulting services"
    },
    {
      "number": "INV-1002",
      "total_amount_for_invoice": "900.00",
      "created_date": "2026-02-01",
      "due_date": "2026-03-03",
      "summary": "Consulting services, phase 2"
    }
  ],
  "contract_date": "2026-01-01T00:00:00.000Z",
  "is_written": true,
  "document_refs": [
    {
      "storage_path": "entities/aZ4kQ9pX2/claims/pc_af66fa4b5cb7283356863b7554d4e140/documents/0TCsxImkxYI.pdf",
      "mime_type": "application/pdf",
      "filename": "invoice-00412.pdf"
    }
  ]
}

partner_invoice_ids are your own invoice references, stored on the claim and echoed back by GET /claims for reconciliation. Note the defendant address uses town_city/county, while the /onboardings address uses locality/region. The two shapes are not interchangeable.

Response

201 Created (new) / 200 OK (idempotent replay):

{
  "claim_id": "k4m9t",
  "message_id": "a1b2c",
  "document_ids": ["d3f4g"],
  "already_existed": false
}

Replay behaviour

message_id is null when no first message was created (empty message and no document_refs) and on every replay. On a replay, document_ids is always empty; documents link only on first creation, so send all your context and documents on the first call. See Idempotency.

Request​

Response​

Request

Response