Skip to main content
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

​
Authorization
string
required
Bearer token obtained from your Clerk session. Example: Bearer eyJhbGc...
​
Content-Type
string
required
Must be application/json.

​
Request body

​
title
string
required
Display name for the document. Minimum 1 character, maximum 200 characters.
​
description
string
Optional longer description or notes. Maximum 2000 characters. Pass null or omit to leave unset.
​
chattelType
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.
​
loan
object
Attach a loan record to this document. Omit or pass null to create the document without a loan.

​
Response

Returns 201 Created with the newly created document.
​
document
object
required
The created document, identical in shape to documents returned by List documents.

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

​
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.
IDLabelDescription
leasehold_estateLeasehold estateTemporary use of land or building
vehicleTitled & registered vehiclesMotor vehicles, titled watercraft, aircraft, RVs — any road or serial-numbered unit
livestockLivestockFarm animals
furnitureFurnitureMovable home furnishings
appliancesAppliancesFreestanding appliances
electronicsElectronicsComputers, TVs, phones, audio
clothingClothingApparel and accessories
jewelryJewelryWearable valuables
artworkArtworkPaintings, sculpture, portable decor
toolsToolsHand and power tools
lawn_gardenLawn & gardenMowers, trimmers, patio items
sports_equipmentSports equipmentBikes, clubs, exercise gear
books_mediaBooks & mediaBooks, games, physical media
kitchenwareKitchenwareDishes, cookware, small items
bedding_linensBedding & linensSheets, towels, curtains on rods
musical_instrumentsMusical instrumentsPortable instruments
collectiblesCollectiblesCoins, cards, movable antiques
machineryMachineryFarm or industrial equipment (movable)
mobile_homeMobile homeManufactured home not affixed to land
boat_watercraftBoat / watercraftMotorboats, jet skis, canoes
aircraftAircraftPlanes, helicopters, personal drones
petsPets & domestic animalsHousehold animals
money_cashMoney & cashPhysical currency
stocks_bondsStocks & bondsCertificates and shares
bank_accountsBank accountsDeposit account rights
patentsPatentsInvention rights
trademarksTrademarksBrand identifiers
copyrightsCopyrightsCreative work rights
insurance_policiesInsurance policiesContractual coverage
promissory_notesPromissory notesWritten repayment promises
contracts_leasesContracts & leasesAgreement rights
cryptocurrencyCryptocurrencyDigital assets
camera_gearCameras & photo gearLenses, tripods, lighting
bicycles_scootersBicycles & scootersPedal and electric micromobility
household_decorHousehold decorLamps, rugs, freestanding mirrors
office_equipmentOffice equipmentMovable desks, printers, filing
garden_shedsGarden shedsPortable storage structures
portable_hot_tubPortable hot tubSpa not built in
caravans_trailersCaravans & trailersTowable units

​
Error cases

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