# Kiteworks API — admin Operations

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

---

## GET /rest/admin/hostnames

**Summary:** List hostnames

Returns a paginated list of all alias hostnames, including their hostname, disabled state, and deletion status.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `alias_name` | query | no | Alias name |
| `alias_name:contains` | query | no | Alias name. Search for results that contain the specified characters in this parameter. |
| `tenant_id` | query | no | Tenant ID |
| `tenant_id:gt` | query | no | Tenant ID. Search for results where this parameter value is greater than the specified value. |
| `tenant_id:gte` | query | no | Tenant ID. Search for results where this parameter value is greater than or equal to the specified value. |
| `tenant_id:lt` | query | no | Tenant ID. Search for results where this parameter value is less than the specified value. |
| `tenant_id:lte` | query | no | Tenant ID. Search for results where this parameter value is less than or equal to the specified value. |
| `deleted` | query | no | Filter by whether the hostname is deleted. |
| `disabled` | query | no | Filter by whether the hostname is disabled. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | List of hostnames retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (HostnameList):**

```json
{
  "data": [
    {
      "id": 1,
      "hostname": "alias.example.com",
      "deleted": false,
      "disabled": false
    }
  ],
  "metadata": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/admin/hostnames

**Summary:** Create an alias hostname

Creates a new alias hostname for the current tenant. The hostname must be a valid subdomain of the configured site domain and must not already 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 |
|----------|------|----------|-------------|
| `hostname` | string | yes | Hostname |
| `disabled` | boolean | no | Disable hostname |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Hostname created successfully. |
| 409 | Conflict  <i>Possible error codes: </i>ERR_ENTITY_EXISTS |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED, ERR_INPUT_NOT_BOOLEAN |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (HostnameCreated):**

```json
{
  "id": 2,
  "hostname": "newteam.example.com",
  "deleted": false,
  "disabled": false
}
```

**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"
  }
}
```

**422 (ERR_INPUT_NOT_BOOLEAN):**

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

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/admin/hostnames" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "hostname": "string",
         "disabled": true,
         "addLinks": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/hostnames"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "hostname": "string",
  "disabled": true,
  "addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/admin/hostnames

**Summary:** Deletes list of hostnames

