Build with the
B2B debt collection API.
Submit overdue invoices. Receive collection activity, payment, and remittance updates. Modern Collections runs the collection operation; this guide shows your team how to connect it to your product.
- Your platformAn overdue invoice
A customer authorizes a placement.
- Modern CollectionsThe collection file
Verification, outreach, disputes, and payments.
- Back in your productA status you can act on
Signed events and the current API record.
Choose how much your team builds.
Your interface. Our collection operation.
Create placements from your server, keep a link to each invoice, and translate signed events into updates your customers can read.
Your team
- Choose which invoices customers can submit and obtain their authorization.
- Keep API credentials on your server and scope each request to the correct creditor.
- Build the handoff, receive events, and show accurate status in your product.
Modern Collections
- Verify the creditor and apply the collection agreement and payout requirements.
- Enrich the file and check compliance before outreach as the collector of record.
- Handle collection activity and expose the file, payment, and remittance records.
Agree the creditor onboarding and signing-secret handoff with our team before building. Creating a creditor record alone does not authorize outreach.
From agreement to first placement.
Plan the creditor setup alongside the technical work. API access and a successful request do not replace verification or clearance to contact a debtor.
Agree the handoff
Confirm your partnership, creditor permissions, environment access, and the experience your team will own. Identify who supplies documents and handles creditor questions.
Your team + Modern CollectionsOnboard the creditor
Create or link the creditor, collect the required business and ownership information, and complete verification, the agreement, and payout setup. An invitation can bring the creditor into our hosted flow.
Each creditor is onboarded separatelySubmit a test placement
Use issued test access and test invoice data. Save the returned placement ID, handle review or validation responses, and confirm the right creditor owns the file.
API request or dashboard importProve the return path
Verify event signatures, handle duplicate delivery, and compare your displayed status with the current API record. Confirm readiness and operating coverage before enabling live placements.
Your receiver + our collection team
What can be handled through the partner API?
Partner endpoints can create linked creditors, report missing business-verification fields, submit verification, and invite a creditor to the hosted workflow. Agreement authority and payout setup depend on the approved onboarding arrangement. Confirm that arrangement with us before promising a fully embedded signup.
For placement requests with a partner key, X-MC-Creditor names the linked creditor by UUID or external reference. The partner must have the required authority. Each creditor remains separately scoped.
One invoice, in both directions.
A short preview of the request, response, and payment update.
Send the invoice and debtor details from your product.
{
"invoice_number": "INV-4210",
"invoice_amount": "4210.00",
"debtor": {
"company_name": "Example Supply Co.",
"primary_email": "ap@example.com"
}
}Request body excerpt. Authentication and creditor scope are covered in the API reference.
See complete requests and webhook handling
What does the placement request require?
The required fields are a positive invoice_amount and debtor.company_name. Send the invoice number, dates, contact details, and debtor state when available so the file is useful and the duplicate and compliance checks have context. The amount accepts up to two decimal places.
callback_url sets a public HTTPS destination for this placement’s events. It is optional when a creditor or partner default is configured. Obtain the relevant outbound signing secret during setup before accepting deliveries.
Use the events that actually happen.
A commitment, payment receipt, full recovery, and creditor payout are different states. Keep them separate in your customer experience.
placement.accepted- The placement was taken on and is ours to work.
placement.outreach_started- Outreach began on the file.
placement.resumed- Outreach restarted after a pause.
dispute.resolved- An open dispute was closed.
call.completed- A voice attempt finished, including voicemail or no answer.
placement.first_contact- First live contact on the placement.
placement.disputed- The debtor disputed the placement.
payment.commitment_made- A promise to pay or payment plan was agreed. Money has not necessarily arrived.
placement.status_changed- A status transition, including changes also covered by paid and closed events.
placement.paid- The placement is fully paid. This does not confirm a creditor payout.
placement.closed- A closure such as recall, withdrawal, or resolution outside collections.
placement.paused- Outreach stopped, with a categorized reason and affected channels.
placement.operator_message- An operator sent a note about this placement to the creditor or partner.
payment.received- A full or partial payment arrived, with fee and net amounts.
evidence.requested- Supporting documents are needed to improve the collection file.
dispute.evidence_requested- Documents are needed to answer a dispute.
evidence.received- Documents were supplied for an open request.
evidence.still_outstanding- A submission was reviewed and requested documents are still missing.
payment.succeeded- A debtor payment was captured, including partials.
payment.reversed- A captured payment was clawed back; amount is the positive reversal.
remittance.updated- A payout row was created or changed status.
evidence.fulfilled- The requested documents arrived and the ask was closed.
evidence.expired- An evidence ask passed its respond-by date unfulfilled.
The configured endpoint receives the event catalogue; filter the events you use in your receiver. Authenticated catalogue: GET /v1/partner/webhook-events.
Make the return path dependable.
Verify before acting.
Use the raw request body, the header timestamp, and the correct creditor’s outbound secret. Compare the signature in constant time and reject timestamps more than five minutes in the past or future. The JSON timestamp is for context; it is not the signature timestamp.
Accept once. Handle repeats.
After verification, save the delivery and queue the work durably, then return a 2xx response. Deduplicate with
X-Delivery-Id. Retries keep the same ID and body but receive a fresh signature timestamp. Make business updates idempotent too; paid and closed transitions also emit the generic status event.Recover from interruptions.
Timeouts, connection failures, 5xx responses, and 408/429 responses are retried with backoff. Other 4xx responses move to operator review. Use a direct HTTPS endpoint; redirects are not followed. Retrieve the current placement before reconciling a stale or out-of-order update.
Use the delivery ID to deduplicate a verified event, not as proof of authenticity. The signature covers the timestamp and raw body. Keep API keys and signing secrets on the server.
Handle the next response, too.
201Placement created- Save the placement ID and inspect warnings. Creation is separate from outreach clearance.
202Review required- Keep the intake review ID. A time-barred submission can be accepted for review without creating an actionable placement.
400 / 401 / 403Scope or access problem- Check the key, linked creditor, permission, and verification state. Fix access before retrying.
409Duplicate invoice- Look up the existing placement for this creditor and reconcile your record. Do not change the invoice number to bypass the duplicate guard.
422Invalid or unsupported input- Read the validation detail. Check field formats, amount precision, and the partner’s permitted operating scope.
For a timeout or 5xx on create, check whether the invoice already exists before resubmitting. The create endpoint does not provide a general Idempotency-Key contract. The CLI retries eligible reads, not create requests.
Can we use the CLI or an agent instead?
In Claude.ai or ChatGPT, add https://api.moderncollections.io/mcp as a custom connector and sign in with your Modern Collections dashboard login. No API key is needed, and you can disconnect it under Settings → Developer access → Connected apps.
Any other agent connects to the same URL with header Authorization: Bearer and the creditor API key from Settings → Developer access → API Key. The same card is at GET /v1/public/mcp and llms.txt. A partner key also sends X-MC-Creditor.
To file an invoice the user handed over: placement_create (this starts real outreach — confirm the company and amount first), then document_upload with the file, then document_process. placement_recall stops a placement that should not have been opened. The local package name is modern-collections. Do not install the PyPI project named mc-api; that is a different package. An agent still needs the creditor’s key or a signed-in connection; it does not bypass onboarding or compliance.