> 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-explorer/placements.md).
# Placements
Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on.
## List placements
> Returns a paginated list of placements. Use the filters to narrow by status, posture, debtor, or date range.
```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"tags":[{"name":"placements","description":"Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on."}],"servers":[{"url":"https://api.moderncollections.io/v1","description":"Production"},{"url":"https://sandbox.api.moderncollections.io/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as a Bearer token in the `Authorization` header."}},"parameters":{"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"Sort":{"name":"sort","in":"query","description":"Field to sort by. Prefix with `-` for descending (e.g. `-placed_at`).","schema":{"type":"string"}}},"schemas":{"Posture":{"type":"string","enum":["preserve","escalate"],"description":"Negotiation posture. `preserve` is relationship-protecting with gentler cadence; `escalate` is firmer with faster cadence.\n"},"PlacementList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Placement"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Placement":{"type":"object","properties":{"placement_id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string"},"invoice_amount":{"type":"number","format":"float"},"currency":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"days_past_due":{"type":"integer"},"posture":{"$ref":"#/components/schemas/Posture"},"status":{"$ref":"#/components/schemas/PlacementStatus"},"debtor_id":{"type":"string","format":"uuid"},"debtor":{"$ref":"#/components/schemas/Debtor"},"compliance":{"$ref":"#/components/schemas/Compliance"},"estimated_first_contact":{"type":"string","format":"date-time"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PlacementStatus":{"type":"string","enum":["pending_enrichment","pending_compliance","in_outreach","pending_payment","paid","disputed","resolved","closed_uncollected","recalled"]},"Debtor":{"allOf":[{"$ref":"#/components/schemas/NewDebtor"},{"type":"object","properties":{"debtor_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"placement_count":{"type":"integer"},"flags":{"type":"object","properties":{"cease_and_desist":{"type":"boolean"},"attorney_representation":{"type":"boolean"},"bankruptcy_filed":{"type":"boolean"}}}}}]},"NewDebtor":{"type":"object","required":["company_name","state"],"properties":{"company_name":{"type":"string"},"primary_domain":{"type":"string"},"primary_email":{"type":"string","format":"email"},"primary_phone":{"type":"string"},"state":{"type":"string","description":"Two-letter US state code."},"city":{"type":"string"},"zip":{"type":"string"},"entity_type":{"type":"string","enum":["corp","llc","sole_prop","partnership","other"]}}},"Compliance":{"type":"object","description":"The most recent compliance decision attached to the placement. Refreshed automatically before each outreach attempt.","properties":{"can_call":{"type":"boolean"},"can_email":{"type":"boolean"},"escalation_allowed":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"evaluated_at":{"type":"string","format":"date-time"}}},"TimelineEvent":{"type":"object","properties":{"event":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"previous_status":{"type":"string"},"new_status":{"type":"string"},"actor":{"type":"string"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["code","category","message"],"properties":{"code":{"type":"string"},"category":{"type":"string","enum":["invalid_request","authentication","authorization","not_found","conflict","compliance_refusal","rate_limit","server_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/placements":{"get":{"summary":"List placements","description":"Returns a paginated list of placements. Use the filters to narrow by status, posture, debtor, or date range.","tags":["placements"],"operationId":"listPlacements","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/Sort"},{"name":"status","in":"query","description":"Comma-separated list of statuses to include.","schema":{"type":"string"}},{"name":"posture","in":"query","description":"Filter by current posture.","schema":{"$ref":"#/components/schemas/Posture"}},{"name":"debtor_id","in":"query","description":"Restrict to placements for one debtor.","schema":{"type":"string","format":"uuid"}},{"name":"min_amount","in":"query","schema":{"type":"number","format":"float"}},{"name":"max_amount","in":"query","schema":{"type":"number","format":"float"}}],"responses":{"200":{"description":"A paginated page of placements.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacementList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Create a placement
> Files a new placement against the supplied debtor. The placement enters \`pending\_enrichment\`, then progresses through \`pending\_compliance\` to \`in\_outreach\` automatically.\
> \
> {% hint style="info" %}\
> Send a stable \`Idempotency-Key\` header (we recommend using your own invoice ID) so retries never create duplicates.\
> {% endhint %}
```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"tags":[{"name":"placements","description":"Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on."}],"servers":[{"url":"https://api.moderncollections.io/v1","description":"Production"},{"url":"https://sandbox.api.moderncollections.io/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as a Bearer token in the `Authorization` header."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"A stable client-supplied key. Retries with the same key are deduplicated server-side for at least 24 hours.","schema":{"type":"string"}}},"schemas":{"NewPlacement":{"type":"object","required":["invoice_number","invoice_amount","currency","due_date","debtor"],"properties":{"invoice_number":{"type":"string"},"invoice_amount":{"type":"number","format":"float"},"currency":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"posture":{"$ref":"#/components/schemas/Posture"},"callback_url":{"type":"string","format":"uri","description":"Per-placement webhook override. Falls back to the creditor default if omitted."},"notes":{"type":"string"},"debtor":{"$ref":"#/components/schemas/NewDebtor"}}},"Posture":{"type":"string","enum":["preserve","escalate"],"description":"Negotiation posture. `preserve` is relationship-protecting with gentler cadence; `escalate` is firmer with faster cadence.\n"},"NewDebtor":{"type":"object","required":["company_name","state"],"properties":{"company_name":{"type":"string"},"primary_domain":{"type":"string"},"primary_email":{"type":"string","format":"email"},"primary_phone":{"type":"string"},"state":{"type":"string","description":"Two-letter US state code."},"city":{"type":"string"},"zip":{"type":"string"},"entity_type":{"type":"string","enum":["corp","llc","sole_prop","partnership","other"]}}},"Placement":{"type":"object","properties":{"placement_id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string"},"invoice_amount":{"type":"number","format":"float"},"currency":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"days_past_due":{"type":"integer"},"posture":{"$ref":"#/components/schemas/Posture"},"status":{"$ref":"#/components/schemas/PlacementStatus"},"debtor_id":{"type":"string","format":"uuid"},"debtor":{"$ref":"#/components/schemas/Debtor"},"compliance":{"$ref":"#/components/schemas/Compliance"},"estimated_first_contact":{"type":"string","format":"date-time"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PlacementStatus":{"type":"string","enum":["pending_enrichment","pending_compliance","in_outreach","pending_payment","paid","disputed","resolved","closed_uncollected","recalled"]},"Debtor":{"allOf":[{"$ref":"#/components/schemas/NewDebtor"},{"type":"object","properties":{"debtor_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"placement_count":{"type":"integer"},"flags":{"type":"object","properties":{"cease_and_desist":{"type":"boolean"},"attorney_representation":{"type":"boolean"},"bankruptcy_filed":{"type":"boolean"}}}}}]},"Compliance":{"type":"object","description":"The most recent compliance decision attached to the placement. Refreshed automatically before each outreach attempt.","properties":{"can_call":{"type":"boolean"},"can_email":{"type":"boolean"},"escalation_allowed":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"evaluated_at":{"type":"string","format":"date-time"}}},"TimelineEvent":{"type":"object","properties":{"event":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"previous_status":{"type":"string"},"new_status":{"type":"string"},"actor":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["code","category","message"],"properties":{"code":{"type":"string"},"category":{"type":"string","enum":["invalid_request","authentication","authorization","not_found","conflict","compliance_refusal","rate_limit","server_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"responses":{"BadRequest":{"description":"The request was malformed or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"A resource with the supplied identifier already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ComplianceRefusal":{"description":"The request was rejected by the compliance engine.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/placements":{"post":{"summary":"Create a placement","description":"Files a new placement against the supplied debtor. The placement enters `pending_enrichment`, then progresses through `pending_compliance` to `in_outreach` automatically.\n\n{% hint style=\"info\" %}\nSend a stable `Idempotency-Key` header (we recommend using your own invoice ID) so retries never create duplicates.\n{% endhint %}\n","tags":["placements"],"operationId":"createPlacement","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewPlacement"}}}},"responses":{"201":{"description":"Placement created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Placement"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ComplianceRefusal"}}}}}}
```
## Retrieve a placement
> Returns the full placement detail, including the compliance block and the most-recent timeline entries.
```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"tags":[{"name":"placements","description":"Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on."}],"servers":[{"url":"https://api.moderncollections.io/v1","description":"Production"},{"url":"https://sandbox.api.moderncollections.io/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as a Bearer token in the `Authorization` header."}},"schemas":{"Placement":{"type":"object","properties":{"placement_id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string"},"invoice_amount":{"type":"number","format":"float"},"currency":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"days_past_due":{"type":"integer"},"posture":{"$ref":"#/components/schemas/Posture"},"status":{"$ref":"#/components/schemas/PlacementStatus"},"debtor_id":{"type":"string","format":"uuid"},"debtor":{"$ref":"#/components/schemas/Debtor"},"compliance":{"$ref":"#/components/schemas/Compliance"},"estimated_first_contact":{"type":"string","format":"date-time"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Posture":{"type":"string","enum":["preserve","escalate"],"description":"Negotiation posture. `preserve` is relationship-protecting with gentler cadence; `escalate` is firmer with faster cadence.\n"},"PlacementStatus":{"type":"string","enum":["pending_enrichment","pending_compliance","in_outreach","pending_payment","paid","disputed","resolved","closed_uncollected","recalled"]},"Debtor":{"allOf":[{"$ref":"#/components/schemas/NewDebtor"},{"type":"object","properties":{"debtor_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"placement_count":{"type":"integer"},"flags":{"type":"object","properties":{"cease_and_desist":{"type":"boolean"},"attorney_representation":{"type":"boolean"},"bankruptcy_filed":{"type":"boolean"}}}}}]},"NewDebtor":{"type":"object","required":["company_name","state"],"properties":{"company_name":{"type":"string"},"primary_domain":{"type":"string"},"primary_email":{"type":"string","format":"email"},"primary_phone":{"type":"string"},"state":{"type":"string","description":"Two-letter US state code."},"city":{"type":"string"},"zip":{"type":"string"},"entity_type":{"type":"string","enum":["corp","llc","sole_prop","partnership","other"]}}},"Compliance":{"type":"object","description":"The most recent compliance decision attached to the placement. Refreshed automatically before each outreach attempt.","properties":{"can_call":{"type":"boolean"},"can_email":{"type":"boolean"},"escalation_allowed":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"evaluated_at":{"type":"string","format":"date-time"}}},"TimelineEvent":{"type":"object","properties":{"event":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"previous_status":{"type":"string"},"new_status":{"type":"string"},"actor":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["code","category","message"],"properties":{"code":{"type":"string"},"category":{"type":"string","enum":["invalid_request","authentication","authorization","not_found","conflict","compliance_refusal","rate_limit","server_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/placements/{placement_id}":{"get":{"summary":"Retrieve a placement","description":"Returns the full placement detail, including the compliance block and the most-recent timeline entries.","tags":["placements"],"operationId":"getPlacement","responses":{"200":{"description":"Placement detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Placement"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## List calls on a placement
> Returns every voice call attempted on this placement with outcome, duration, and a link to the recording (where retained).
```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"tags":[{"name":"placements","description":"Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on."}],"servers":[{"url":"https://api.moderncollections.io/v1","description":"Production"},{"url":"https://sandbox.api.moderncollections.io/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as a Bearer token in the `Authorization` header."}},"schemas":{"Call":{"type":"object","properties":{"call_id":{"type":"string","format":"uuid"},"placement_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["outbound","inbound"]},"status":{"type":"string","enum":["scheduled","in_progress","completed","failed","no_answer","voicemail_left"]},"outcome":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"ended_at":{"type":"string","format":"date-time"},"duration_seconds":{"type":"integer"},"recording_url":{"type":"string","format":"uri","description":"Pre-signed URL with 1-hour expiry. Subject to per-state recording-consent rules."},"transcript_url":{"type":"string","format":"uri"},"compliance_flags":{"type":"array","items":{"type":"string"}}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["code","category","message"],"properties":{"code":{"type":"string"},"category":{"type":"string","enum":["invalid_request","authentication","authorization","not_found","conflict","compliance_refusal","rate_limit","server_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/placements/{placement_id}/calls":{"get":{"summary":"List calls on a placement","description":"Returns every voice call attempted on this placement with outcome, duration, and a link to the recording (where retained).","tags":["placements"],"operationId":"listPlacementCalls","responses":{"200":{"description":"An array of call records.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Call"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## List emails on a placement
> Returns every outbound email sent on this placement and every classified reply we've received.
```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"tags":[{"name":"placements","description":"Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on."}],"servers":[{"url":"https://api.moderncollections.io/v1","description":"Production"},{"url":"https://sandbox.api.moderncollections.io/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as a Bearer token in the `Authorization` header."}},"schemas":{"EmailRecord":{"type":"object","properties":{"email_id":{"type":"string","format":"uuid"},"placement_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["outbound","inbound"]},"subject":{"type":"string"},"from_address":{"type":"string","format":"email"},"to_address":{"type":"string","format":"email"},"sent_at":{"type":"string","format":"date-time"},"classification":{"type":"object","description":"For inbound replies: ML-classified intent and confidence.","properties":{"intent":{"type":"string"},"confidence":{"type":"number","format":"float"}}}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["code","category","message"],"properties":{"code":{"type":"string"},"category":{"type":"string","enum":["invalid_request","authentication","authorization","not_found","conflict","compliance_refusal","rate_limit","server_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/placements/{placement_id}/emails":{"get":{"summary":"List emails on a placement","description":"Returns every outbound email sent on this placement and every classified reply we've received.","tags":["placements"],"operationId":"listPlacementEmails","responses":{"200":{"description":"An array of email records.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EmailRecord"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Audit log for a placement
> Returns the full immutable audit timeline for the placement. Every state transition, compliance decision, outreach attempt, and admin action appears here.\
> \
> Add \`?format=csv\` to receive the response as \`text/csv\` — useful for compliance reviews.
```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"tags":[{"name":"placements","description":"Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on."}],"servers":[{"url":"https://api.moderncollections.io/v1","description":"Production"},{"url":"https://sandbox.api.moderncollections.io/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as a Bearer token in the `Authorization` header."}},"schemas":{"AuditEvent":{"type":"object","properties":{"audit_id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"actor":{"type":"string"},"previous_value":{"type":"string"},"new_value":{"type":"string"},"reason":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["code","category","message"],"properties":{"code":{"type":"string"},"category":{"type":"string","enum":["invalid_request","authentication","authorization","not_found","conflict","compliance_refusal","rate_limit","server_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/placements/{placement_id}/audit":{"get":{"summary":"Audit log for a placement","description":"Returns the full immutable audit timeline for the placement. Every state transition, compliance decision, outreach attempt, and admin action appears here.\n\nAdd `?format=csv` to receive the response as `text/csv` — useful for compliance reviews.\n","tags":["placements"],"operationId":"getPlacementAudit","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"An array of audit events.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}}},"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Recall a placement
> Recalls the placement and ceases all outreach immediately. Final state — recalled placements cannot be re-opened; file a new placement instead.
```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"tags":[{"name":"placements","description":"Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on."}],"servers":[{"url":"https://api.moderncollections.io/v1","description":"Production"},{"url":"https://sandbox.api.moderncollections.io/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as a Bearer token in the `Authorization` header."}},"schemas":{"Placement":{"type":"object","properties":{"placement_id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string"},"invoice_amount":{"type":"number","format":"float"},"currency":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"days_past_due":{"type":"integer"},"posture":{"$ref":"#/components/schemas/Posture"},"status":{"$ref":"#/components/schemas/PlacementStatus"},"debtor_id":{"type":"string","format":"uuid"},"debtor":{"$ref":"#/components/schemas/Debtor"},"compliance":{"$ref":"#/components/schemas/Compliance"},"estimated_first_contact":{"type":"string","format":"date-time"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Posture":{"type":"string","enum":["preserve","escalate"],"description":"Negotiation posture. `preserve` is relationship-protecting with gentler cadence; `escalate` is firmer with faster cadence.\n"},"PlacementStatus":{"type":"string","enum":["pending_enrichment","pending_compliance","in_outreach","pending_payment","paid","disputed","resolved","closed_uncollected","recalled"]},"Debtor":{"allOf":[{"$ref":"#/components/schemas/NewDebtor"},{"type":"object","properties":{"debtor_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"placement_count":{"type":"integer"},"flags":{"type":"object","properties":{"cease_and_desist":{"type":"boolean"},"attorney_representation":{"type":"boolean"},"bankruptcy_filed":{"type":"boolean"}}}}}]},"NewDebtor":{"type":"object","required":["company_name","state"],"properties":{"company_name":{"type":"string"},"primary_domain":{"type":"string"},"primary_email":{"type":"string","format":"email"},"primary_phone":{"type":"string"},"state":{"type":"string","description":"Two-letter US state code."},"city":{"type":"string"},"zip":{"type":"string"},"entity_type":{"type":"string","enum":["corp","llc","sole_prop","partnership","other"]}}},"Compliance":{"type":"object","description":"The most recent compliance decision attached to the placement. Refreshed automatically before each outreach attempt.","properties":{"can_call":{"type":"boolean"},"can_email":{"type":"boolean"},"escalation_allowed":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"evaluated_at":{"type":"string","format":"date-time"}}},"TimelineEvent":{"type":"object","properties":{"event":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"previous_status":{"type":"string"},"new_status":{"type":"string"},"actor":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["code","category","message"],"properties":{"code":{"type":"string"},"category":{"type":"string","enum":["invalid_request","authentication","authorization","not_found","conflict","compliance_refusal","rate_limit","server_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/placements/{placement_id}/recall":{"post":{"summary":"Recall a placement","description":"Recalls the placement and ceases all outreach immediately. Final state — recalled placements cannot be re-opened; file a new placement instead.","tags":["placements"],"operationId":"recallPlacement","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Optional creditor-supplied reason recorded in the audit log."}}}}}},"responses":{"200":{"description":"Placement recalled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Placement"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Change posture
> Switches a placement between \`preserve\` and \`escalate\` mid-flight. The change takes effect at the next outreach attempt.
```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"tags":[{"name":"placements","description":"Create, list, retrieve, and recall placements. A placement represents one overdue invoice we're collecting on."}],"servers":[{"url":"https://api.moderncollections.io/v1","description":"Production"},{"url":"https://sandbox.api.moderncollections.io/v1","description":"Sandbox"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as a Bearer token in the `Authorization` header."}},"schemas":{"Posture":{"type":"string","enum":["preserve","escalate"],"description":"Negotiation posture. `preserve` is relationship-protecting with gentler cadence; `escalate` is firmer with faster cadence.\n"},"Placement":{"type":"object","properties":{"placement_id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string"},"invoice_amount":{"type":"number","format":"float"},"currency":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"days_past_due":{"type":"integer"},"posture":{"$ref":"#/components/schemas/Posture"},"status":{"$ref":"#/components/schemas/PlacementStatus"},"debtor_id":{"type":"string","format":"uuid"},"debtor":{"$ref":"#/components/schemas/Debtor"},"compliance":{"$ref":"#/components/schemas/Compliance"},"estimated_first_contact":{"type":"string","format":"date-time"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PlacementStatus":{"type":"string","enum":["pending_enrichment","pending_compliance","in_outreach","pending_payment","paid","disputed","resolved","closed_uncollected","recalled"]},"Debtor":{"allOf":[{"$ref":"#/components/schemas/NewDebtor"},{"type":"object","properties":{"debtor_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"placement_count":{"type":"integer"},"flags":{"type":"object","properties":{"cease_and_desist":{"type":"boolean"},"attorney_representation":{"type":"boolean"},"bankruptcy_filed":{"type":"boolean"}}}}}]},"NewDebtor":{"type":"object","required":["company_name","state"],"properties":{"company_name":{"type":"string"},"primary_domain":{"type":"string"},"primary_email":{"type":"string","format":"email"},"primary_phone":{"type":"string"},"state":{"type":"string","description":"Two-letter US state code."},"city":{"type":"string"},"zip":{"type":"string"},"entity_type":{"type":"string","enum":["corp","llc","sole_prop","partnership","other"]}}},"Compliance":{"type":"object","description":"The most recent compliance decision attached to the placement. Refreshed automatically before each outreach attempt.","properties":{"can_call":{"type":"boolean"},"can_email":{"type":"boolean"},"escalation_allowed":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"evaluated_at":{"type":"string","format":"date-time"}}},"TimelineEvent":{"type":"object","properties":{"event":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"previous_status":{"type":"string"},"new_status":{"type":"string"},"actor":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":"object","required":["code","category","message"],"properties":{"code":{"type":"string"},"category":{"type":"string","enum":["invalid_request","authentication","authorization","not_found","conflict","compliance_refusal","rate_limit","server_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/placements/{placement_id}/posture":{"post":{"summary":"Change posture","description":"Switches a placement between `preserve` and `escalate` mid-flight. The change takes effect at the next outreach attempt.","tags":["placements"],"operationId":"updatePosture","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["posture"],"properties":{"posture":{"$ref":"#/components/schemas/Posture"}}}}}},"responses":{"200":{"description":"Posture updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Placement"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
---
# 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-explorer/placements.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.