Soft-deletes a list of hostnames in a single request. Supports partial success, meaning valid items are processed even if some fail.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Hostnames deleted successfully. |
| 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/admin/hostnames?id:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/hostnames"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())
```

---

## GET /rest/admin/hostnames/{id}

**Summary:** Returns the details of hostname of the specified ID.

Returns the hostname record identified by the given ID, including its hostname value, disabled state, and deletion status.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the hostname to be retrieved |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Hostname details retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (HostnameInfo):**

```json
{
  "id": 1,
  "hostname": "alias.example.com",
  "deleted": false,
  "disabled": false
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the hostname to be retrieved

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

---

## PUT /rest/admin/hostnames/{id}

**Summary:** Disable / enable alias hostname

Updates the disabled state of the specified hostname, allowing it to be enabled or disabled.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the hostname to disable |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `disabled` | boolean | no | Disable hostname |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Hostname updated successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (HostnameDisabled):**

```json
{
  "id": 1,
  "hostname": "alias.example.com",
  "deleted": false,
  "disabled": true
}
```

**200 (HostnameEnabled):**

```json
{
  "id": 1,
  "hostname": "alias.example.com",
  "deleted": false,
  "disabled": false
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/admin/hostnames/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "disabled": true,
         "addLinks": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the hostname to disable

url = f"https://{{instance}}.kiteworks.com/rest/admin/hostnames/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "disabled": true,
  "addLinks": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/admin/hostnames/{id}

**Summary:** Mark specified hostname as deleted.

Soft-deletes the specified hostname by marking it as deleted. The record is retained but treated as inactive.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the hostname |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Hostname marked as deleted successfully. |
| 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/admin/hostnames/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the hostname

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

---

## GET /rest/admin/mail

**Summary:** List emails

Returns a list of emails for any user in the system. This includes sent emails, received emails, draft emails, and request a file emails. Requires admin privileges.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `senderId` | query | no | Unique identifier of User who sent Email |
| `senderId:in` | query | no | Unique identifier of User who sent Email. Search for results that match any of the specified values for this parameter. |
| `date` | query | no | Email creation date |
| `date:gt` | query | no | Email creation date. Search for results where this parameter value is greater than the specified value. |
| `date:gte` | query | no | Email creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `date:lt` | query | no | Email creation date. Search for results where this parameter value is less than the specified value. |
| `date:lte` | query | no | Email creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `modified_date` | query | no | Email modification date |
| `modified_date:gt` | query | no | Email modification date. Search for results where this parameter value is greater than the specified value. |
| `modified_date:gte` | query | no | Email modification date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified_date:lt` | query | no | Email modification date. Search for results where this parameter value is less than the specified value. |
| `modified_date:lte` | query | no | Email modification date. Search for results where this parameter value is less than or equal to the specified value. |
| `deleted` | query | no | Filter emails based on whether they have been deleted. |
| `emailPackageId` | query | no | Email Package unique identifier |
| `emailPackageId:in` | query | no | Email Package unique identifier. Search for results that match any of the specified values for this parameter. |
| `templateId` | query | no | Email Template unique identifier |
| `templateId:in` | query | no | Email Template unique identifier. Search for results that match any of the specified values for this parameter. |
| `status` | query | no | Filter emails by status. Accepted values: `sent`, `draft`, `queued`, `error`, `self_send`, `transferring`. |
| `isPreview` | query | no | Whether the email is a preview email |
| `isUserSent` | query | no | Whether the email was sent by some user |
| `webFormId` | query | no | Email web form ID |
| `webFormId:contains` | query | no | Email web form ID. Search for results that contain the specified characters in this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of emails matching the specified filters. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (AdminEmailList):**

```json
[
  {
    "id": "eml12345abc67890de",
    "senderId": "usr98765cba43210fe",
    "templateId": 1,
    "status": "sent",
    "type": "sendfile",
    "date": "2024-06-15",
    "deleted": false,
    "emailPackageId": "pkg12345abc67890de",
    "isRead": true,
    "bucket": "inbox",
    "subject": "Q2 Reports"
  }
]
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## DELETE /rest/admin/mail/actions/withdrawFiles/users/{userId}

**Summary:** Withdraw all files from the emails of deleted or demoted users

Withdraws all files from the emails of users who have been deleted or demoted.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `userId` | path | yes | The unique identifier of the user from whom to withdraw files. |
| `emailId:in` | query | no | A list of email IDs to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The files were successfully withdrawn from the specified emails. No content is returned. |
| 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/admin/mail/actions/withdrawFiles/users/:userId" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

userId = "VALUE"  # The unique identifier of the user from whom to withdraw files.

url = f"https://{{instance}}.kiteworks.com/rest/admin/mail/actions/withdrawFiles/users/{userId}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```

---

## GET /rest/admin/profiles

**Summary:** List user types (profiles)

Returns a paginated list of user type profiles configured in the system (e.g., Standard and Restricted), including each profile's name, built-in status, and cloneability.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `name` | query | no | Profile name |
| `name:contains` | query | no | Profile name. Search for results that contain the specified characters in this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | List of user type profiles retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ProfileList):**

