> 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/conventions.md). # Conventions Conventions, authentication, pagination, and where the endpoint reference lives. The [**OpenAPI 3.1 spec**](https://github.com/knollmeyersam-dot/MC-Docs/tree/main/api-reference/rest-api/openapi.yaml) is the endpoint reference. It is generated directly from the live application schema, so every path, field and response shape is accurate by construction and cannot drift from the implementation. The explorer in the sidebar renders it; the spec file is also what you feed to a code generator. This page covers the conventions that apply across it. ## Authentication A bearer token on every request: ``` Authorization: Bearer ca__ ``` Onboarding routes under `/v1/creditors/me/*` and `/v1/agreements/*` also accept the short-lived onboarding JWT issued at signup. A **platform partner** uses `Bearer pa__` and adds an `X-MC-Creditor` header naming which linked creditor the request acts for. The paths, bodies and response shapes are identical either way — only tenant selection differs. See [Platform partners](/rest-api/partner-model.md). | Caller | Credential | Tenant chosen by | | ---------------- | ---------------------------------------- | ------------------------------------------- | | Creditor | `Bearer ca_…` | The key itself. `X-MC-Creditor` is ignored. | | Platform partner | `Bearer pa_…`, or a Partner User session | The `X-MC-Creditor` header, on every call. | ## Conventions * **Timestamps** are UTC ISO-8601 strings. * **Amounts** are decimal USD in request and response bodies (`7500.00`) — except EPD-adjacent fields (payment attempts, portal payment intents), which use integer `amount_cents`. * **IDs** are UUIDs. They are not sequential — treat them as opaque. * **Versioning**: every endpoint is under `/v1/` (the unauthenticated `/health` probes excepted). We commit to additive-only changes within v1; breaking changes ship as `/v2/…`. ## Pagination Two styles, depending on the endpoint: * **Page-based** on list endpoints — `page` and `page_size` (`GET /v1/placements` caps at 100, `GET /v1/payments` at 200). * **Keyset** on the audit trail — `GET /v1/placements/{id}/audit` returns `{"events": [...], "pagination": {"next_cursor": …, "has_more": …}}`. Pass `next_cursor` back as `cursor`. ## The surfaces | Surface | What it covers | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Placements | The root resource. Create, read, recall, amend, posture, payments, disputes, audit. See [Placements](/rest-api/placement-lifecycle.md). | | Intake | Bulk and alternate filing channels — signed JSON, CSV, file drop, the review queue. See [Ingest overdue invoices](/guides/ingest-invoices.md). | | Payments and remittances | Commitments, attempts, and the payout ledger. See [Reconcile payments](/guides/reconcile-payments.md). | | Disputes and evidence | Debtor challenges and the documents that answer them. | | Documents and improve | Supporting files, evidence scoring, and what is missing from a collection file. | | Analytics, exports, statements | Per-creditor aggregates and generated reports. | | Settings, agreements, onboarding | Account configuration, MSA acceptance, verification state. | | `/partner/*` | The partner's own management surface. See [Platform partners](/rest-api/partner-model.md). | There is no cross-tenant surface. `/v1/admin/*` is operator-only and is not reachable by any integrator. ## Not exposed * **No `/v1/debtors` endpoints.** Debtor data is returned inside placements (`debtor` sub-object) and `GET /v1/analytics/top-debtors`. Filtering placements by `debtor_id` is not available. * **No creditor-side dispute creation.** Disputes are opened by the debtor. * **No payment-plan endpoint.** Plans are created through the voice and email agent flows and surface as a `PaymentCommitment` with installments. * **No hard-delete endpoint.** Tenant data is soft-deleted (`deleted_at`). A debtor-facing CPRA DSAR endpoint exists at `POST /v1/portal/dsar`. ## See also * [Quickstart](/getting-started/quickstart.md) * [Errors and limits](/getting-started/errors.md) * [Clients and MCP](/clients/clients.md) — including generating your own client from the spec --- # 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/conventions.md?ask=&goal= ``` `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.