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

# Sync Your Full Account Inventory with the Slate API

> Follow these steps to upsert accounts into Slate, store returned UUIDs, apply partial updates, and keep your full inventory continuously in sync.

Keeping your account inventory in sync with Slate ensures that balances, statuses, and metadata stay consistent across your collections workflows. Use the accounts API to upsert records on creation, update them on any change, and look them up by your own identifiers at any time.

<Note>
  The Accounts API is currently a **draft** — shapes, field names, and field sets may change before it is finalized.

  The `POST /v1/accounts` endpoint is fully idempotent on `crid`. Sending the same payload twice creates the record once and updates it in place on subsequent calls — safe to use in retry logic or batch pipelines.
</Note>

<Steps>
  <Step title="Prepare your account snapshot">
    Before calling the API, assemble the required fields for each account record. Every upsert must include:

    | Field            | Type   | Description                                                                                                       |
    | ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
    | `crid`           | string | Your internal identifier for the account                                                                          |
    | `creditorId`     | uuid   | The creditor this account belongs to. Register creditors via `POST /v1/creditors`; must be one your owner manages |
    | `status`         | enum   | `ACTIVE` or `CLOSED`                                                                                              |
    | `currentBalance` | string | Outstanding balance **in US dollars** as a decimal string (not cents)                                             |

    <Warning>
      Pass `currentBalance` as a decimal string — for example `"1250.75"`, not `1250.75` or `"125075"`. Monetary amounts are decimal strings; submitting values in cents will silently inflate every balance in Slate.
    </Warning>

    Include optional fields such as `accountNumber`, `portfolioId`, `chargeOffDate`, or `metadata` whenever they are available. The richer the snapshot, the less back-and-forth required downstream in legal workflows.

    <Note>
      `creditorId` references a creditor entity — register creditors first via `POST /v1/creditors` and list them with `GET /v1/creditors`. If you place accounts, a placement's `firmId` likewise references a firm registered via `POST /v1/firms`.
    </Note>
  </Step>

  <Step title="Upsert the account">
    Send a `POST /v1/accounts` request with your account payload. If an account with the same `crid` already exists, Slate updates it in place; otherwise it creates a new record.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.slate.inc/accounts/v1/accounts \
        -H 'Authorization: Bearer <token>' \
        -H 'Content-Type: application/json' \
        -d '{
          "crid": "ACC-00123",
          "creditorId": "3f9a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
          "status": "ACTIVE",
          "currentBalance": "1250.75",
          "accountNumber": "ACC-00123",
          "chargeOffDate": "2023-06-15"
        }'
      ```

      ```json Example Request Body theme={null}
      {
        "crid": "ACC-00123",
        "creditorId": "3f9a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
        "status": "ACTIVE",
        "currentBalance": "1250.75",
        "accountNumber": "ACC-00123",
        "chargeOffDate": "2023-06-15"
      }
      ```
    </CodeGroup>

    <Tip>
      Schedule a **daily full-inventory feed** that sends every account in your portfolio — even accounts with no changes. Because the endpoint is idempotent, re-sending unchanged records costs nothing and guarantees Slate never drifts from your system of record.
    </Tip>
  </Step>

  <Step title="Store the returned accountId">
    On success, Slate returns a `201 Created` response containing the canonical `accountId` UUID. Persist this value in your system; you will reference it in matters, payments, and legal filings.

    ```json Example Response theme={null}
    {
      "accountId": "7f3e1c2a-4b5d-4e8f-9012-3a4b5c6d7e8f",
      "owner": "acme-collections",
      "crid": "ACC-00123",
      "creditorId": "3f9a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
      "status": "ACTIVE",
      "currentBalance": "1250.75",
      "accountNumber": "ACC-00123",
      "chargeOffDate": "2023-06-15",
      "createdOn": "2024-01-15T10:30:00Z",
      "lastUpdated": "2024-01-15T10:30:00Z"
    }
    ```

    Map `crid → accountId` in your database so you can hydrate Slate UUIDs without an extra lookup on every subsequent API call.
  </Step>

  <Step title="Apply partial updates with PATCH">
    When a balance changes, a status transitions, or any single field needs updating, use `PATCH /v1/accounts/{accountId}` instead of re-sending the full payload. Include only the fields you want to change.

    <CodeGroup>
      ```bash Balance Update theme={null}
      curl -X PATCH https://api.slate.inc/accounts/v1/accounts/7f3e1c2a-4b5d-4e8f-9012-3a4b5c6d7e8f \
        -H 'Authorization: Bearer <token>' \
        -H 'Content-Type: application/json' \
        -d '{
          "currentBalance": "980.00"
        }'
      ```

      ```bash Status Update theme={null}
      curl -X PATCH https://api.slate.inc/accounts/v1/accounts/7f3e1c2a-4b5d-4e8f-9012-3a4b5c6d7e8f \
        -H 'Authorization: Bearer <token>' \
        -H 'Content-Type: application/json' \
        -d '{
          "status": "CLOSED"
        }'
      ```
    </CodeGroup>

    Partial updates are the preferred approach for high-frequency changes such as daily balance refreshes — they minimize payload size and reduce the risk of accidentally overwriting fields you did not intend to touch.
  </Step>

  <Step title="Look up accounts by crid">
    If you need to retrieve a Slate account record using your own identifier — for example, during reconciliation or when the `accountId` UUID is not cached locally — query the accounts list endpoint. `GET /v1/accounts` requires an `owner` query parameter, and filtering uses deep-object `filter[...]` syntax — for example `filter[crid]=ACC-00123`, `filter[status]=CLOSED`, or `filter[metadata][region]=west`.

    ```bash cURL theme={null}
    curl -X GET 'https://api.slate.inc/accounts/v1/accounts?owner=acme-collections&filter[crid]=ACC-00123' \
      -H 'Authorization: Bearer <token>'
    ```

    ```json Example Response theme={null}
    {
      "accounts": [
        {
          "accountId": "7f3e1c2a-4b5d-4e8f-9012-3a4b5c6d7e8f",
          "owner": "acme-collections",
          "crid": "ACC-00123",
          "creditorId": "3f9a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
          "status": "ACTIVE",
          "currentBalance": "980.00",
          "lastUpdated": "2024-01-16T08:00:00Z"
        }
      ],
      "pagination": {
        "totalCount": 1,
        "nextCursor": "",
        "previousCursor": ""
      }
    }
    ```

    The response returns an `accounts` array — use the first element for a one-to-one mapping, or iterate over multiple results if your filter matches more than one Slate account. Page through larger result sets with `cursor` (from a response's `pagination.nextCursor`/`pagination.previousCursor`, empty strings at the ends), `limit`, `orderBy`, and `orderDirection`.
  </Step>
</Steps>