> For the complete documentation index, see [llms.txt](https://docs.moderncollections.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.moderncollections.io/rest-api/debtors.md).

# Debtors

A **debtor** is the company that owes money on a placement. Debtors are deduplicated across placements: if the same company has three overdue invoices, you'll see one debtor with three placements.

## No dedicated public endpoints

There are no `/v1/debtors` or `/v1/debtors/{id}` endpoints today. Debtor information is surfaced inside other resources:

* `GET /v1/placements/{id}` returns the debtor's `id`, `company_name`, `entity_type`, `state`, `city`, `primary_email`, `primary_phone` in the `debtor` sub-object.
* `GET /v1/analytics/top-debtors` returns the highest-outstanding debtors with `id`, `company_name`, `outstanding`, `placement_count` for the authenticated creditor.

Filtering placements by `debtor_id` is **not** currently exposed on `GET /v1/placements`.

## Deduplication

On `POST /v1/placements`, the platform reuses an existing debtor row when one of the following matches (in order):

1. **Canonical company name** — the intake pipeline strips punctuation and legal-entity suffixes (`Inc.`, `LLC`, `Corp.`) so `"Acme, Inc."` and `"Acme Inc"` collapse onto one row.
2. **`primary_email`** — exact match for this creditor.
3. **`primary_domain`** — exact match for this creditor.

Matching is per-creditor; the same company across two creditors is two separate debtor rows.

When matched, the existing debtor is **enriched** in-place — missing `primary_email`, `primary_domain`, `primary_phone`, or `state` fields on the existing row are filled in from the new placement payload.

## Fields tracked on a debtor

* **Identity:** `company_name`, `canonical_name`, `entity_type` (`llc`, `corporation`, `sole_proprietor`, `partnership`, `unknown`), `primary_domain`.
* **Contacts:** `primary_email`, `primary_phone`.
* **Geography:** `state`, `city`, `zip`. State drives compliance evaluation.
* **Safety flags:** `safety_flags` array on the placement (not the debtor) carries `debtor_sanctions_hit`, `volume_quota_exceeded`, `debtor_pile_on`, etc.

Per-channel opt-out flags (`call_opt_out`, `email_opt_out`) are set automatically when a debtor asks us to stop contacting them (on a call or via an email reply) and are honored by the outreach schedulers. They are not currently mutable via the public API.

## Sanctions screening

High-value placements (default threshold `$250,000`) trigger an OFAC / sanctions screen on the debtor entity at intake. A hit attaches the `debtor_sanctions_hit` safety flag to the placement; the compliance engine then blocks outreach. Vendor outages degrade gracefully — the placement still proceeds, and a `debtor.sanctions_screened` audit event records the degradation for a 24-hour re-screen.

## Hard delete / GDPR-style erasure

Tenant data is soft-deleted only (`deleted_at`). There is no public erasure endpoint today. A CPRA DSAR submission endpoint exists at `POST /v1/portal/dsar` (public, rate-limited to 5/hour per IP).

## See also

* [Compliance: data handling](/compliance-for-integrators/data-handling-pii.md)
* [Placements](/rest-api/placements.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.moderncollections.io/rest-api/debtors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.