> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safeclose.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List chattel documents and portfolio stats

> Fetch all chattel documents owned by your account, ordered by most-recently updated, plus an aggregated stats summary of your document portfolio.

Two endpoints let you retrieve your document portfolio. `GET /v1/documents` returns the full list of documents with their associated loan data. `GET /v1/documents/stats` gives you a fast aggregate count — total documents, how many carry a loan, and how many of those loans are behind schedule.

## List documents

```http theme={null}
GET /v1/documents
```

Returns all documents owned by your authenticated account. Documents are ordered by `updatedAt` descending, so the most recently modified document appears first. Each document includes its associated loan record if one exists.

### Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from your Clerk session. Example: `Bearer eyJhbGc...`
</ParamField>

### Response

<ResponseField name="documents" type="object[]" required>
  Ordered list of document objects, newest first.

  <Expandable title="document properties">
    <ResponseField name="id" type="string" required>
      Unique document identifier.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Human-readable document title. Maximum 200 characters.
    </ResponseField>

    <ResponseField name="description" type="string or null" required>
      Optional longer description. `null` when not set.
    </ResponseField>

    <ResponseField name="chattelType" type="string" required>
      Classification ID for the type of chattel asset. See [valid chattel types](/api/documents/create#chattel-types).
    </ResponseField>

    <ResponseField name="userId" type="string">
      ID of the account that owns this document.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of when the document was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of the most recent update.
    </ResponseField>

    <ResponseField name="loan" type="object or null" required>
      Associated loan record, or `null` if no loan is attached.

      <Expandable title="loan properties">
        <ResponseField name="providerName" type="string" required>
          Name of the lending institution or loan provider.
        </ResponseField>

        <ResponseField name="originalAmount" type="number" required>
          Original principal amount of the loan, as a non-negative number.
        </ResponseField>

        <ResponseField name="remainingAmount" type="number" required>
          Current outstanding balance, as a non-negative number.
        </ResponseField>

        <ResponseField name="currency" type="string" required>
          ISO currency code, e.g. `"USD"`. Maximum 8 characters.
        </ResponseField>

        <ResponseField name="maturityDate" type="string or null" required>
          ISO 8601 date string for the loan maturity date, or `null` if not set.
        </ResponseField>

        <ResponseField name="status" type="string" required>
          Loan repayment status. One of `"CURRENT"` or `"BEHIND"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://your-api.example.com/v1/documents \
    --header 'Authorization: Bearer <your-session-token>'
  ```

  ```json Response theme={null}
  {
    "documents": [
      {
        "id": "doc_01j9z8x7w6v5u4t3s2r1q0p",
        "title": "2022 Ford F-150 Loan Package",
        "description": "Chattel documentation for dealer financing agreement",
        "chattelType": "vehicle",
        "userId": "usr_clerk_abc123",
        "createdAt": "2026-03-15T10:30:00.000Z",
        "updatedAt": "2026-04-22T14:55:00.000Z",
        "loan": {
          "providerName": "First National Auto Finance",
          "originalAmount": 42500,
          "remainingAmount": 38200,
          "currency": "USD",
          "maturityDate": "2029-03-15",
          "status": "CURRENT"
        }
      },
      {
        "id": "doc_02k0a9y8x7w6v5u4t3s2r1",
        "title": "Manufactured Home — Lot 14B",
        "description": null,
        "chattelType": "mobile_home",
        "userId": "usr_clerk_abc123",
        "createdAt": "2025-11-01T09:00:00.000Z",
        "updatedAt": "2026-04-10T08:20:00.000Z",
        "loan": null
      }
    ]
  }
  ```
</CodeGroup>

***

## Get document stats

```http theme={null}
GET /v1/documents/stats
```

Returns aggregate counts for your document portfolio. Use this endpoint to populate dashboard summary cards without loading the full document list.

### Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from your Clerk session.
</ParamField>

### Response

<ResponseField name="total" type="number" required>
  Total number of documents owned by your account.
</ResponseField>

<ResponseField name="withLoan" type="number" required>
  Number of documents that have an associated loan record.
</ResponseField>

<ResponseField name="behind" type="number" required>
  Number of documents whose loan has a status of `"BEHIND"`. These are candidates for RCM outreach.
</ResponseField>

### Example

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://your-api.example.com/v1/documents/stats \
    --header 'Authorization: Bearer <your-session-token>'
  ```

  ```json Response theme={null}
  {
    "total": 18,
    "withLoan": 12,
    "behind": 3
  }
  ```
</CodeGroup>

***

## Error cases

| Status | Error message                         | Cause                                         |
| ------ | ------------------------------------- | --------------------------------------------- |
| `401`  | `Missing Authorization Bearer token.` | No `Authorization` header was sent.           |
| `401`  | `Invalid or expired token.`           | The Bearer token is malformed or has expired. |