# Kiteworks API — profiles Operations

**4 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/profiles.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/profiles.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/profiles

**Summary:** Add custom profile

Creates a new custom user type profile cloned from an existing built-in profile (e.g., Standard). The new profile's name must be unique. Returns 404 if the specified prototype profile does not exist.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | yes | Display name of the profile |
| `prototype` | integer | no | Id of the prototype profile to be cloned. If not passed, the Standard profile will be used |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Custom profile created successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 409 | Conflict  <i>Possible error codes: </i>ERR_ENTITY_EXISTS |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_NOT_IN_RANGE, ERR_INPUT_NOT_ALPHA_DASH, ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (CustomProfileCreated):**

```json
{
  "id": 5,
  "name": "Custom Standard",
  "builtIn": 0,
  "cloneable": 0,
  "prototype": 1
}
```

**403 (ERR_ACCESS_USER):**

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

**409 (ERR_ENTITY_EXISTS):**

```json
{
  "errors": {
    "code": "ERR_ENTITY_EXISTS",
    "message": "Entity exists"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

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

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/profiles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "name": "string",
         "prototype": 1
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/profiles"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "name": "string",
  "prototype": 1
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/profiles/{id}

**Summary:** Return user type (profile) details

Returns the details of the current user's own type profile, including its name, built-in status, and cloneability. Returns 403 if the requested profile does not belong to the current user.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user type (profile) to be retrieved |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | User type profile details retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ProfileInfo):**

```json
{
  "id": 2,
  "name": "Restricted",
  "builtIn": 1,
  "cloneable": 0
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the user type (profile) to be retrieved

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

---

## PUT /rest/profiles/{id}

**Summary:** Update profile

Updates the feature settings of the specified user type profile. When disabling collaboration access, optional demotion settings control how existing user data is handled (retained, deleted, or transferred to another user).

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the profile to be modified |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `allowSftp` | boolean | no | Indicates whether SFTP access is allowed |
| `maxStorage` | integer | no | Max storage in bytes |
| `storageQuota` | integer | no | Maximum storage space that user is entitled to |
| `setExpirationLower` | boolean | no | Allow to modify file secure link expiration |
| `sendExternal` | integer | no | Allow sending files to external users |
| `linkExpiration` | integer | no | Link expiration date in days |
| `ldapMapping` | string | no | LDAP Mapping value to determine the user profile type |
| `folderCreate` | integer | no | Allow to create top level folders |
| `sysFolderCreate` | integer | no | Allow to create system quota folders |
| `sysFolderMaxQuota` | integer | no | Set the maximum quota for a system folder |
| `sysFolderMaxCount` | integer | no | Set the maximum number of system folders |
| `sysFolderDefaultQuota` | integer | no | Set the default quota for a system folder |
| `maxLinkExpiration` | integer | no | Upper limit allowed for secure link expiration |
| `acNoAuth` | boolean | no | Who can download file via the secure link |
| `acVerifyRecipient` | boolean | no | Who can download file via the secure link |
| `excludedFileExtensions` | string[] | no | Set excluded file extensions |
| `fileFilterExclusionGroups` | string[] | no | Set excluded file groups |
| `fileFilterCustomFileTypes` | string[] | no | Set custom file types |
| `secureMessageBody` | string | no |  |
| `secureMessageBodyDefault` | boolean | no |  |
| `secureContainerRequired` | boolean | no |  |
| `returnReceipt` | string | no |  |
| `returnReceiptDefault` | boolean | no |  |
| `selfCopy` | string | no |  |
| `selfCopyDefault` | boolean | no |  |
| `includeFingerprint` | string | no |  |
| `includeFingerprintDefault` | boolean | no |  |
| `requestFile` | boolean | no |  |
| `requestFileAllowViewableFile` | boolean | no |  |
| `requestFileUploadAuth` | string | no |  |
| `requestFileAuthDefault` | string | no |  |
| `requestFileExpiration` | integer | no |  |
| `requestFileExpirationUserDecide` | boolean | no |  |
| `requestFileExpirationMax` | integer | no |  |
| `requestFileUploadLimit` | integer | no |  |
| `requestFileUploadLimitUserDecide` | boolean | no |  |
| `requestFileUploadsMax` | integer | no |  |
| `twoFactorAuth` | string | no |  |
| `inactiveExpiration` | integer | no |  |
| `userCanReactivate` | string | no |  |
| `cleanupInactiveAccount` | boolean | no |  |
| `withdrawInactiveAccountFileLinks` | boolean | no |  |
| `allowCollaboration` | boolean | no | Indicates whether Collaboration and Shared Folders are allowed |
| `sendFileLimit` | integer | no | Upper limit allowed for number of attachments per mail. |
| `remoteWipe` | boolean | no | Disallow Collaboration: Wipe remote devices |
| `deleteUnsharedData` | boolean | no | Disallow Collaboration: Delete all data owned by the user |
| `retainData` | boolean | no | Disallow Collaboration: retain the data owned by the user |
| `retainToUser` | string | no | Disallow Collaboration: re-assign the data to the following user |
| `retainPermissionToSharedData` | boolean | no | Disallow Collaboration: retain all permission to shared data |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Profile updated successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN, ERR_INPUT_ATTRIBUTE_FORBIDDEN, ERR_INPUT_REQUIRED, ERR_INPUT_NOT_STRING, ERR_INPUT_NOT_INTEGER, ERR_INPUT_MIN_VALUE, ERR_INPUT_NOT_IN_LIST, ERR_INPUT_MAX_VALUE, ERR_INPUT_NOT_LESS_THEN, ERR_INPUT_NOT_ALLOWED, ERR_INPUT_INVALID, ERR_INPUT_NOT_ARRAY |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ProfileUpdated):**