```json
{
  "data": [
    {
      "id": 1,
      "name": "Standard",
      "builtIn": 1,
      "cloneable": 1
    }
  ],
  "metadata": {
    "total": 2,
    "limit": 50,
    "offset": 0
  }
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## GET /rest/admin/profiles/mappingOrder

**Summary:** Get profile mapping order

Returns the current ordering of user type profiles used to determine which profile is applied to a user on login when multiple mapping rules match.
**Responses:**

| Code | Description |
|------|-------------|
| 200 | Profile mapping order retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (MappingOrder):**

```json
{
  "order": [
    1,
    3,
    2
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## PUT /rest/admin/profiles/mappingOrder

**Summary:** Update profile mapping order

Updates the ordering of user type profiles used to determine which profile is applied to a user on login when multiple mapping rules match. When the peek parameter is set, returns the projected impact without applying changes.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `peek` | boolean | no | Set if we are peeking into the impact |
| `order` | integer[] | yes | Set the User Profile mapping order |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Profile mapping order updated successfully. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN, ERR_INPUT_NOT_ARRAY_OF_INTEGERS, ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (MappingOrderUpdated):**

```json
{
  "order": [
    3,
    1,
    2
  ]
}
```

**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 PUT \
  "https://{instance}.kiteworks.com/rest/admin/profiles/mappingOrder" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "peek": true,
         "order": [
         1
       ]
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/profiles/mappingOrder"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "peek": true,
  "order": [
  1
]
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/admin/profiles/mappings

**Summary:** Get profile mapping results for user

Simulates profile mapping evaluation for the specified user and returns which profile mapping rules would match, without applying any changes.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `user` | query | yes | Username or email of the user to test mappings for |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Profile mapping test results retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (MappingTestResult):**

```json
{
  "result": [
    {
      "id": "ldap1",
      "name": "Engineering LDAP",
      "filter": "(memberOf=cn=Engineering)"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/admin/profiles/mappings?user=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/profiles/mappings"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "user": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())
```

---

## GET /rest/admin/profiles/{id}

**Summary:** Return a user type

Returns the details of the specified user type profile, including its name, built-in status, and cloneability.

**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": 1,
  "name": "Standard",
  "builtIn": 1,
  "cloneable": 1
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/admin/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/admin/profiles/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## GET /rest/admin/profiles/{id}/mappings

**Summary:** Get profile mapping details

Returns the identity provider mapping rules configured for the specified profile, including LDAP, SSO, and kiteworks-based filter policies.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the profile to get mapping details for |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Profile mapping details retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ProfileMappings):**

```json
{
  "ldap": [
    {
      "id": "ldap1",
      "name": "Corp LDAP",
      "filter": "(memberOf=cn=Engineering)"
    }
  ],
  "sso": [],
  "kiteworks": [
    {
      "id": "kiteworks",
      "filter": "example.com"
    }
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the profile to get mapping details for

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

---

## PUT /rest/admin/profiles/{id}/mappings

**Summary:** Update profile mapping details

Updates the identity provider mapping rules for the specified profile. When the peek parameter is set, returns the projected impact of the changes without applying them.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the profile to update mapping details for |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `peek` | boolean | no | Set if we are peeking into the impact |
| `changes` | ProfileMapping[] | no | policy changes to be tested/applied |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Profile mapping details updated successfully. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ProfileMappingUpdated):**

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

**422 (ERR_INPUT_NOT_BOOLEAN):**

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

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/admin/profiles/:id/mappings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "peek": true,
         "changes": [
         {
         "impact": [
         "..."
       ],
         "id": "string",
         "name": "string",
         "filter": "string"
       }
       ]
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the profile to update mapping details for

url = f"https://{{instance}}.kiteworks.com/rest/admin/profiles/{id}/mappings"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "peek": true,
  "changes": [
  {
  "impact": [
  "..."
],
  "id": "string",
  "name": "string",
  "filter": "string"
}
]
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/admin/profiles/{id}/users

**Summary:** Return list of users with the specified types

Returns a paginated list of users assigned to the specified user type profile (e.g., all Restricted users), including their names and email addresses.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user type (profile) to retrieve users for |
| `email` | query | no | Filter users based on their email address. |
| `email:contains` | query | no | Filter users based on their email address.. Search for results that contain the specified characters in this parameter. |
| `name` | query | no | Filter users based on their full name. |
| `name:contains` | query | no | Filter users based on their full name.. Search for results that contain the specified characters in this parameter. |
| `metadata` | query | no | Filter users based on their metadata information. |
| `metadataContains` | query | no | Filter users whose metadata contains the specified characters. |
| `deleted` | query | no | Filter users based on whether they have been deleted. |
| `active` | query | no | Filter users based on whether they are active in the system. |
| `verified` | query | no | Filter users based on their verification status. |
| `suspended` | query | no | Filter users based on whether they are suspended. |
| `isRecipient` | query | no | Filter users who are recipients of specific items. |
| `allowsCollaboration` | query | no | Filter users whose profiles allow collaboration access. |
| `created` | query | no | Filter users based on the creation date of their account. |
| `created:gt` | query | no | Filter users based on the creation date of their account.. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Filter users based on the creation date of their account.. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Filter users based on the creation date of their account.. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Filter users based on the creation date of their account.. Search for results where this parameter value is less than or equal to the specified value. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `locate_id` | query | no | If specified, "offset" parameter will be ignored                                             and the page containing entity with this Id will be returned. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | List of users with the specified profile retrieved successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ProfileUserList):**

```json
{
  "data": [
    {
      "id": 42,
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ],
  "metadata": {
    "total": 1,
    "limit": 50,
    "offset": 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/admin/profiles/:id/users" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the user type (profile) to retrieve users for

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

---

## PUT /rest/admin/profiles/{id}/users

**Summary:** Bulk update user types (profiles)

Reassigns multiple users to the specified user type profile. When demoting users to a Restricted or Recipient profile, optional demotion settings control how existing data is handled (retained, deleted, or transferred to another user).

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user type (profile). |
| `id:in` | query | yes | A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of user IDs to be assigned to the user type (profile). |
| `mode` | query | no | Determines the detail level of the response body. |

**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 |
|------|-------------|
| 200 | User profiles 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 |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (BulkProfileUpdate):**

```json
{
  "data": [
    {
      "id": 42,
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ],
  "metadata": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

**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 PUT \
  "https://{instance}.kiteworks.com/rest/admin/profiles/:id/users?id:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "remoteWipe": true,
         "deleteUnsharedData": true,
         "retainData": true,
         "retainToUser": "string",
         "retainToAdvancedFormUser": "string",
         "retainPermissionToSharedData": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the user type (profile).

url = f"https://{{instance}}.kiteworks.com/rest/admin/profiles/{id}/users"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
params = {
    "id:in": "VALUE",
}
payload = {
  "remoteWipe": true,
  "deleteUnsharedData": true,
  "retainData": true,
  "retainToUser": "string",
  "retainToAdvancedFormUser": "string",
  "retainPermissionToSharedData": true
}
response = requests.put(url, params=params, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/admin/users

**Summary:** Get a list of Users

Returns a list of Users in the system. The user must be an administrator with access to User Management.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `email` | query | no | Filter users based on their email address. |
| `email:contains` | query | no | Filter users based on their email address.. Search for results that contain the specified characters in this parameter. |
| `name` | query | no | Filter users based on their full name. |
| `name:contains` | query | no | Filter users based on their full name.. Search for results that contain the specified characters in this parameter. |
| `metadata` | query | no | Filter users based on their metadata information. |
| `metadataContains` | query | no | Filter users whose metadata contains the specified characters. |
| `deleted` | query | no | Filter users based on whether they have been deleted. |
| `active` | query | no | Filter users based on whether they are active in the system. |
| `verified` | query | no | Filter users based on their verification status. |
| `suspended` | query | no | Filter users based on whether they are suspended. |
| `isRecipient` | query | no | Filter users who are recipients of specific items. |
| `allowsCollaboration` | query | no | Filter users whose profiles allow collaboration access. |
| `created` | query | no | Filter users based on the creation date of their account. |
| `created:gt` | query | no | Filter users based on the creation date of their account.. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Filter users based on the creation date of their account.. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Filter users based on the creation date of their account.. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Filter users based on the creation date of their account.. Search for results where this parameter value is less than or equal to the specified value. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `locate_id` | query | no | If specified, "offset" parameter will be ignored                                             and the page containing entity with this Id will be returned. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of users. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (UserList):**

```json
[
  {
    "id": "abc12345def67890ab",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "active": true,
    "verified": true,
    "suspended": false,
    "deleted": false,
    "deactivated": false,
    "flags": 1,
    "userTypeId": 5,
    "created": "2024-01-15T10:30:00+0000"
  }
]
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/admin/users

**Summary:** Create a User

Creates a new User in the system by specifying an email address and name.

**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 |
|----------|------|----------|-------------|
| `email` | string | yes | The user's email |
| `name` | string | no | The name of the user |
| `password` | string | no | The user's password |
| `userTypeId` | integer | no | The unique identifier of the user type |
| `verified` | boolean | no | Indicates whether the user is verified |
| `sendNotification` | boolean | no | Indicates whether a notification is sent to the user |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | User created successfully. Returns the newly created user object. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_INVALID_EMAIL, ERR_INPUT_REQUIRED, ERR_INPUT_PASSWORD_COMPLEXITY_ERROR, ERR_INPUT_NOT_NUMERIC, ERR_INPUT_MIN_VALUE |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (CreatedUser):**

```json
{
  "id": "abc12345def67890ab",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "active": true,
  "verified": false,
  "suspended": false,
  "deleted": false,
  "deactivated": false,
  "flags": 1,
  "userTypeId": 5,
  "created": "2024-01-15T10:30:00+0000"
}
```

**403 (ERR_ACCESS_USER):**

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

**422 (ERR_INPUT_INVALID_EMAIL):**

```json
{
  "errors": {
    "code": "ERR_INPUT_INVALID_EMAIL",
    "message": "Input is not a valid email"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

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

**422 (ERR_INPUT_PASSWORD_COMPLEXITY_ERROR):**

```json
{
  "errors": {
    "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR",
    "message": "Password does not meet complexity requirements"
  }
}
```

**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 POST \
  "https://{instance}.kiteworks.com/rest/admin/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "email": "string",
         "name": "string",
         "password": "string",
         "userTypeId": 1,
         "verified": true,
         "sendNotification": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/users"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "email": "string",
  "name": "string",
  "password": "string",
  "userTypeId": 1,
  "verified": true,
  "sendNotification": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/admin/users/migrateEmails

**Summary:** Bulk update user emails

Bulk update user emails by migrating old email addresses to new ones. Accepts an array of objects containing old and new email pairs.

**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 |
|----------|------|----------|-------------|
| `users` | UserEmail.Post[] | no | Array of user objects, each containing old and new email values. |
| `deleteIfExists` | boolean | no | Indicates whether to delete users whose emails match any in the newEmail field. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Email migration completed successfully. Returns the list of updated user objects. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_INVALID_EMAIL, ERR_INPUT_REQUIRED, ERR_INPUT_PASSWORD_COMPLEXITY_ERROR |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (MigratedUsers):**

```json
[
  {
    "id": "abc12345def67890ab",
    "name": "Jane Doe",
    "email": "jane.new@example.com",
    "active": true,
    "verified": true,
    "suspended": false,
    "deleted": false,
    "deactivated": false,
    "flags": 1,
    "userTypeId": 5,
    "created": "2024-01-15T10:30:00+0000"
  }
]
```

**422 (ERR_INPUT_INVALID_EMAIL):**

```json
{
  "errors": {
    "code": "ERR_INPUT_INVALID_EMAIL",
    "message": "Input is not a valid email"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

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

**422 (ERR_INPUT_PASSWORD_COMPLEXITY_ERROR):**

```json
{
  "errors": {
    "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR",
    "message": "Password does not meet complexity requirements"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/admin/users/migrateEmails" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "users": [
         {
         "oldEmail": "string",
         "newEmail": "string"
       }
       ],
         "deleteIfExists": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/users/migrateEmails"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "users": [
  {
  "oldEmail": "string",
  "newEmail": "string"
}
],
  "deleteIfExists": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/admin/users/migrateEmailsCsv

**Summary:** Bulk update user emails via CSV file

Bulk update user emails by migrating old email addresses to new ones using a CSV file.

**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 |
|----------|------|----------|-------------|
| `body` | string | yes | CSV file containing old and new email pairs. |
| `deleteIfExists` | boolean | no | Indicates whether to delete users whose emails match any in the newEmail field. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Email migration completed successfully. Returns the list of updated user objects. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (MigratedUsers):**

```json
[
  {
    "id": "abc12345def67890ab",
    "name": "Jane Doe",
    "email": "jane.new@example.com",
    "active": true,
    "verified": true,
    "suspended": false,
    "deleted": false,
    "deactivated": false,
    "flags": 1,
    "userTypeId": 5,
    "created": "2024-01-15T10:30:00+0000"
  }
]
```

**422 (ERR_INPUT_NOT_BOOLEAN):**

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

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/admin/users/migrateEmailsCsv" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "body": "string",
         "deleteIfExists": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/users/migrateEmailsCsv"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "body": "string",
  "deleteIfExists": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/admin/users/{id}

**Summary:** Get User

Returns the details of the specified user, including their name, email address, and account status.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user to retrieve |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the requested user's details. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ActiveUser):**

```json
{
  "id": "abc12345def67890ab",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "active": true,
  "verified": true,
  "suspended": false,
  "deleted": false,
  "deactivated": false,
  "flags": 1,
  "userTypeId": 5,
  "created": "2024-01-15T10:30:00+0000"
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the user to retrieve

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

---

## PUT /rest/admin/users/{id}

**Summary:** Update User

Updates the details of a user, such as changing their name, setting them as deleted, or updating their active/inactive status.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user to be updated |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `suspended` | boolean | no | Indicates whether the user is suspended. Set to true to suspend the user. |
| `name` | string | no | The name of the user |
| `password` | string | no | The user's password |
| `verified` | boolean | no | Indicates whether the user is verified |
| `deactivated` | boolean | no | Indicates whether the user is deactivated. Set to true to deactivate the user. |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | User updated successfully. Returns the updated user object. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (UpdatedUser):**

```json
{
  "id": "abc12345def67890ab",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "active": true,
  "verified": true,
  "suspended": false,
  "deleted": false,
  "deactivated": false,
  "flags": 1,
  "userTypeId": 5,
  "created": "2024-01-15T10:30:00+0000"
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/admin/users/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "suspended": true,
         "name": "string",
         "password": "string",
         "verified": true,
         "deactivated": true,
         "addLinks": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the user to be updated

url = f"https://{{instance}}.kiteworks.com/rest/admin/users/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "suspended": true,
  "name": "string",
  "password": "string",
  "verified": true,
  "deactivated": true,
  "addLinks": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/admin/users/{id}

**Summary:** Deletes a User

Mark the specified user as deleted. This user will still be returned in the GET Users query.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user to delete |
| `retainToUser` | query | 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` | query | no | The ID of the user to whom the advanced form data will be transferred, similar to retainToUser but specifically for advanced form components. |
| `remoteWipe` | query | no | Indicates whether to remotely wipe data from both desktop and mobile devices. |
| `deleteUnsharedData` | query | 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` | query | 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. |
| `retainPermissionToSharedData` | query | no | Indicates whether permissions to shared folders should be retained. |
| `withdrawFileLinks` | query | no | Indicates whether files sent by deleted or demoted users should be withdrawn. |
| `withdrawRequestFiles` | query | no | Indicates whether request files sent by deleted or demoted users should be withdrawn. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | User marked as 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/admin/users/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the user to delete

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

---

## GET /rest/admin/users/{id}/adminRoles

**Summary:** Return admin roles of the specified user id.

Returns all admin roles assigned to the specified user. The user may be active or deleted.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user to retrieve admin role |
| `orderBy` | query | no | Sorting options |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the list of admin roles assigned to the specified user. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (AdminRoles):**

```json
[
  {
    "id": 2,
    "name": "Site Admin",
    "guid": "abc12345def67890ab"
  }
]
```

**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/admin/users/:id/adminRoles" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the user to retrieve admin role

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

---

## GET /rest/admin/users/{id}/devices

**Summary:** List devices for a user

Returns a list of devices registered to the specified user.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user whose devices to be retrieved |
| `installTagId` | query | no | Unique identifier of install tag for this Device |
| `installTagId:contains` | query | no | Unique identifier of install tag for this Device. Search for results that contain the specified characters in this parameter. |
| `userId` | query | no | Unique identifier of user for this Device |
| `userId:in` | query | no | Unique identifier of user for this Device. Search for results that match any of the specified values for this parameter. |
| `clientId` | query | no | Unique identifier of client for this Device |
| `clientId:contains` | query | no | Unique identifier of client for this Device. Search for results that contain the specified characters in this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of device records for the specified user. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (User device list):**

```json
{
  "data": [
    {
      "id": 101,
      "client_id": "mobile_app_ios",
      "user_id": 5,
      "install_tag_id": "ABC123DEF456",
      "install_name": "Work iPhone",
      "wipe_flag": 0,
      "mobile_key_store": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the user whose devices to be retrieved

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

---

## GET /rest/admin/activities

**Summary:** Get admin activities list

### Description:
  Retrieves the list of admin activities.
### Precondition:
  The user must be an administrator with access to `Activity Log`.
### Response:
  Returns the list of activities performed by the admin.
### Sorting:
  Sort string syntax `FIELD_NAME:ORDER`.

  ORDER can be `asc` or `desc`.
### Sorting options:
  | FIELD_NAME | Description |
  |------------|-------------|
  | created    | The creation date and time of the activity |
  | client     | The client name |
  | username   | The username associated with the activity |
  | ip_address | The client IP address |

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `startDateTime` | query | yes | The start date and time for the activity range. |
| `endDateTime` | query | yes | The end date and time for the activity range. |
| `eventFilters:in` | query | no | Comma-separated list of event filters to filter the activities. |
| `objectIds:in` | query | no | Comma-separated list of object IDs to filter the activities. |
| `userId` | query | no | User ID to filter activities by a specific user. |
| `maxPages` | query | no | Maximum number of pages to retrieve. |
| `orderBy` | query | no | Sort order for the results. Default is `created:desc`. Allowed values: `created:asc`, `created:desc`, `client:asc`, `client:desc`, `username:asc`, `username:desc`, `ip_address:asc`, `ip_address:desc`. |
| `compact` | query | no | If true, returns a more compact response. |
| `limit` | query | no | Maximum number of items to return. |
| `offset` | query | no | Number of items to skip before returning results, for pagination. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The admin activities list is successfully returned. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**401 (ERR_ACCESS_USER):**

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

**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"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/admin/activities?startDateTime=VALUE&endDateTime=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/activities"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "startDateTime": "VALUE",
    "endDateTime": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())
```

---

## GET /rest/admin/activities/{id}

**Summary:** Get admin activity detail

### Description:
  Retrieves detailed information about a specific activity.
### Precondition:
  The user must be an administrator with access to `Activity Log`.
### Response:
  Returns the full details of the specified activity.

**Parameters:**

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

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Successfully retrieved the activity details. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**401 (ERR_ACCESS_USER):**

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

**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"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

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

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

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

---

## GET /rest/admin/activities/actions/exportCSV

**Summary:** Export admin activities list

### Description:
  Exports the list of admin activities based on the provided filters.
### Precondition:
  The user must be an administrator with access to `Activity Log`.
### Response:
  The admin activities list is generated and sent via email to the requesting user.
### Sorting:
  Sort string syntax `FIELD_NAME:ORDER`.

  ORDER can be `asc` or `desc`.
### Sorting options:
  | FIELD_NAME | Description |
  |------------|-------------|
  | created    | The creation date and time of the activity |
  | client     | The client name |
  | username   | The username associated with the activity |
  | ip_address | The client IP address |

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `startDateTime` | query | yes | The start date and time for the activity range. |
| `endDateTime` | query | yes | The end date and time for the activity range. |
| `eventFilters:in` | query | no | Comma-separated list of event filters to filter the activities. |
| `objectIds:in` | query | no | Comma-separated list of object IDs to filter the activities. |
| `userId` | query | no | User ID to filter activities by a specific user. |
| `maxPages` | query | no | Maximum number of pages to retrieve. |
| `orderBy` | query | no | Sort order for the results. Default is `created:desc`. Allowed values: `created:asc`, `created:desc`, `client:asc`, `client:desc`, `username:asc`, `username:desc`, `ip_address:asc`, `ip_address:desc`. |
| `compact` | query | no | If true, returns a more compact response. |
| `limit` | query | no | Maximum number of items to return. |
| `offset` | query | no | Number of items to skip before returning results, for pagination. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The admin activities list is being processed and will be sent via email. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**401 (ERR_ACCESS_USER):**

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

**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"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/admin/activities/actions/exportCSV?startDateTime=VALUE&endDateTime=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/activities/actions/exportCSV"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "startDateTime": "VALUE",
    "endDateTime": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())
```

---