# Record a loan

`POST /api/v1/vaults/{vault}/possessions/{possession}/loans`

Record a possession lent to a contact of its vault, or borrowed from one.

Name an existing contact with contact_id, or write a new one down with new_contact: the contact and the loan are then saved together, or neither is. A contact of another vault answers 404. The change is written to the account log.

A planned or active loan of a possession that is sold, given away, thrown away, lost or stolen answers 422 on status ("This possession is no longer in your hands, so only a returned loan can be recorded for it."). A second active loan answers 422 on status ("Another loan of this possession is active. Mark it as returned first."). A due day before the start answers 422 on due_on, and a returned loan without its return day answers 422 on returned_on ("Say when it came back.").

## Parameters

- `vault` (string, required): The vault the possession is kept in, named either by the readable name it reports as slug or by its id. A vault of another account answers 404.
- `possession` (uuid, required): The id of the possession. A possession of another vault or of another account answers 404.
- `direction` (string, required): lent or borrowed.
- `status` (string, required): planned, active or returned.
- `contact_id` (uuid, optional): The id of a contact of the vault. Required without new_contact.
- `new_contact` (object, optional): A contact to write down with the loan, as first_name (required) and last_name. Required without contact_id, and refused with it.
- `started_on` (date, required): The day the loan started, as YYYY-MM-DD.
- `due_on` (date, optional): The day it is due back, as YYYY-MM-DD. Not before started_on.
- `returned_on` (date, optional): The day it came back, as YYYY-MM-DD. Required for a returned loan, not before started_on, and ignored otherwise.
- `condition_out_id` (uuid, optional): The id of a possession condition of the account, the one it left in.
- `condition_back_id` (uuid, optional): The id of a possession condition of the account, the one it came back in. Kept only for a returned loan.
- `deposit_amount` (number, optional): A deposit left against the loan, from 0 to 9,999,999,999.99.
- `deposit_currency` (string, optional): The currency of the deposit, as a lowercase ISO code. Required with a deposit.
- `purpose` (string, optional): Why it was lent or borrowed, up to 5,000 characters. Markup is stripped.
- `is_in_provenance` (boolean, optional): Whether the loan records a change of custody in the provenance when it starts and another when it ends. False when left out.

## Returns

The new loan object.

- `data` (object): The possession loan.
- `data.type` (string): Always possession_loan. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.direction` (string): lent when the possession left your hands, borrowed when it came into them.
- `data.attributes.status` (string): planned, active or returned. A possession has at most one active loan.
- `data.attributes.is_overdue` (boolean): Whether the loan is active and its due day has passed, in the time zone of the person asking. It is worked out, never stored.
- `data.attributes.contact_id` (uuid): The id of the contact who has it or lent it, or null once that contact is deleted.
- `data.attributes.contact_name` (string): The name of that contact, or null once that contact is deleted.
- `data.attributes.started_on` (date): The day the loan started, as YYYY-MM-DD.
- `data.attributes.due_on` (date): The day it is due back, as YYYY-MM-DD, or null when no day was agreed.
- `data.attributes.returned_on` (date): The day it came back, as YYYY-MM-DD, or null unless the loan is returned.
- `data.attributes.condition_out_id` (uuid): The id of the possession condition it left in, or null.
- `data.attributes.condition_back_id` (uuid): The id of the possession condition it came back in, or null.
- `data.attributes.deposit_amount` (string): A deposit left against the loan, as a decimal with two places, or null.
- `data.attributes.deposit_currency` (string): The currency of the deposit, as a lowercase ISO code, or null without a deposit.
- `data.attributes.purpose` (string): Why it was lent or borrowed, or null.
- `data.attributes.is_in_provenance` (boolean): Whether the loan records a change of custody in the provenance when it starts and another when it ends.
- `data.attributes.created_at` (timestamp): When the loan was recorded, as a count of seconds since 1970.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.
- `data.links.web` (string): The Loans section of the possession in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/8a3d1f62-7b4e-4c95-a0e1-2f6c9b5d3e71/loans \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "direction": "lent",
      "status": "active",
      "contact_id": "7f1c3e58-9a24-4b6d-8c03-5e2a7d9f1b46",
      "started_on": "2026-11-01",
      "due_on": "2026-11-30",
      "deposit_amount": 50,
      "deposit_currency": "usd",
      "is_in_provenance": true
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/8a3d1f62-7b4e-4c95-a0e1-2f6c9b5d3e71/loans', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    direction: 'lent',
    status: 'active',
    contact_id: '7f1c3e58-9a24-4b6d-8c03-5e2a7d9f1b46',
    started_on: '2026-11-01',
    due_on: '2026-11-30',
    deposit_amount: 50,
    deposit_currency: 'usd',
    is_in_provenance: true,
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/8a3d1f62-7b4e-4c95-a0e1-2f6c9b5d3e71/loans', [
    'direction' => 'lent',
    'status' => 'active',
    'contact_id' => '7f1c3e58-9a24-4b6d-8c03-5e2a7d9f1b46',
    'started_on' => '2026-11-01',
    'due_on' => '2026-11-30',
    'deposit_amount' => 50,
    'deposit_currency' => 'usd',
    'is_in_provenance' => true,
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "possession_loan",
        "id": "b2e9f4c7-1a63-4d58-8e07-3c5d9a1f6b28",
        "attributes": {
            "direction": "lent",
            "status": "active",
            "is_overdue": false,
            "contact_id": "7f1c3e58-9a24-4b6d-8c03-5e2a7d9f1b46",
            "contact_name": "Dwight Schrute",
            "started_on": "2026-11-01",
            "due_on": "2026-11-30",
            "returned_on": null,
            "condition_out_id": "2e6b9d14-5c87-4a30-b9f2-1d4e8a6c3f57",
            "condition_back_id": null,
            "deposit_amount": "50.00",
            "deposit_currency": "usd",
            "purpose": "The beet harvest party at Schrute Farms.",
            "is_in_provenance": true,
            "created_at": 1773450000
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/8a3d1f62-7b4e-4c95-a0e1-2f6c9b5d3e71/loans/b2e9f4c7-1a63-4d58-8e07-3c5d9a1f6b28",
            "web": "https://my.monicahq.com/vaults/dunder-mifflin/possessions/8a3d1f62-7b4e-4c95-a0e1-2f6c9b5d3e71/loans"
        }
    }
}
```
