## Create a loan

`POST https://getkollek.com/api/copies/{copy}/loans`

Record a loan against a copy.

**Permissions:** Owners and editors. Viewers get a 404 response.

### Path parameters

- `copy` (integer, required): The ID of the copy the loan belongs to.

### Body parameters

- `direction` (string, required): Which way custody moves. One of outgoing (a piece lent out) or incoming (a piece borrowed in).
- `status` (string, optional): Where the loan sits in its lifecycle. One of planned, active, overdue, returned, cancelled or lost. Defaults to active. Prefer the return endpoint over setting returned by hand, and leave overdue to be reached on its own.
- `party` (string, required): Who the copy was lent to or borrowed from.
- `purpose` (string, optional): Why the copy was loaned.
- `loaned_at` (string, required): The date the copy left or arrived, in YYYY-MM-DD format.
- `due_at` (string, optional): When the copy is expected back, in YYYY-MM-DD format. Leave it out for an open ended loan.
- `returned_at` (string, optional): When the loan was closed, in YYYY-MM-DD format. Usually set through the return endpoint rather than here.
- `item_condition_out_id` (integer, optional): The ID of the condition the copy was in when it left. Must be a condition of your account.
- `item_condition_in_id` (integer, optional): The ID of the condition the copy was in when it came back. Must be a condition of your account.
- `deposit_amount` (integer, optional): A deposit held against the loan, in the smallest currency unit (e.g. cents).
- `deposit_currency_code` (string, optional): The three letter currency code the deposit is expressed in. Defaults to the currency of the collection.
- `include_in_provenance` (boolean, optional): Whether the loan belongs to the object's story. When true, a matching provenance event is generated for the loan, and another for the return; setting it back to false removes them.

**Returns:** The created loan object.

### Example request

```bash
curl https://getkollek.com/api/copies/1/loans \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "outgoing",
    "status": "active",
    "party": "The Whitney Museum",
    "purpose": "Retrospective exhibition, east wing.",
    "loaned_at": "2024-01-01",
    "due_at": "2024-07-01",
    "returned_at": "2024-06-15",
    "item_condition_out_id": "1",
    "item_condition_in_id": "3",
    "deposit_amount": "250000",
    "deposit_currency_code": "USD",
    "include_in_provenance": "true"
}'
```

### Example response

`Status: 201`

```json
{
    "data": {
        "type": "loan",
        "id": "1",
        "attributes": {
            "copy_id": "1",
            "loan_provenance_event_id": null,
            "return_provenance_event_id": null,
            "direction": "outgoing",
            "status": "active",
            "party": "The Whitney Museum",
            "purpose": "Retrospective exhibition, east wing.",
            "loaned_at": 1704067200,
            "due_at": 1719792000,
            "returned_at": null,
            "item_condition_out_id": "1",
            "item_condition_in_id": null,
            "deposit_amount": 250000,
            "deposit_currency_code": "USD",
            "include_in_provenance": true,
            "created_at": 1752537600,
            "updated_at": 1752537600
        },
        "context": {
            "item_name": "Amazing Spider-Man #1",
            "copy_identifier": "CBX-042",
            "collection_name": "My Comics"
        },
        "links": {
            "self": "https://getkollek.com/api/copies/1/loans/1"
        }
    }
}
```