# Kiteworks API — requestFile Operations

**11 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/requestFile.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/requestFile.json)

> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.

---

## POST /rest/folders/{id}/actions/requestFile

**Summary:** Send a Request File to Folder request

### Description:
  Initiates a Request File to Folder.
### Precondition:
  The user profile must have the necessary access rights to request files to the folder.
### Response:
  Successfully creates a request file and returns the request file details.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the entity. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `to` | string[] | yes | List of email addresses to send the files to. |
| `subject` | string | yes | Subject of the email. Must be between 1 and 998 characters. |
| `body` | string | no | The body of the email. |
| `expire` | string | no | The expiration date of the request file link. |
| `count` | integer | no | The maximum number of files to attach. |
| `requireAuth` | boolean | no | Indicates if authentication is required to access the files. |
| `files` | string[] | no | List of object GUIDs representing the files to be sent. |
| `actionId` | integer | no | The action to allow recipients to perform on viewable files. `1` – View only. `2` – View and download. |
| `showToken` | integer | no | Whether to include the request file token in the response. `0` – Do not include the token. `1` – Include the token. |

**Responses:**

| Code | Description |
|------|-------------|
| 201 | Request File to Folder request has been successfully created. |
| 400 | Bad Request  <i>Possible error codes: </i>ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND, ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST, ERR_LICENSE_MAX_USERS_COUNT_REACHED, ERR_USER_HAS_NO_USER_TYPE, ERR_USER_TYPE_NO_ACCESS |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_HYPERLINK, ERR_INPUT_INVALID_DATE, ERR_INPUT_REQUIRED, ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**400 (ERR_REQUEST_INVALID_JSON):**

```json
{
  "errors": [
    {
      "code": "ERR_REQUEST_INVALID_JSON",
      "message": "Invalid json provided"
    }
  ]
}
```

**401 (ERR_AUTH_INVALID_CSRF):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_INVALID_CSRF",
      "message": "Invalid CSRF Authentication"
    }
  ]
}
```

**401 (ERR_AUTH_UNAUTHORIZED):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_UNAUTHORIZED",
      "message": "Unauthorized"
    }
  ]
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": [
    {
      "code": "ERR_ACCESS_USER",
      "message": "Insufficient access permissions"
    }
  ]
}
```

**403 (ERR_ENTITY_DELETED):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_DELETED",
      "message": "Entity is deleted"
    }
  ]
}
```

**403 (ERR_ENTITY_DLP_LOCKED):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_DLP_LOCKED",
      "message": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance."
    }
  ]
}
```

**403 (ERR_ENTITY_IS_SECURE_FOLDER):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_IS_SECURE_FOLDER",
      "message": "Operation not permitted on restricted Folder."
    }
  ]
}
```

**403 (ERR_ENTITY_NOT_SCANNED):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_NOT_SCANNED",
      "message": "One or more files are undergoing security and privacy scans. Please try again later."
    }
  ]
}
```

**403 (ERR_ENTITY_VIRUS_FOUND):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_VIRUS_FOUND",
      "message": "File is infected"
    }
  ]
}
```

**403 (ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST",
      "message": "Distribution list user is not allowed to register"
    }
  ]
}
```

**403 (ERR_LICENSE_MAX_USERS_COUNT_REACHED):**

```json
{
  "errors": [
    {
      "code": "ERR_LICENSE_MAX_USERS_COUNT_REACHED",
      "message": "License count has been reached"
    }
  ]
}
```

**403 (ERR_USER_HAS_NO_USER_TYPE):**

```json
{
  "errors": [
    {
      "code": "ERR_USER_HAS_NO_USER_TYPE",
      "message": "User has no profile"
    }
  ]
}
```

**403 (ERR_USER_TYPE_NO_ACCESS):**

```json
{
  "errors": [
    {
      "code": "ERR_USER_TYPE_NO_ACCESS",
      "message": "Permission denied"
    }
  ]
}
```

**422 (ERR_INPUT_HYPERLINK):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_HYPERLINK",
      "message": "Not allowed hyperlink domain. Hyperlink domain should not different from anchored text domain."
    }
  ]
}
```

**422 (ERR_INPUT_INVALID_DATE):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_INVALID_DATE",
      "message": "The input is not a valid date."
    }
  ]
}
```

**422 (ERR_INPUT_REQUIRED):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_REQUIRED",
      "message": "Field is required"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

