POST /v1/documents — create a chattel 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.

POST /v1/documents

Request headers

string

required

Bearer token obtained from your Clerk session. Example: Bearer eyJhbGc...

string

required

Must be application/json.

Request body

string

required

Display name for the document. Minimum 1 character, maximum 200 characters.

string

Optional longer description or notes. Maximum 2000 characters. Pass null or omit to leave unset.

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 below. Returns 400 if the value is not recognized.

object

Attach a loan record to this document. Omit or pass null to create the document without a loan.

Show loan properties

string

required

Name of the lending institution or loan provider. Minimum 1 character, maximum 120 characters.

number

required

Original principal amount of the loan. Must be a non-negative number.

number

required

Current outstanding balance. Must be a non-negative number.

string

default:"USD"

ISO currency code. Maximum 8 characters. Defaults to "USD". The value is stored uppercased.

string

Loan maturity date as an ISO 8601 date string (e.g. "2029-06-30"). Optional. Pass null or omit to leave unset.

string

default:"CURRENT"

Loan repayment status. One of "CURRENT" or "BEHIND". Defaults to "CURRENT".

Response

Returns 201 Created with the newly created document.

object

required

The created document, identical in shape to documents returned by List documents.

Show document properties

string

required

Unique document identifier assigned by the API.

string

required

The title you submitted.

string or null

required

The description you submitted, or null.

string

required

The chattel type ID you submitted.

string

Your account ID.

string

required

ISO 8601 timestamp of creation.

string

required

ISO 8601 timestamp, equal to createdAt on initial creation.

object or null

required

The created loan record if you included loan in the request body, otherwise null.

Show loan properties

string

required

Name of the lending institution.

number

required

Original principal amount.

number

required

Outstanding balance.

string

required

ISO currency code, uppercased.

string or null

required

Loan maturity date or null.

string

required

"CURRENT" or "BEHIND".

Example

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"
    }
  }'

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"
  }'

{
  "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"
    }
  }
}

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.

Overview

Documents

Signing

Workspace

POST /v1/documents — create a chattel document

Request headers

Request body

Response

Example

Chattel types

Error cases

​Request headers

​Request body

​Response

​Example

​Chattel types

​Error cases

Request headers

Request body

Response

Example

Chattel types

Error cases