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

# POST /v1/documents — create a chattel document

> Create a chattel document with an optional loan record. Accepts title, chattelType, description, and loan fields. Returns 201 with the new document.

`POST /v1/documents` creates a new chattel document in your account. You can optionally attach a loan record at creation time. The document immediately appears in your list and triggers a `document.created` event in your activity feed.

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

## Request headers

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

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

<ParamField body="title" type="string" required>
  Display name for the document. Minimum 1 character, maximum 200 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional longer description or notes. Maximum 2000 characters. Pass `null` or omit to leave unset.
</ParamField>

<ParamField body="chattelType" type="string" required>
  Classification ID for the type of chattel asset. Must be one of the valid chattel type IDs listed in the [chattel types table](#chattel-types) below. Returns `400` if the value is not recognized.
</ParamField>

<ParamField body="loan" type="object">
  Attach a loan record to this document. Omit or pass `null` to create the document without a loan.

  <Expandable title="loan properties">
    <ParamField body="providerName" type="string" required>
      Name of the lending institution or loan provider. Minimum 1 character, maximum 120 characters.
    </ParamField>

    <ParamField body="originalAmount" type="number" required>
      Original principal amount of the loan. Must be a non-negative number.
    </ParamField>

    <ParamField body="remainingAmount" type="number" required>
      Current outstanding balance. Must be a non-negative number.
    </ParamField>

    <ParamField body="currency" type="string" default="USD">
      ISO currency code. Maximum 8 characters. Defaults to `"USD"`. The value is stored uppercased.
    </ParamField>

    <ParamField body="maturityDate" type="string">
      Loan maturity date as an ISO 8601 date string (e.g. `"2029-06-30"`). Optional. Pass `null` or omit to leave unset.
    </ParamField>

    <ParamField body="status" type="string" default="CURRENT">
      Loan repayment status. One of `"CURRENT"` or `"BEHIND"`. Defaults to `"CURRENT"`.
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns `201 Created` with the newly created document.

<ResponseField name="document" type="object" required>
  The created document, identical in shape to documents returned by [List documents](/api/documents/list).

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

    <ResponseField name="title" type="string" required>
      The title you submitted.
    </ResponseField>

    <ResponseField name="description" type="string or null" required>
      The description you submitted, or `null`.
    </ResponseField>

    <ResponseField name="chattelType" type="string" required>
      The chattel type ID you submitted.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Your account ID.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of creation.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp, equal to `createdAt` on initial creation.
    </ResponseField>

    <ResponseField name="loan" type="object or null" required>
      The created loan record if you included `loan` in the request body, otherwise `null`.

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

        <ResponseField name="originalAmount" type="number" required>
          Original principal amount.
        </ResponseField>

        <ResponseField name="remainingAmount" type="number" required>
          Outstanding balance.
        </ResponseField>

        <ResponseField name="currency" type="string" required>
          ISO currency code, uppercased.
        </ResponseField>

        <ResponseField name="maturityDate" type="string or null" required>
          Loan maturity date or `null`.
        </ResponseField>

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

## Example

<CodeGroup>
  ```bash Request (with loan) theme={null}
  curl --request POST \
    --url https://your-api.example.com/v1/documents \
    --header 'Authorization: Bearer <your-session-token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "title": "2022 Ford F-150 Loan Package",
      "description": "Dealer financing agreement for VIN 1FTEW1EP4NFA00001",
      "chattelType": "vehicle",
      "loan": {
        "providerName": "First National Auto Finance",
        "originalAmount": 42500,
        "remainingAmount": 42500,
        "currency": "USD",
        "maturityDate": "2029-03-15",
        "status": "CURRENT"
      }
    }'
  ```

  ```bash Request (document only) theme={null}
  curl --request POST \
    --url https://your-api.example.com/v1/documents \
    --header 'Authorization: Bearer <your-session-token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "title": "Storage Unit Contents — Unit 42",
      "chattelType": "furniture"
    }'
  ```

  ```json Response 201 theme={null}
  {
    "document": {
      "id": "doc_01j9z8x7w6v5u4t3s2r1q0p",
      "title": "2022 Ford F-150 Loan Package",
      "description": "Dealer financing agreement for VIN 1FTEW1EP4NFA00001",
      "chattelType": "vehicle",
      "userId": "usr_clerk_abc123",
      "createdAt": "2026-04-27T12:00:00.000Z",
      "updatedAt": "2026-04-27T12:00:00.000Z",
      "loan": {
        "providerName": "First National Auto Finance",
        "originalAmount": 42500,
        "remainingAmount": 42500,
        "currency": "USD",
        "maturityDate": "2029-03-15",
        "status": "CURRENT"
      }
    }
  }
  ```
</CodeGroup>

***

## Chattel types

The `chattelType` field must be one of the following IDs. The API returns `400 { "error": "Invalid chattelType." }` if you submit a value not in this list.

| ID                    | Label                        | Description                                                                         |
| --------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| `leasehold_estate`    | Leasehold estate             | Temporary use of land or building                                                   |
| `vehicle`             | Titled & registered vehicles | Motor vehicles, titled watercraft, aircraft, RVs — any road or serial-numbered unit |
| `livestock`           | Livestock                    | Farm animals                                                                        |
| `furniture`           | Furniture                    | Movable home furnishings                                                            |
| `appliances`          | Appliances                   | Freestanding appliances                                                             |
| `electronics`         | Electronics                  | Computers, TVs, phones, audio                                                       |
| `clothing`            | Clothing                     | Apparel and accessories                                                             |
| `jewelry`             | Jewelry                      | Wearable valuables                                                                  |
| `artwork`             | Artwork                      | Paintings, sculpture, portable decor                                                |
| `tools`               | Tools                        | Hand and power tools                                                                |
| `lawn_garden`         | Lawn & garden                | Mowers, trimmers, patio items                                                       |
| `sports_equipment`    | Sports equipment             | Bikes, clubs, exercise gear                                                         |
| `books_media`         | Books & media                | Books, games, physical media                                                        |
| `kitchenware`         | Kitchenware                  | Dishes, cookware, small items                                                       |
| `bedding_linens`      | Bedding & linens             | Sheets, towels, curtains on rods                                                    |
| `musical_instruments` | Musical instruments          | Portable instruments                                                                |
| `collectibles`        | Collectibles                 | Coins, cards, movable antiques                                                      |
| `machinery`           | Machinery                    | Farm or industrial equipment (movable)                                              |
| `mobile_home`         | Mobile home                  | Manufactured home not affixed to land                                               |
| `boat_watercraft`     | Boat / watercraft            | Motorboats, jet skis, canoes                                                        |
| `aircraft`            | Aircraft                     | Planes, helicopters, personal drones                                                |
| `pets`                | Pets & domestic animals      | Household animals                                                                   |
| `money_cash`          | Money & cash                 | Physical currency                                                                   |
| `stocks_bonds`        | Stocks & bonds               | Certificates and shares                                                             |
| `bank_accounts`       | Bank accounts                | Deposit account rights                                                              |
| `patents`             | Patents                      | Invention rights                                                                    |
| `trademarks`          | Trademarks                   | Brand identifiers                                                                   |
| `copyrights`          | Copyrights                   | Creative work rights                                                                |
| `insurance_policies`  | Insurance policies           | Contractual coverage                                                                |
| `promissory_notes`    | Promissory notes             | Written repayment promises                                                          |
| `contracts_leases`    | Contracts & leases           | Agreement rights                                                                    |
| `cryptocurrency`      | Cryptocurrency               | Digital assets                                                                      |
| `camera_gear`         | Cameras & photo gear         | Lenses, tripods, lighting                                                           |
| `bicycles_scooters`   | Bicycles & scooters          | Pedal and electric micromobility                                                    |
| `household_decor`     | Household decor              | Lamps, rugs, freestanding mirrors                                                   |
| `office_equipment`    | Office equipment             | Movable desks, printers, filing                                                     |
| `garden_sheds`        | Garden sheds                 | Portable storage structures                                                         |
| `portable_hot_tub`    | Portable hot tub             | Spa not built in                                                                    |
| `caravans_trailers`   | Caravans & trailers          | Towable units                                                                       |

***

## Error cases

| Status | Error message                         | Cause                                                                                                             |
| ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `400`  | `Invalid body.`                       | The request body fails schema validation — a required field is missing or a field value exceeds its length limit. |
| `400`  | `Invalid chattelType.`                | The `chattelType` value is not in the list of valid chattel type IDs.                                             |
| `400`  | `Could not create document.`          | A database-level error prevented the document from being saved.                                                   |
| `401`  | `Missing Authorization Bearer token.` | No `Authorization` header was sent.                                                                               |
| `401`  | `Invalid or expired token.`           | The Bearer token is malformed or has expired.                                                                     |