```json
{
  "errors": [
    {
      "code": "ERR_INVALID_PARAMETER",
      "message": "Invalid Parameter Exception"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/folders/:id/actions/requestFile" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "to": [
         "string"
       ],
         "subject": "string",
         "body": "string",
         "expire": "2024-01-15",
         "count": 1,
         "requireAuth": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier (UUID) of the entity.

url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/requestFile"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "to": [
  "string"
],
  "subject": "string",
  "body": "string",
  "expire": "2024-01-15",
  "count": 1,
  "requireAuth": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/requestFile/{ref}

**Summary:** Returns Request File Info by ref

### Description:
  Retrieves detailed information about a Request File using the provided reference (ref).
### Precondition:
  The user must have valid authentication and appropriate access to view the request file information.
### Response:
  Returns the details of the specified request file, including its associated metadata and status.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `read` | query | no | Indicates whether to log the view event. Defaults to true. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The Request File Info, including the details of the specified request file. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_REQUEST_FILE, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_REQUEST_FILE_EXPIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**401 (ERR_AUTH_INVALID_CSRF):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_INVALID_CSRF",
      "message": "Invalid CSRF Authentication"
    }
  ]
}
```

**401 (ERR_AUTH_REQUEST_FILE):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_REQUEST_FILE",
      "message": "Operation not permitted. This request requires authorization"
    }
  ]
}
```

**401 (ERR_AUTH_UNAUTHORIZED):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_UNAUTHORIZED",
      "message": "Unauthorized"
    }
  ]
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": [
    {
      "code": "ERR_ACCESS_USER",
      "message": "Insufficient access permissions"
    }
  ]
}
```

**403 (ERR_ENTITY_DELETED):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_DELETED",
      "message": "Entity is deleted"
    }
  ]
}
```

**403 (ERR_ENTITY_REQUEST_FILE_EXPIRED):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_REQUEST_FILE_EXPIRED",
      "message": "The request file has expired"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## DELETE /rest/requestFile/{ref}

**Summary:** Expire a request file link

Marks the request file link as expired, preventing any further file uploads through it. **Requires the authenticated user to be the user who created the request file link.**

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The request file link was successfully expired. Returns no content. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```

---

## GET /rest/requestFile/{ref}/preview/{object_id}

**Summary:** Get preview metadata for a source file

Gets the preview metadata for a source file attached to the request file link. If the source file's action is set to `view`, the preview is generated with the Viewer role.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `object_id` | path | yes | The unique identifier (UUID) of the source file. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the preview metadata for the specified source file. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Preview ready):**

```json
{
  "link": "/preview/files/7/preview.html",
  "pdf": null,
  "view_url": "https://viewer.example.com/view?token=abc123",
  "status": "Preview",
  "mime": "application/pdf",
  "native": true,
  "watermark": null,
  "tdfOriginalExtension": null
}
```

**200 (Preview processing):**

