## Add a document

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

Attach a document to a copy or one of its records, by uploading a file as multipart/form-data or by pointing at an external URL. Provide exactly one of the two.

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

### Path parameters

- `copy` (integer, required): The ID of the copy whose documents you are listing or adding to.

### Body parameters

- `documentable_type` (string, optional): The kind of record the document is attached to. One of copy, transaction, provenance_event, valuation, insurance_record, maintenance_record or loan. Defaults to copy.
- `documentable_id` (integer, optional): The ID of the record the document is attached to. Must belong to the copy in the path. Defaults to the copy itself.
- `type` (string, required): What the document is. One of receipt, invoice, certificate, appraisal, insurance, photograph, condition_report, restoration_report, catalogue, correspondence, ownership_record, authenticity_record or other.
- `name` (string, required): The display name of the document.
- `file` (file, optional): The file to store, sent as multipart/form-data. Provide either a file or an external_url, not both. A stored file may be up to 20 MB and must be a PDF, an image, or a common document or spreadsheet format.
- `external_url` (string, optional): A link to a file held elsewhere, used instead of uploading one. Provide either a file or an external_url.
- `description` (string, optional): A free note about the document.
- `issued_at` (string, optional): The date the document was issued, in YYYY-MM-DD format.
- `reference_number` (string, optional): An external reference such as an invoice or certificate number.

**Returns:** The created document object.

### Example request

```bash
curl https://getkollek.com/api/copies/1/documents \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "documentable_type": "valuation",
    "documentable_id": "5",
    "type": "appraisal",
    "name": "Appraisal report",
    "file": "@appraisal.pdf",
    "external_url": "https://drive.example.com/appraisal.pdf",
    "description": "Signed and dated by the appraiser.",
    "issued_at": "2024-01-01",
    "reference_number": "INV-2024-0117"
}'
```

### Example response

`Status: 201`

```json
{
    "data": {
        "type": "document",
        "id": "1",
        "attributes": {
            "documentable_type": "valuation",
            "documentable_id": "5",
            "document_type": "receipt",
            "name": "Appraisal report",
            "external_url": null,
            "download_url": "https://getkollek.com/api/documents/1",
            "mime_type": "application/pdf",
            "size": 248000,
            "description": "Signed and dated by the appraiser.",
            "issued_at": 1704067200,
            "reference_number": "INV-2024-0117",
            "created_at": 1752537600,
            "updated_at": 1752537600
        },
        "links": {
            "self": "https://getkollek.com/api/documents/1"
        }
    }
}
```