---
title: REST API – File Management
description: "Uploading a file involves several steps: create a document, upload the file, then link them. --- ## Step 1: Get the Folder's Webservice ID To create a document, you need the Webservice ID of the target folder. Use a `query`…"
url: "https://www.kafinea.com/en/help/api/rest-api-file-management/"
updated: "2026-04-03"
category: API
---

# REST API – File Management

Uploading a file involves several steps: create a document, upload the file, then link them.

---

## Step 1: Get the Folder's Webservice ID

To create a document, you need the Webservice ID of the target folder. Use a `query` operation:

**Curl example:**

```bash
curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=query&sessionName=YOUR_SESSION_ID&query=SELECT%20id%20FROM%20DocumentFolders%20WHERE%20foldername%20LIKE%20'Default'%20LIMIT%201%20;"
```

**Request:**

```sql
SELECT id FROM DocumentFolders WHERE foldername LIKE 'Default' LIMIT 1 ;
```

---

## Step 2: Create a Document Entity

Create a `Documents` type entity via the `create` operation.

> **POST** `https://apps.kafinea.com/{instance}/webservice.php`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `operation` | string | yes | Must be `create` |
| `sessionName` | string | yes | Session ID |
| `element` | JSON | yes | Document JSON object (see fields below) |
| `elementType` | string | yes | Must be `Documents` |

**`element` object fields:**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `notes_title` | string | yes | Document entity name |
| `folderid` | string | yes | Folder Webservice ID (step 1) |
| `filename` | string | yes | File name |
| `filetype` | string | yes | MIME type (e.g., `application/pdf`) |
| `filesize` | int | yes | File size in bytes |
| `filestatus` | int | yes | `1` for active |
| `filelocationtype` | string | yes | `I` for internal storage |
| `assigned_user_id` | string | yes | Assigned user's Webservice ID |

**Curl example:**

```bash
curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php 
  -d "operation=create" 
  -d "sessionName=YOUR_SESSION_ID" 
  -d 'element={"notes_title":"Mon document","folderid":"65x1","filename":"rapport.pdf","filetype":"application/pdf","filesize":12345,"filestatus":1,"filelocationtype":"I","assigned_user_id":"19x1"}' 
  -d "elementType=Documents"
```

---

## Step 3: Upload the file (FileUpload)

This operation uploads the file and links it to the created document. It can also be used alone to add images to products (replace `attachmentType` with `Image` and `parentId` with the product's Webservice ID).

> **POST** `https://apps.kafinea.com/{instance}/webservice.php`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `operation` | string | yes | Must be `FileUpload` |
| `sessionName` | string | yes | Session ID |
| `parentId` | string | yes | Document Webservice ID (step 2) |
| `attachmentType` | string | yes | `Attachment` for a file, `Image` for an image |
| `fileName` | string | yes | File name |
| `fileContents` | string | yes | File content encoded in base64 |

**Curl example:**

```bash
curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php 
  -d "operation=FileUpload" 
  -d "sessionName=YOUR_SESSION_ID" 
  -d "parentId=15x7890" 
  -d "attachmentType=Attachment" 
  -d "fileName=rapport.pdf" 
  -d "fileContents=$(base64 -w0 rapport.pdf)"
```

---

## Retrieve a file (files_retrieve)

Retrieves a file previously added to Kafinea. You need the WebserviceID of the **file** (not to be confused with that of the Document entity).

> **GET** `https://apps.kafinea.com/{instance}/webservice.php`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `operation` | string | yes | Must be `files_retrieve` |
| `sessionName` | string | yes | Session ID |
| `id` | string | yes | File Webservice ID |

**Curl example:**

```bash
curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=files_retrieve&sessionName=YOUR_SESSION_ID&id=28x5678"
```

---

## Related references 🔗

- [CRUD Operations](https://www.kafinea.com/en/documentation/api/rest-api-crud-operations/)
- [Related Operations](https://www.kafinea.com/en/documentation/api/rest-api-entity-relationships/)