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

# Update an existing chattel document

> Modify the title, description, or chattel type of a document you own. All fields are optional — send only the fields you want to change.

`PATCH /v1/documents/:id` lets you update the metadata of a document you own. All body fields are optional; you only need to include the fields you want to change. Successfully updating a document triggers a `document.updated` event in your activity feed.

<Note>
  This endpoint updates document metadata only. To attach or modify the associated loan, use the create endpoint with a new document, or contact support for loan record changes.
</Note>

```http theme={null}
PATCH /v1/documents/:id
```

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

## Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the document to update. The document must be owned by your account; the API returns `404` for documents that do not exist or belong to another account.
</ParamField>

## Request body

All fields are optional. The API only modifies the fields you include in the request body.

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

<ParamField body="description" type="string or null">
  New description. Maximum 2000 characters. Pass `null` explicitly to clear an existing description.
</ParamField>

<ParamField body="chattelType" type="string">
  New chattel type classification ID. Must be one of the [valid chattel type IDs](/api/documents/create#chattel-types). Returns `400` if the value is not recognized.
</ParamField>

## Response

Returns `200 OK` with the updated document.

<ResponseField name="document" type="object" required>
  The full updated document object.

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

    <ResponseField name="title" type="string" required>
      Updated title.
    </ResponseField>

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

    <ResponseField name="chattelType" type="string" required>
      Updated chattel type ID.
    </ResponseField>

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

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

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

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

      <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.
        </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 Update title only theme={null}
  curl --request PATCH \
    --url https://your-api.example.com/v1/documents/doc_01j9z8x7w6v5u4t3s2r1q0p \
    --header 'Authorization: Bearer <your-session-token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "title": "2022 Ford F-150 — Revised Loan Package"
    }'
  ```

  ```bash Update multiple fields theme={null}
  curl --request PATCH \
    --url https://your-api.example.com/v1/documents/doc_01j9z8x7w6v5u4t3s2r1q0p \
    --header 'Authorization: Bearer <your-session-token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "title": "Jet Ski — Hull ID SC2209AA",
      "description": "Personal watercraft acquired at auction, title transferred April 2026",
      "chattelType": "boat_watercraft"
    }'
  ```

  ```bash Clear the description theme={null}
  curl --request PATCH \
    --url https://your-api.example.com/v1/documents/doc_01j9z8x7w6v5u4t3s2r1q0p \
    --header 'Authorization: Bearer <your-session-token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "description": null
    }'
  ```

  ```json Response 200 theme={null}
  {
    "document": {
      "id": "doc_01j9z8x7w6v5u4t3s2r1q0p",
      "title": "Jet Ski — Hull ID SC2209AA",
      "description": "Personal watercraft acquired at auction, title transferred April 2026",
      "chattelType": "boat_watercraft",
      "userId": "usr_clerk_abc123",
      "createdAt": "2026-03-15T10:30:00.000Z",
      "updatedAt": "2026-04-27T15:42:00.000Z",
      "loan": {
        "providerName": "First National Auto Finance",
        "originalAmount": 42500,
        "remainingAmount": 38200,
        "currency": "USD",
        "maturityDate": "2029-03-15",
        "status": "CURRENT"
      }
    }
  }
  ```
</CodeGroup>

***

## Error cases

| Status | Error message                         | Cause                                                                              |
| ------ | ------------------------------------- | ---------------------------------------------------------------------------------- |
| `400`  | `Invalid body.`                       | A field value fails schema validation, for example `title` exceeds 200 characters. |
| `400`  | `Invalid chattelType.`                | The `chattelType` value is not a recognized chattel type ID.                       |
| `401`  | `Missing Authorization Bearer token.` | No `Authorization` header was sent.                                                |
| `401`  | `Invalid or expired token.`           | The Bearer token is malformed or has expired.                                      |
| `404`  | `Not found.`                          | No document with the given `id` exists, or it belongs to a different account.      |