# Kiteworks API — contacts Operations

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

**Summary:** List contacts

### Description:
  Returns a paginated list of the current user's contacts, with optional name filtering and sort order.
### Precondition:
  User must be authenticated.
### Response:
  Returns the list of contacts matching the specified filters.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `name` | query | no | Filter contacts by exact name match. |
| `name:contains` | query | no | Filter contacts whose name contains the specified string. |
| `orderBy` | query | no | Sort order for the results. Default is `name:asc`. Allowed values: `id:asc`, `id:desc`, `name:asc`, `name:desc`, `lastContactDate:asc`, `lastContactDate:desc`. |
| `limit` | query | no | Maximum number of contacts to return. |
| `offset` | query | no | Number of contacts to skip before returning results, for pagination. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The contacts list has been successfully returned. |
| 400 | Bad Request  <i>Possible error codes: </i>ERR_REQUEST_INVALID_FILTER |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 490 | Request blocked by WAF |

**Response Examples:**

**400 (ERR_REQUEST_INVALID_FILTER):**

```json
{
  "errors": [
    {
      "code": "ERR_REQUEST_INVALID_FILTER",
      "message": "Filter validation failed"
    }
  ]
}
```

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

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/contacts

**Summary:** Create a contact

### Description:
  Creates a new contact entry for the current user, associating a display name with one or more email addresses.
### Precondition:
  User must be authenticated.
### Response:
  Returns the newly created contact.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | yes | Display name for the contact. |
| `items` | ContactEmail[] | no | List of email addresses associated with this contact. At least one email address is required. |

**Responses:**

| Code | Description |
|------|-------------|
| 201 | The contact has been successfully created. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 409 | Conflict  <i>Possible error codes: </i>ERR_ENTITY_EXISTS |
| 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"
    }
  ]
}
```

**409 (ERR_ENTITY_EXISTS):**

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

**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/contacts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "name": "string",
         "items": [
         {
         "email": "string"
       }
       ]
       }'
```

**Python:**

```python
import requests

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

---

## GET /rest/contacts/{id}

**Summary:** Get a contact

### Description:
  Returns the details of the specified contact, including its display name and associated email addresses.
### Precondition:
  User must be authenticated and must own the contact.
### Response:
  Returns the contact details.

**Parameters:**

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

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The contact has been successfully returned. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 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_UNAUTHORIZED):**

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

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

**Python:**

```python
import requests

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

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

---

## PUT /rest/contacts/{id}

**Summary:** Update a contact

### Description:
  Updates the display name and associated email addresses of the specified contact.
### Precondition:
  User must be authenticated and must own the contact.
### Response:
  The contact has been updated.

**Parameters:**

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

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | yes | Display name for the contact. |
| `items` | ContactEmail[] | no | List of email addresses associated with this contact. At least one email address is required. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The contact has been successfully updated. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 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_INVALID_PARAMETER |
| 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_UNAUTHORIZED):**

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

**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_INVALID_PARAMETER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/contacts/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "name": "string",
         "items": [
         {
         "email": "string"
       }
       ]
       }'
```

**Python:**

```python
import requests

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

url = f"https://{{instance}}.kiteworks.com/rest/contacts/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "name": "string",
  "items": [
  {
  "email": "string"
}
]
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/contacts/{id}

**Summary:** Delete a contact

### Description:
  Permanently removes the specified contact from the current user's contact list.
### Precondition:
  User must be authenticated and must own the contact.
### Response:
  The contact has been deleted.

**Parameters:**

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

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The contact has been successfully deleted. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 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_UNAUTHORIZED):**

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

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

**Python:**

```python
import requests

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

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

---