> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slate.inc/llms.txt
> Use this file to discover all available pages before exploring further.
# Accounts API: Place and Sync Debt Inventory in Slate
> The Accounts API is the core of Slate. Upsert accounts by crid, track balances and lifecycle state, and place accounts with firms.
The Accounts API is currently a **draft**. Shapes, field names, and field sets may change before it is finalized.
An **account** is the primary entity Slate services against. Each account maps to a single debt account in your portfolio. It carries the consumer's balance, creditor information, placement details, and legal status. Every other Slate resource (files, signatures, QC reviews) is ultimately associated with an account, either directly or through a matter. Before you can use any other Slate API, you need accounts in the system.
## The Two-Identifier System
Slate uses two identifiers for every account, and understanding both are essential for a reliable integration.
**`accountId`** is a UUID that Slate assigns when an account is first created. It is stable, canonical, and used in all Slate URLs and relationships (for example, `GET /v1/accounts/{accountId}`). You will not know this value before the account exists. Slate returns it in the create/upsert response.
**`crid`** is the account number from your own system. You supply this value, and it must be unique within your owner. Use it as your lookup key when you do not yet have a Slate `accountId`. For example, on your first upsert or when reconciling records.
## The Upsert Pattern
`POST /v1/accounts` is idempotent. Send an account by `crid` and Slate will create it if it does not exist, or update it if it does. The response always includes the Slate-assigned `accountId`.
A `creditorId` is required, and it references a creditor you register beforehand via `POST /v1/creditors` (list them with `GET /v1/creditors`). A placement's `firmId` likewise references a firm you register via `POST /v1/firms`.
```bash theme={null}
curl --request POST \
--url "https://api.slate.inc/accounts/v1/accounts" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"crid": "ACCT-00123456",
"creditorId": "3f9a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
"currentBalance": "4872.50",
"status": "ACTIVE",
"placement": {
"firmId": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
"date": "2024-06-01"
}
}'
```
Response:
```json theme={null}
{
"accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"owner": "acme-collections",
"crid": "ACCT-00123456",
"creditorId": "3f9a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
"currentBalance": "4872.50",
"status": "ACTIVE",
"closedOn": null,
"matterId": null,
"placement": {
"firmId": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
"date": "2024-06-01"
},
"createdOn": "2024-06-20T14:30:00Z",
"lastUpdated": "2024-06-20T14:30:00Z"
}
```
Use the upsert endpoint as your **daily inventory feed**. Send your full current account state on each run. Slate handles the diff internally. You do not need to track which accounts are new versus existing. The upsert pattern takes care of that for you.
## Targeted Partial Updates
When you need to update a single field on a known account without re-sending the full record, use `PATCH /v1/accounts/{accountId}`:
```bash theme={null}
curl --request PATCH \
--url "https://api.slate.inc/accounts/v1/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"currentBalance": "3100.00"
}'
```
Only the fields you include in the PATCH body will be modified. All other account fields remain unchanged.
## Account Lifecycle
Every account has a `status` field with two possible values:
| Status | Meaning |
| -------- | ------------------------------------------------------------------------------------------------------ |
| `ACTIVE` | The account is live and being serviced. Default for newly placed accounts. |
| `CLOSED` | The account is no longer being actively serviced. No further placements or legal actions are expected. |
Update `status` to `CLOSED` via upsert or PATCH when an account is paid, recalled, or otherwise resolved.
## Money Format
All monetary amounts in Slate are expressed as US dollars with two decimal places, sent and returned as decimal **strings** — for example, `"1250.75"`. Slate does **not** use cents, integers, or bare JSON numbers. Strings avoid floating-point rounding. Sending `"125075"` when you mean `$1,250.75` will result in an incorrect balance nearly 100 times too large.
Always format currency values as a decimal string: `"4872.50"`, not `4872.50`, `"487250"`, or `"$4,872.50"`.
## Key Account Fields
| Field | Type | Description |
| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `crid` | string | Your internal account number. Required on upsert. Unique per owner. |
| `creditorId` | uuid | The creditor this account belongs to. References a creditor you register via `POST /v1/creditors`; must be one your owner manages. Required. |
| `currentBalance` | string | Outstanding balance in US dollars as a decimal string (for example, `"1250.75"`). |
| `status` | string | `ACTIVE` or `CLOSED`. |
| `accountNumber` | string | The current client/account number. May change over the life of the account. |
| `accountNumberHistory` | array | Read-only history of account-number changes, oldest first. Recorded automatically whenever `accountNumber` changes. |
| `portfolioId` | string | Identifier of the portfolio this account belongs to, when it is part of a purchased portfolio. |
| `chargeOffDate` | date | The date the account was charged off (ISO 8601 `YYYY-MM-DD`), if applicable. |
| `closedOn` | date | The date the account was closed; null while `ACTIVE`. |
| `matterId` | uuid | Read-only UUID of the current active matter for this account. |
| `metadata` | object | Custom key/value string pairs (Stripe-style) for attributes Slate does not model natively. Up to 50 keys. |
| `placement.firmId` | uuid | The firm currently handling the account. References a firm you register via `POST /v1/firms`. |
| `placement.date` | date | ISO 8601 date the account was placed with the firm. |
| `placement.feeStructure` | string | The fee arrangement for the placement. |
| `placement.feeRateType` | string | How the fee rate is expressed. |
| `placement.balance` | string | Balance at time of placement in US dollars, as a decimal string. |
| `legal.suit.filedDate` | date | Date the lawsuit was filed (ISO 8601 `YYYY-MM-DD`). |
| `legal.judgment.enteredDate` | date | Date the judgment was entered (ISO 8601 `YYYY-MM-DD`). |
| `legal.judgment.amount` | string | Judgment amount in US dollars, as a decimal string. |
| `createdOn` | datetime | Read-only ISO 8601 timestamp of when the account was first created in Slate. |
| `lastUpdated` | datetime | Read-only ISO 8601 timestamp of the most recent update to this account. |