```json
{
  "id": 1,
  "name": "Standard",
  "builtIn": 1,
  "cloneable": 1
}
```

**403 (ERR_ACCESS_USER):**

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

**422 (ERR_INPUT_NOT_BOOLEAN):**

```json
{
  "errors": {
    "code": "ERR_INPUT_NOT_BOOLEAN",
    "message": "Input is not a valid boolean"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

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

**422 (ERR_INPUT_NOT_INTEGER):**

```json
{
  "errors": {
    "code": "ERR_INPUT_NOT_INTEGER",
    "message": "Input is not a valid integer"
  }
}
```

**422 (ERR_INPUT_MIN_VALUE):**

```json
{
  "errors": {
    "code": "ERR_INPUT_MIN_VALUE",
    "message": "The specified input below the minimum allowed value."
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/profiles/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "allowSftp": true,
         "maxStorage": 1,
         "storageQuota": 1,
         "setExpirationLower": true,
         "sendExternal": 1,
         "linkExpiration": 1
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the profile to be modified

url = f"https://{{instance}}.kiteworks.com/rest/profiles/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "allowSftp": true,
  "maxStorage": 1,
  "storageQuota": 1,
  "setExpirationLower": true,
  "sendExternal": 1,
  "linkExpiration": 1
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/profiles/{id}/replace/{new_profile}

**Summary:** Delete custom profile and set new profile instead of deleted profile

Permanently deletes the specified custom profile and reassigns all affected users to the specified replacement profile. Optional demotion settings control how existing user data is handled during the transition.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the custom profile to be deleted |
| `new_profile` | path | yes | ID of the replacement profile to assign to affected users |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `remoteWipe` | boolean | no | Indicates whether to remotely wipe data from both desktop and mobile devices. |
| `deleteUnsharedData` | boolean | no | Indicates whether data owned by the user should be deleted. This is required and must be set to True if `retainData` is False, and vice versa. |
| `retainData` | boolean | no | Indicates whether data should be retained and transferred to another user. This is required and must be True if `deleteUnsharedData` is False, and vice versa. |
| `retainToUser` | string | no | The ID of the new owner to whom the data will be transferred, applicable when `retainData` and/or `retainPermissionToSharedData` are set to true. |
| `retainToAdvancedFormUser` | string | no | The ID of the user to whom the advanced form data will be transferred, similar to retainToUser but specifically for advanced form components. |
| `retainPermissionToSharedData` | boolean | no | Indicates whether permissions to shared folder should be retained. |
| `withdrawRequestFiles` | boolean | no | Indicates whether request files should be withdrawn. |
| `withdrawFileLinks` | boolean | no | Indicates whether sent files should be withdrawn. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Custom profile deleted successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN, ERR_INPUT_ATTRIBUTE_FORBIDDEN, ERR_INPUT_REQUIRED, ERR_INPUT_NOT_STRING |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

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

**422 (ERR_INPUT_NOT_BOOLEAN):**

```json
{
  "errors": {
    "code": "ERR_INPUT_NOT_BOOLEAN",
    "message": "Input is not a valid boolean"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

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

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/profiles/:id/replace/:new_profile" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the custom profile to be deleted
new_profile = "VALUE"  # ID of the replacement profile to assign to affected users

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

---