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

# Models

## The Posture object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"Posture":{"type":"string","enum":["preserve","escalate"],"description":"Negotiation posture. `preserve` is relationship-protecting with gentler cadence; `escalate` is firmer with faster cadence.\n"}}}}
```

## The PlacementStatus object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"PlacementStatus":{"type":"string","enum":["pending_enrichment","pending_compliance","in_outreach","pending_payment","paid","disputed","resolved","closed_uncollected","recalled"]}}}}
```

## The Compliance object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The NewDebtor object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"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"]}}}}}}
```

## The DebtorUpdate object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"DebtorUpdate":{"type":"object","properties":{"primary_email":{"type":"string","format":"email"},"primary_phone":{"type":"string"},"cease_and_desist":{"type":"boolean"},"attorney_representation":{"type":"boolean"},"bankruptcy_filed":{"type":"boolean"}}}}}}
```

## The Debtor object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"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"]}}}}}}
```

## The DebtorList object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"DebtorList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Debtor"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"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"]}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}
```

## The NewPlacement object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"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"]}}}}}}
```

## The Placement object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The PlacementList object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"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"}}},"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"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}
```

## The TimelineEvent object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The Call object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"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"}}}}}}}
```

## The EmailRecord object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"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"}}}}}}}}
```

## The AuditEvent object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The NewPayment object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"NewPayment":{"type":"object","required":["placement_id","amount","currency","method","received_at"],"properties":{"placement_id":{"type":"string","format":"uuid"},"amount":{"type":"number","format":"float"},"currency":{"type":"string"},"method":{"type":"string","enum":["ach_credit","wire","check","card","other"]},"received_at":{"type":"string","format":"date-time"},"external_reference":{"type":"string","description":"Your AR-side reference (e.g. wire confirmation number)."}}}}}}
```

## The Payment object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"Payment":{"allOf":[{"$ref":"#/components/schemas/NewPayment"},{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","applied","reversed"]},"created_at":{"type":"string","format":"date-time"}}}]},"NewPayment":{"type":"object","required":["placement_id","amount","currency","method","received_at"],"properties":{"placement_id":{"type":"string","format":"uuid"},"amount":{"type":"number","format":"float"},"currency":{"type":"string"},"method":{"type":"string","enum":["ach_credit","wire","check","card","other"]},"received_at":{"type":"string","format":"date-time"},"external_reference":{"type":"string","description":"Your AR-side reference (e.g. wire confirmation number)."}}}}}}
```

## The NewPaymentPlan object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"NewPaymentPlan":{"type":"object","required":["placement_id","installments","cadence"],"properties":{"placement_id":{"type":"string","format":"uuid"},"installments":{"type":"array","items":{"type":"object","required":["amount","due_date"],"properties":{"amount":{"type":"number","format":"float"},"due_date":{"type":"string","format":"date"}}}},"cadence":{"type":"string","enum":["weekly","biweekly","monthly"]}}}}}}
```

## The PaymentPlan object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"PaymentPlan":{"allOf":[{"$ref":"#/components/schemas/NewPaymentPlan"},{"type":"object","properties":{"plan_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","completed","defaulted"]},"created_at":{"type":"string","format":"date-time"}}}]},"NewPaymentPlan":{"type":"object","required":["placement_id","installments","cadence"],"properties":{"placement_id":{"type":"string","format":"uuid"},"installments":{"type":"array","items":{"type":"object","required":["amount","due_date"],"properties":{"amount":{"type":"number","format":"float"},"due_date":{"type":"string","format":"date"}}}},"cadence":{"type":"string","enum":["weekly","biweekly","monthly"]}}}}}}
```

## The NewDispute object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"NewDispute":{"type":"object","required":["placement_id","reason"],"properties":{"placement_id":{"type":"string","format":"uuid"},"reason":{"type":"string","enum":["goods_not_received","services_not_rendered","billing_error","bankruptcy","identity_theft","paid_already","other"]},"description":{"type":"string"},"evidence_urls":{"type":"array","items":{"type":"string","format":"uri"}}}}}}}
```

## The Dispute object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"Dispute":{"type":"object","properties":{"dispute_id":{"type":"string","format":"uuid"},"placement_id":{"type":"string","format":"uuid"},"reason":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["open","resolved"]},"resolution":{"type":"string","enum":["accepted_by_creditor","rejected","withdrawn"],"nullable":true},"opened_at":{"type":"string","format":"date-time"},"resolved_at":{"type":"string","format":"date-time","nullable":true}}}}}}
```

## The AnalyticsSummary object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"AnalyticsSummary":{"type":"object","properties":{"range":{"type":"string"},"total_placed":{"type":"number","format":"float"},"total_recovered":{"type":"number","format":"float"},"recovery_rate":{"type":"number","format":"float"},"average_days_to_recovery":{"type":"number","format":"float"},"age_buckets":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string"},"placed_amount":{"type":"number","format":"float"},"recovered_amount":{"type":"number","format":"float"},"recovery_rate":{"type":"number","format":"float"}}}}}}}}}
```

## The Pagination object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}
```

## The Error object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The ErrorEnvelope object

```json
{"openapi":"3.1.0","info":{"title":"Modern Collections API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```


---

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