Collection Cases#

A Collection Case represents a debt recovery action submitted to a collection partner. Cases track the full lifecycle from submission through resolution.

The Collection Case object#

Attribute	Type	Description
`id`	string	UUID identifier with `dc_` prefix
`object`	string	Always `"collection_case"`
`reference`	string	Human-readable reference (e.g., `Q8OAXF3W`)
`status`	enum	`pending_verification`, `needs_details`, `active`, `paused`, `closed`
`close_code`	string	Resolution reason (when closed)
`amount_to_recover`	integer	Original debt amount in smallest currency unit
`remainder`	integer	Outstanding balance
`currency`	string	ISO 4217 currency code
`debtor`	object	Debtor information
`debtor.type`	enum	`company` or `private`
`debtor.name`	string	Debtor's name
`debtor.contact_person`	string	Contact person (for companies)
`debtor.email`	string	Debtor's email
`debtor.phone`	string	Debtor's phone
`debtor.address`	object	Debtor's address
`debtor.country`	string	ISO 3166-1 alpha-2 country code
`collection_partner`	object	Assigned collection partner
`collection_partner.name`	string	Partner name
`collection_partner.email`	string	Partner email
`collection_partner.phone`	string	Partner phone
`collection_partner.site`	string	Partner website
`creditor_reference`	string	Your internal reference
`due_date`	timestamp	Original payment due date
`is_test`	boolean	Test mode flag
`metadata`	hash	Key-value pairs
`created`	timestamp	Time at which the object was created

{
  "id": "dc_a1b2c3d4",
  "object": "collection_case",
  "reference": "Q8OAXF3W",
  "status": "active",
  "close_code": null,
  "amount_to_recover": 360000,
  "remainder": 360000,
  "currency": "eur",
  "debtor": {
    "type": "private",
    "name": "John Smith",
    "email": "john.smith@example.com",
    "phone": "+49 170 1234567",
    "address": {
      "line1": "Friedrichstraße 123",
      "city": "Berlin",
      "postal_code": "10117",
      "country": "DE"
    },
    "country": "DE"
  },
  "collection_partner": {
    "name": "CollectMax GmbH",
    "email": "cases@collectmax.de",
    "phone": "+49 30 1234567",
    "site": "https://collectmax.de"
  },
  "creditor_reference": "INV-2024-0892",
  "due_date": 1730419200,
  "is_test": false,
  "metadata": {
    "property_id": "prop_456",
    "tenant_id": "ten_789"
  },
  "created": 1706140800
}

Create a Collection Case#

POST /v1/collection_cases

Parameter	Type	Required	Description
`amount_to_recover`	integer	Yes	Debt amount in smallest currency unit
`currency`	string	Yes	ISO 4217 currency code
`debtor`	object	Yes	Debtor information
`debtor.type`	string	Yes	`company` or `private`
`debtor.name`	string	Yes	Debtor's full name
`debtor.email`	string	No	Debtor's email
`debtor.phone`	string	No	Debtor's phone number
`debtor.address`	object	Yes	Debtor's address
`debtor.country`	string	Yes	Country code
`creditor_reference`	string	No	Your internal reference
`due_date`	string	Yes	Original due date (YYYY-MM-DD)
`metadata`	hash	No	Key-value pairs

curl https://api.casapay.com/v1/collection_cases \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_to_recover": 360000,
    "currency": "eur",
    "debtor": {
      "type": "private",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "phone": "+49 170 1234567",
      "address": {
        "line1": "Friedrichstraße 123",
        "city": "Berlin",
        "postal_code": "10117",
        "country": "DE"
      }
    },
    "creditor_reference": "INV-2024-0892",
    "due_date": "2024-11-01"
  }'

{
  "id": "dc_a1b2c3d4",
  "object": "collection_case",
  "reference": "Q8OAXF3W",
  "status": "active",
  "amount_to_recover": 360000,
  "remainder": 360000,
  "currency": "eur",
  "created": 1706140800
}

Retrieve a Collection Case#

Retrieve by ID or by human-readable reference.

GET /v1/collection_cases/:id

GET /v1/collection_cases/ref/:reference

curl https://api.casapay.com/v1/collection_cases/dc_a1b2c3d4 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

# Or by reference
curl https://api.casapay.com/v1/collection_cases/ref/Q8OAXF3W \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

List Collection Cases#

GET /v1/collection_cases

Parameter	Type	Description
`status`	string	Filter by status
`debtor_country`	string	Filter by debtor country
`debtor_type`	string	Filter by `company` or `private`
`created[gte]`	timestamp	Created on or after
`created[lte]`	timestamp	Created on or before
`limit`	integer	Number of objects (1–100)
`starting_after`	string	Cursor for pagination

curl "https://api.casapay.com/v1/collection_cases?status=active&limit=10" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Upload a File to a Case#

POST /v1/collection_cases/:id/files

Content-Type: multipart/form-data

Parameter	Type	Required	Description
`file`	file	Yes	File to upload
`document_type`	string	Yes	`original_invoice`, `debtor_documents`, `creditor_documents`, `demand_letter`, `miscellaneous`
`description`	string	No	File description

curl https://api.casapay.com/v1/collection_cases/dc_a1b2c3d4/files \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -F "file=@invoice.pdf" \
  -F "document_type=original_invoice" \
  -F "description=Original unpaid invoice"