Modern Collections

Playbooks for working this account: how to place, triage an AR aging, and more. Call with no ``topic`` for the list; call with a topic name for its full text.

guide

List disputes across the portfolio, optionally filtered by placement or status.

dispute_list

Document asks we need from the creditor or AR platform. Fulfill by uploading files with document_upload. Email is also sent. An ask has no deadline and does not expire (``due_at`` is always null).

evidence_request_list

Partner keys: the creditors you act for. Run this first with a partner key. Each row has ``creditor_id``, ``name`` and ``external_creditor_ref``. Pass one of those as ``creditor`` on every other call to act for that creditor. ``q`` searches by name.

partner_creditor_list

Partner keys: open document asks across every creditor you act for. Each row names the creditor, the invoice and the documents we need. An ask has no deadline and does not expire (``due_at`` is always null): it stays open until the documents arrive or we withdraw it. Upload with document_upload, passing that row's creditor.

partner_evidence_request_list

List payment commitments and attempts across this creditor's placements. ``commitments`` and ``attempts`` are each a page (``items``, ``limit``, ``offset``, ``total``); ``limit`` / ``offset`` cut both.

payment_list

List every document filed on one placement, with per-row processing status.

placement_documents

Find placements. Use this to turn a company name or invoice number into an id. ``q`` matches the debtor company name or the invoice number. ``status`` is a comma-separated filter (e.g. ``in_outreach,disputed``). ``sort`` is ``placed_at``, ``invoice_amount``, ``days_past_due``, ``status`` or ``updated_at``, with a leading ``-`` for descending (default newest first). ``outreach_phase`` is ``hunt`` (still finding the right contact) or ``engaged``. ``updated_since`` (ISO 8601 with a timezone offset, e.g. ``2026-10-01T12:00:00Z``) returns only placements changed strictly after that instant, oldest change first: the catch-up read after a missed webhook. To resume, pass the last row's ``updated_at`` as ``updated_since`` and its ``id`` as ``after_id``, so rows changed at the same instant are not skipped.

placement_list

List the creditor's remittance ledger — money collected and owed back to them.

remittance_list

List the creditor's monthly statements.

statement_list

What happened on an account: calls, emails, payments, disputes, edits. ``view`` defaults to ``summary`` (the events a creditor acts on); ``full`` adds the platform's own bookkeeping rows. ``event_type`` is a comma-separated filter; ``actor`` filters by who acted; ``since`` / ``until`` are ISO timestamps. Keyset-paginated with ``cursor``.

audit_query

Read back the data extracted from a placement's documents. The aggregated, source-cited view built from every confirmed document fact on the placement — the extracted invoice fields, contradictions between documents, and the items still missing. This is how you check what the platform actually read off an uploaded invoice before correcting anything with placement_amend. Returns null until the first document has been processed.

placement_context

Recall a placement — stop all further outreach on it, immediately. Use when the debt is settled outside the platform, the invoice was placed in error, or the creditor asks for collection to stop. This is the counterpart to placement_create: an agent that can place an invoice must be able to recall it.

placement_recall

Record a payment the debtor made directly to the creditor. Stops outreach. ``amount`` is a positive decimal string. Pass the bank reference or remittance id as ``idempotency_key`` when the user has one. Without it a key is derived from the placement, the amount and today's date (UTC), so a retried call replays instead of recording the payment twice. Two separate payments of the same amount on the same day need two different keys.

payment_record

Close a dispute out. ``resolution`` is 'denied', 'upheld', or 'withdrawn'. This has real side effects — it can resume outreach and release a remittance hold — so it is separate from dispute_acknowledge, which only marks the dispute as being reviewed. ``note`` is required (2-2000 characters) and is retained on the record. Resolve only when the user tells you to. 'denied' is refused with 409 ``answer_required`` until an answer to the debtor is on record for the dispute. 'withdrawn' on a dispute with no answer on record ends the dispute and leaves outreach paused.

dispute_resolve

Save the company details that business verification checks. Returns the checklist. Pass only what the user gave you; a field left out is left alone, so the details can be saved a few at a time. ``legal_name`` is the registered legal name, ``ein`` the nine-digit US tax ID (12-3456789), ``industry`` a short description, ``state_of_incorporation`` a two-letter US state. The address is saved as a whole: pass line1, city, state and postal code together. Read the values back to the user before saving: they are checked against the business registry, and they lock once verification starts (409). No tool returns the EIN afterwards. A partner connection saves them for a creditor it holds: pass ``creditor``.

account_setup_update

Set a placement's collection posture: 'preserve' or 'escalate'. ``preserve`` softens outreach to protect the commercial relationship; ``escalate`` pursues the debt more assertively.

placement_set_posture

Show a document to the debtor in their payment portal (or hide it again). The debtor will see the file. Confirm with the user which document and placement first. ``reviewed_content_hash`` pins the exact bytes reviewed. A processed PDF or image may be shared when either its classified type or the type declared at upload is an invoice, contract, statement of work, purchase order, proof of delivery or service, or statement of account.

document_share_with_debtor

Correct the debtor's contact details on a placement. Only the fields passed are changed. A contact change re-runs the compliance decision, so fixing a wrong phone number or state can re-open outreach on a placement that was blocked from being worked.

placement_update_debtor

Upload a supporting document (invoice, contract, delivery proof, ...) to the file. Pass exactly one of ``content_base64`` (base64-encoded bytes), ``content_text`` (plain text such as an email body), or ``file_path`` (local stdio only, and only inside ``MC_API_MCP_UPLOAD_ROOT``). If the user has the file on their computer and you cannot read it, use document_upload_link instead and give them the link. Read by the platform: PDF (≤10MB), PNG/JPG (≤5MB), plain text / HTML / .eml / JSON (≤2MB), and Word (.docx), Excel (.xlsx/.xls), CSV, Outlook (.msg), RTF, WebP, TIFF and HEIC (≤10MB, converted on our side); the bytes must really be the declared type. Any other file up to 10MB is stored but not read (``status`` ``uploaded``). ``placement_id`` attaches it to a placement directly; without it the platform auto-matches the document to a placement. ``document_type`` (e.g. 'invoice', 'contract') records your type hint; the platform's classification remains authoritative, but the declared type is kept (``declared_document_type``) and lets the user share the file with the debtor even when the classifier read it differently. ``share_with_debtor=True`` shows the file to the debtor in their payment portal once it is processed, if it is a shareable document on the placement; ``debtor_share_note`` on the document says why it is not shown yet. The debtor will see the file: confirm with the user first. Re-uploading the same bytes is safe — the API returns the existing document flagged ``metadata.duplicate``.

document_upload

Get a short-lived browser link the user opens to upload files onto a placement. Use it when the user has the file on their computer and you cannot read it (for example in a chat app). Give the user the ``url``: they open it, choose the file, and it is filed on the placement. It works for several files until ``expires_at`` (30 minutes by default, at most 60) and needs no login, so give it only to the user and never post it anywhere else. ``document_type`` (e.g. 'invoice') is recorded on every file sent through it. ``share_with_debtor=True`` shows every file sent through it to the debtor once processed, if it is a shareable document (confirm with the user first).

document_upload_link

Start here. Which account this key reaches, and what blocks placing. Creditor account: the account name and id, status, whether business verification (KYB) cleared, whether the agreement is accepted and payouts are linked, and a plain-English ``blocking`` list. Partner account: every linked creditor, with the ``creditor_id`` / ``external_creditor_ref`` to pass as ``creditor`` on later calls. ``credential`` says whether this connection signed in or uses an API key. Call it first, and whenever a call fails with 401 or 403.

account_whoami