> 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/overview.md).

# Overview

The Modern Collections REST API is your primary integration surface for placing invoices, tracking outreach, reconciling payments, and acting on collections programmatically.

The [OpenAPI specification](https://github.com/knollmeyersam-dot/MC-Docs/blob/main/api-reference/rest-api/openapi.yaml) is the canonical machine-readable definition. It is **generated directly from the live application schema** — covering the external creditor-API-key surface (62 paths / 71 operations) — so request and response shapes are field-accurate and cannot drift from the implementation. The pages in this section are descriptive companions to that contract.

## Base URL

All API routes are versioned under `/v1/`. There is no production default and no single published host — you select an environment explicitly, and each environment has its own host:

| Environment | Base URL                                |
| ----------- | --------------------------------------- |
| `demo`      | `https://app.demo.moderncollections.io` |
| `prod`      | `https://api.moderncollections.io`      |

Append `/v1` to any of these to reach the versioned API. On `demo`, authenticated `/v1/*` calls reach the backend; the bare `/health` is the dashboard origin, not the API. See [Environments](/getting-started/environments.md) for what changes between environments.

## Authentication

Bearer token in the `Authorization` header: `Bearer ca_<prefix>_<secret>`. The same header is used on every external route. Onboarding routes under `/v1/creditors/me/*` and `/v1/agreements/*` also accept the short-lived onboarding JWT issued at signup. See [Authentication](/getting-started/authentication.md).

## Content types

* **Requests:** `application/json` (intake also accepts `text/csv` and `multipart/form-data` on specific routes).
* **Responses:** `application/json`.

## Resource URL patterns

There is no single uniform pattern. The placements router uses RPC-flavoured action endpoints (`POST /v1/placements/{id}/recall`, `POST /v1/placements/{id}/posture`, `POST /v1/placements/{id}/payment-received`) alongside the resource endpoints (`POST /v1/placements`, `GET /v1/placements/{id}`).

## Pagination

`GET /v1/placements` accepts `page` (≥1, default 1) and `page_size` (1..100, default 25). The response wraps:

```json
{
  "placements": [/* … */],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total_count": 142,
    "total_pages": 6
  }
}
```

Other list endpoints (payments, remittances, audit) use varying shapes — `GET /v1/placements/{id}/audit` uses keyset pagination with a `cursor` parameter and returns `{"events": [...], "pagination": {"next_cursor": ..., "has_more": ...}}`.

## Filtering

Where supported, multi-value filters are comma-separated:

```
GET /v1/placements?status=in_outreach,pending_payment
```

`GET /v1/placements/{id}/audit` supports `event_type` (CSV, capped at 25 values), `actor`, `since`, `until`.

## Sorting

Not exposed as a public query parameter on placements today; results are sorted by `placed_at DESC`.

## Timestamps

ISO-8601 UTC. Example: `"2026-04-09T16:00:00Z"`.

## Money

Decimal USD in request and response bodies (`7500.00`). The `currency` field is always `"USD"` today.

## Resources

These pages narrate the most-used corners of the surface. They are not exhaustive — the [OpenAPI specification](https://github.com/knollmeyersam-dot/MC-Docs/blob/main/api-reference/rest-api/openapi.yaml) is.

| Resource                              | Purpose                                                                                    | Most-used endpoints                                              |
| ------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| [Placements](/rest-api/placements.md) | Create, list, retrieve, recall, change posture, amend.                                     | `POST /v1/placements`, `GET /v1/placements/{id}`                 |
| [Debtors](/rest-api/debtors.md)       | Debtor entities are implicit — there are no dedicated `/v1/debtors` endpoints today.       | Surfaced inside placement responses.                             |
| [Payments](/rest-api/payments.md)     | List payment commitments and attempts; record received payments.                           | `GET /v1/payments`, `POST /v1/placements/{id}/payment-received`  |
| [Disputes](/rest-api/disputes.md)     | Acknowledge and inspect disputes filed by debtors via the portal.                          | `POST /v1/placements/{id}/dispute/acknowledge`                   |
| [Analytics](/rest-api/analytics.md)   | Per-creditor aggregates: recovered series, status distribution, top debtors, call heatmap. | `GET /v1/analytics/summary`, `GET /v1/analytics/recovered-daily` |
| [Portal](/rest-api/portal.md)         | Debtor self-service endpoints (JWT-authenticated).                                         | Debtor-only                                                      |

### Surfaces not narrated here

These routers are part of the external creditor-API-key surface and are fully described in the [OpenAPI specification](https://github.com/knollmeyersam-dot/MC-Docs/blob/main/api-reference/rest-api/openapi.yaml) — they just don't have a hand-written companion page yet:

* `/v1/intake/*` — CSV preview/commit, file and webhook intake, drafts, and intake addresses.
* `/v1/documents/*` — document upload, processing, and match confirmation.
* `/v1/exports/*` — export jobs and downloads.
* `/v1/statements/*` — remittance statements and statement downloads.
* `/v1/agreements/*` — MSA review and acceptance (also accepts the onboarding JWT).
* `/v1/integrations/qbo/*` — QuickBooks Online connect, sync log, and disconnect.
* `/v1/creditors/me/*` — self-serve onboarding (KYB submission, tax info, API-key issuance, bank link, status).
* `/v1/settings` and `/v1/creditors/me/notification-settings` — account and notification settings.

The unauthenticated `/health` checks, the debtor portal, and the admin surface are excluded from the spec by design (the public signup route `POST /v1/creditors` **is** included). The remittance endpoints (`GET /v1/creditors/me/remittances`, `GET /v1/placements/{id}/remittance`) exist in the API but are not yet covered by the generated spec — see [Payments](/rest-api/payments.md) for their shapes.

> Tax classification note: `tax_classification` accepts exactly `sole_prop`, `partnership`, `llc`, `s_corp`, `c_corp`, `nonprofit`, `other`. Any other value (including longer spellings like `sole_proprietor` or `single_member_llc`) is rejected.

## OpenAPI specification

```
openapi.yaml
```

It is regenerated from the live application on each change, so it is always the field-accurate source of truth. A hosted OpenAPI URL is not yet published.

## Versioning

The API is on **v1**. We commit to additive-only changes within v1 — new fields, new endpoints, new events ship continuously without breaking your integration. A breaking change would ship as `/v2/…`. See the [Change Log](https://github.com/knollmeyersam-dot/MC-Docs/blob/main/change-log/README.md).

## See also

* [Error handling](/getting-started/error-handling.md) — error body shape and status codes.
* [SDKs](/sdks/python.md) — the typed Python client (`mc_api.client.MCClient`) and the JavaScript client.
* [CLI & MCP quickstart](/integration-guides/mcp-agent-quickstart.md) — drive the API from the `mc-api` CLI or an agent.
* [MCP Servers](/mcp-servers/overview.md) — the stdio MCP server and its [tools](/mcp-servers/tools.md).
* [Webhooks](/webhooks/overview.md) — get notified instead of polling.


---

# 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/overview.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.