```json
{
  "link": null,
  "pdf": null,
  "view_url": null,
  "status": "Processing",
  "mime": null,
  "native": false,
  "watermark": null,
  "tdfOriginalExtension": null
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref/preview/:object_id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.
object_id = "VALUE"  # The unique identifier (UUID) of the source file.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/preview/{object_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## GET /rest/requestFile/{ref}/sources

**Summary:** Get source files attached by the requester

Returns the list of files the requester attached to the request file link for the uploader to view or download. Each entry includes computed permissions based on DLP policy and the configured action (`view` or `download`).

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of source file records attached to the request file link. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Source file list):**

```json
{
  "data": [
    {
      "id": 1,
      "file_id": 7,
      "requestfile_id": 12,
      "action_id": 1,
      "permissions": [
        {
          "name": "view",
          "enabled": true
        },
        {
          "name": "download",
          "enabled": false
        }
      ]
    },
    {
      "id": 2,
      "file_id": 8,
      "requestfile_id": 12,
      "action_id": 2,
      "permissions": [
        {
          "name": "view",
          "enabled": true
        },
        {
          "name": "download",
          "enabled": true
        }
      ]
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 20
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref/sources" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/sources"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## GET /rest/requestFile/{ref}/sources/{object_id}

**Summary:** Get source file metadata

Gets the file metadata for a specific source file attached to the request file link.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `object_id` | path | yes | The unique identifier (UUID) of the source file. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the file metadata for the specified source file. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Source file metadata):**

```json
{
  "id": 7,
  "name": "onboarding-checklist.pdf",
  "parent_id": 3,
  "size": 102400,
  "mime": "application/pdf",
  "created": "2024-01-10T09:00:00+00:00",
  "modified": "2024-03-01T14:30:00+00:00",
  "deleted": false,
  "locked": 0
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref/sources/:object_id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.
object_id = "VALUE"  # The unique identifier (UUID) of the source file.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/sources/{object_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## GET /rest/requestFile/{ref}/uploads

**Summary:** Get files uploaded by the current user

Returns the list of files the currently authenticated user has uploaded for the specified request file link. Returns an empty list when the link does not require authentication (`require_auth=false`).

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of upload records for the current user. Returns `{data: []}` when the link does not require authentication. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Upload list):**

```json
{
  "data": [
    {
      "id": 10,
      "file_id": 55,
      "requestfile_id": 12
    },
    {
      "id": 11,
      "file_id": 56,
      "requestfile_id": 12
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 20
}
```

**200 (No auth required):**

```json
{
  "data": []
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref/uploads" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/uploads"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## GET /rest/requestFile/{ref}/uploads/{object_id}

**Summary:** Get uploaded file metadata

Gets the file metadata for a specific file uploaded through the request file link. Only accessible when the link requires authentication (`require_auth=true`). The uploader's email address is stripped from the displayed file name before it is returned.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `object_id` | path | yes | The unique identifier (UUID) of the uploaded file. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the file metadata for the specified uploaded file, with the uploader's email suffix removed from the file name. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Uploaded file metadata):**

```json
{
  "id": 55,
  "name": "signed-agreement.pdf",
  "parent_id": 3,
  "size": 85000,
  "mime": "application/pdf",
  "created": "2024-03-20T11:00:00+00:00",
  "modified": "2024-03-20T11:00:00+00:00",
  "deleted": false,
  "locked": 0
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref/uploads/:object_id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.
object_id = "VALUE"  # The unique identifier (UUID) of the uploaded file.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/uploads/{object_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## DELETE /rest/requestFile/{ref}/uploads/{object_id}

**Summary:** Delete an uploaded file

Deletes a file that was uploaded through the request file link. Only accessible when the link requires authentication (`require_auth=true`) and has not expired.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |
| `object_id` | path | yes | The unique identifier (UUID) of the uploaded file. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The uploaded file was successfully deleted. Returns no content. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_LOCKED |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**403 (ERR_ENTITY_LOCKED):**

```json
{
  "errors": {
    "code": "ERR_ENTITY_LOCKED",
    "message": "File is locked"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref/uploads/:object_id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.
object_id = "VALUE"  # The unique identifier (UUID) of the uploaded file.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/uploads/{object_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```

---

## POST /rest/mail/actions/requestFile

**Summary:** Request files to inbox

### Description:
  Sends a request files to inbox message.
### Precondition:
  Must be assigned a user profile with the ability to request files to inbox.
### Response:
  Sends the message requesting files to your inbox.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `to` | string[] | yes | List of email addresses to send the files to. |
| `subject` | string | yes | Subject of the email. Must be between 1 and 998 characters. |
| `body` | string | no | The body of the email. |
| `expire` | string | no | The expiration date of the request file link. |
| `fileLimit` | integer | no | The maximum number of files to attach. |
| `requireAuth` | boolean | no | Indicates if authentication is required to access the files. |
| `returnReceipts` | string[] | no | List of email addresses to send read receipts to. |
| `sharedMailboxId` | string | no | Unique identifier for the Shared Mailbox. Used to search for results belonging to this Shared Mailbox. |

**Responses:**

| Code | Description |
|------|-------------|
| 201 | Request File to Inbox request has been successfully created. |
| 400 | Bad Request  <i>Possible error codes: </i>ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST, ERR_LICENSE_MAX_USERS_COUNT_REACHED, ERR_SYSTEM_REQUEST_FILE_DISABLED, ERR_USER_HAS_NO_USER_TYPE, ERR_PROFILE_SEND_FILE_EXTERNAL_DISABLED, ERR_USER_TYPE_NO_ACCESS |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_HYPERLINK, ERR_INPUT_INVALID_DATE, ERR_INPUT_REQUIRED, ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**400 (ERR_REQUEST_INVALID_JSON):**

```json
{
  "errors": [
    {
      "code": "ERR_REQUEST_INVALID_JSON",
      "message": "Invalid json provided"
    }
  ]
}
```

**401 (ERR_AUTH_INVALID_CSRF):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_INVALID_CSRF",
      "message": "Invalid CSRF Authentication"
    }
  ]
}
```

**401 (ERR_AUTH_UNAUTHORIZED):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_UNAUTHORIZED",
      "message": "Unauthorized"
    }
  ]
}
```

**403 (ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST",
      "message": "Distribution list user is not allowed to register"
    }
  ]
}
```

**403 (ERR_LICENSE_MAX_USERS_COUNT_REACHED):**

```json
{
  "errors": [
    {
      "code": "ERR_LICENSE_MAX_USERS_COUNT_REACHED",
      "message": "License count has been reached"
    }
  ]
}
```

**403 (ERR_SYSTEM_REQUEST_FILE_DISABLED):**

```json
{
  "errors": [
    {
      "code": "ERR_SYSTEM_REQUEST_FILE_DISABLED",
      "message": "Request file feature is not enabled on this system."
    }
  ]
}
```

**403 (ERR_USER_HAS_NO_USER_TYPE):**

```json
{
  "errors": [
    {
      "code": "ERR_USER_HAS_NO_USER_TYPE",
      "message": "User has no profile"
    }
  ]
}
```

**403 (ERR_PROFILE_SEND_FILE_EXTERNAL_DISABLED):**

```json
{
  "errors": [
    {
      "code": "ERR_PROFILE_SEND_FILE_EXTERNAL_DISABLED",
      "message": "This profile is not allowed to send files to external users"
    }
  ]
}
```

**403 (ERR_USER_TYPE_NO_ACCESS):**

```json
{
  "errors": [
    {
      "code": "ERR_USER_TYPE_NO_ACCESS",
      "message": "Permission denied"
    }
  ]
}
```

**422 (ERR_INPUT_HYPERLINK):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_HYPERLINK",
      "message": "Not allowed hyperlink domain. Hyperlink domain should not different from anchored text domain."
    }
  ]
}
```

**422 (ERR_INPUT_INVALID_DATE):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_INVALID_DATE",
      "message": "The input is not a valid date."
    }
  ]
}
```

**422 (ERR_INPUT_REQUIRED):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_REQUIRED",
      "message": "Field is required"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

```json
{
  "errors": [
    {
      "code": "ERR_INVALID_PARAMETER",
      "message": "Invalid Parameter Exception"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/mail/actions/requestFile" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "to": [
         "string"
       ],
         "subject": "string",
         "body": "string",
         "expire": "2024-01-15",
         "fileLimit": 1,
         "requireAuth": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/mail/actions/requestFile"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "to": [
  "string"
],
  "subject": "string",
  "body": "string",
  "expire": "2024-01-15",
  "fileLimit": 1,
  "requireAuth": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/requestFile/{ref}/reply

**Summary:** Reply to Request File

### Description:
  Processes a reply to a specific Request File.
### Precondition:
  The user must be authenticated and have the proper access to reply to the specified request file.
### Response:
  The reply to the request file is processed, and a successful response is returned with the status of the action.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `ref` | path | yes | The unique reference of the Request File upload link. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | no | The body of the reply. This field is optional. |

**Responses:**

| Code | Description |
|------|-------------|
| 201 | The reply to the Request File has been successfully processed. |
| 400 | Bad Request  <i>Possible error codes: </i>ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_REQUEST_FILE_NO_FILE_UPLOADED |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_HYPERLINK |
| 490 | Request blocked by WAF |

**Response Examples:**

**400 (ERR_REQUEST_INVALID_JSON):**

```json
{
  "errors": [
    {
      "code": "ERR_REQUEST_INVALID_JSON",
      "message": "Invalid json provided"
    }
  ]
}
```

**401 (ERR_AUTH_INVALID_CSRF):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_INVALID_CSRF",
      "message": "Invalid CSRF Authentication"
    }
  ]
}
```

**401 (ERR_AUTH_UNAUTHORIZED):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_UNAUTHORIZED",
      "message": "Unauthorized"
    }
  ]
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": [
    {
      "code": "ERR_ACCESS_USER",
      "message": "Insufficient access permissions"
    }
  ]
}
```

**403 (ERR_ENTITY_REQUEST_FILE_NO_FILE_UPLOADED):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_REQUEST_FILE_NO_FILE_UPLOADED",
      "message": "No file has been uploaded for the request file"
    }
  ]
}
```

**422 (ERR_INPUT_HYPERLINK):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_HYPERLINK",
      "message": "Not allowed hyperlink domain. Hyperlink domain should not different from anchored text domain."
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/requestFile/:ref/reply" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "body": "string"
       }'
```

**Python:**

```python
import requests

ref = "VALUE"  # The unique reference of the Request File upload link.

url = f"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/reply"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "body": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---