contacts

5 endpoints
GET/rest/contacts

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
Query Parameters
name
Optional
string

Filter contacts by exact name match.

name:contains
Optional
string

Filter contacts whose name contains the specified string.

orderBy
Optional
string

Sort order for the results. Default is name:asc.
Allowed values: id:asc, id:desc, name:asc, name:desc, lastContactDate:asc, lastContactDate:desc.

limit
Optional
integer

Maximum number of contacts to return.

offset
Optional
integer

Number of contacts to skip before returning results, for pagination.

Responses

The contacts list has been successfully returned.

total
integer

Total number of items available.

limit
integer

Maximum number of items returned per page.

offset
integer

Number of items skipped before the current page.

id
integer

Unique identifier of the contact.

userId
string
name
string

Display name of the contact.

created
string

Date and time when the contact was created.

modified
string

Date and time when the contact was last modified.

lastContactDate
string

Date and time of the most recent interaction with this contact.

email
string

Email address of the contact.

isDistributionList
boolean

Indicates whether the contact is a distribution list.

profileIcon
string

URL or identifier of the contact's profile icon.

Bad Request

Possible error codes: ERR_REQUEST_INVALID_FILTER

code
string

Error code

message
string

Error message

Unauthorized

Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/contacts" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/contacts"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "metadata": {}, "data": [ { "id": 1, "userId": "string", "name": "string", "created": "2024-01-15", "modified": "2024-01-15", "lastContactDate": "2024-01-15" } ] }
{ "errors": [ { "code": "ERR_REQUEST_INVALID_FILTER", "message": "Filter validation failed" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
// Error - No Body
POST/rest/contacts

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
name
Required
string

Display name for the contact.

items
ContactEmail[]

List of email addresses associated with this contact. At least one email address is required.

Responses

The contact has been successfully created.

id
integer

Unique identifier of the contact.

userId
string
name
string

Display name of the contact.

created
string

Date and time when the contact was created.

modified
string

Date and time when the contact was last modified.

lastContactDate
string

Date and time of the most recent interaction with this contact.

email
string

Email address of the contact.

isDistributionList
boolean

Indicates whether the contact is a distribution list.

profileIcon
string

URL or identifier of the contact's profile icon.

Unauthorized

Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Conflict

Possible error codes: ERR_ENTITY_EXISTS

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
{ "id": 1, "userId": "string", "name": "string", "created": "2024-01-15", "modified": "2024-01-15", "lastContactDate": "2024-01-15" }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ENTITY_EXISTS", "message": "Entity exists" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
// Error - No Body
GET/rest/contacts/{id}

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
Path Parameters
id
Required
integer

The unique identifier of the entity.

Responses

The contact has been successfully returned.

id
integer

Unique identifier of the contact.

userId
string
name
string

Display name of the contact.

created
string

Date and time when the contact was created.

modified
string

Date and time when the contact was last modified.

lastContactDate
string

Date and time of the most recent interaction with this contact.

email
string

Email address of the contact.

isDistributionList
boolean

Indicates whether the contact is a distribution list.

profileIcon
string

URL or identifier of the contact's profile icon.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/contacts/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "id": 1, "userId": "string", "name": "string", "created": "2024-01-15", "modified": "2024-01-15", "lastContactDate": "2024-01-15" }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
// Error - No Body
PUT/rest/contacts/{id}

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
Path Parameters
id
Required
integer

The unique identifier of the entity.

Request Body
name
Required
string

Display name for the contact.

items
ContactEmail[]

List of email addresses associated with this contact. At least one email address is required.

Responses

The contact has been successfully updated.

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Conflict

Possible error codes: ERR_ENTITY_EXISTS

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_ENTITY_EXISTS", "message": "Entity exists" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
// Error - No Body
DELETE/rest/contacts/{id}

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
Path Parameters
id
Required
integer

The unique identifier of the entity.

Responses

The contact has been successfully deleted.

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/contacts/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
// Error - No Body
Previouscomments
Nextdevices