Kiteworks contacts API
The contacts API from Kiteworks — 2 operation(s) for contacts.
OpenAPI Specification
openapi: 3.0.2
info:
version: '28'
title: Kiteworks API Documentation activities contacts API
tags:
- name: contacts
paths:
/rest/contacts:
post:
summary: Create a contact
description: "### Description:\n Creates a new contact entry for the current user, associating a display name with one or more email addresses.\n### Precondition:\n User must be authenticated.\n### Response:\n Returns the newly created contact.\n"
tags:
- contacts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCreate'
responses:
'201':
description: The contact has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'409':
description: 'Conflict<br /><br /><i>Possible error codes: </i>ERR_ENTITY_EXISTS'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ENTITY_EXISTS:
summary: Entity exists
description: Entity exists
value:
errors:
- code: ERR_ENTITY_EXISTS
message: Entity exists
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INVALID_PARAMETER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INVALID_PARAMETER:
summary: Invalid Parameter Exception
description: Invalid Parameter Exception
value:
errors:
- code: ERR_INVALID_PARAMETER
message: Invalid Parameter Exception
'490':
description: Request blocked by WAF
get:
summary: List contacts
description: "### Description:\n Returns a paginated list of the current user's contacts, with optional name filtering and sort order.\n### Precondition:\n User must be authenticated.\n### Response:\n Returns the list of contacts matching the specified filters.\n"
tags:
- contacts
parameters:
- in: query
name: name
required: false
description: Filter contacts by exact name match.
schema:
type: string
- in: query
name: name:contains
required: false
description: Filter contacts whose name contains the specified string.
schema:
type: string
- in: query
name: orderBy
required: false
description: 'Sort order for the results. Default is `name:asc`.<br>Allowed values: `id:asc`, `id:desc`, `name:asc`, `name:desc`, `lastContactDate:asc`, `lastContactDate:desc`.'
schema:
type: string
enum:
- id:asc
- id:desc
- name:asc
- name:desc
- lastContactDate:asc
- lastContactDate:desc
- in: query
name: limit
required: false
description: Maximum number of contacts to return.
schema:
type: integer
- in: query
name: offset
required: false
description: Number of contacts to skip before returning results, for pagination.
schema:
type: integer
responses:
'200':
description: The contacts list has been successfully returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactList'
'400':
description: 'Bad Request<br /><br /><i>Possible error codes: </i>ERR_REQUEST_INVALID_FILTER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_REQUEST_INVALID_FILTER:
summary: Filter validation failed
description: Filter validation failed
value:
errors:
- code: ERR_REQUEST_INVALID_FILTER
message: Filter validation failed
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'490':
description: Request blocked by WAF
/rest/contacts/{id}:
put:
summary: Update a contact
description: "### Description:\n Updates the display name and associated email addresses of the specified contact.\n### Precondition:\n User must be authenticated and must own the contact.\n### Response:\n The contact has been updated.\n"
tags:
- contacts
parameters:
- in: path
name: id
required: true
description: The unique identifier of the entity.
schema:
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCreate'
responses:
'200':
description: The contact has been successfully updated.
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
'409':
description: 'Conflict<br /><br /><i>Possible error codes: </i>ERR_ENTITY_EXISTS'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ENTITY_EXISTS:
summary: Entity exists
description: Entity exists
value:
errors:
- code: ERR_ENTITY_EXISTS
message: Entity exists
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INVALID_PARAMETER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INVALID_PARAMETER:
summary: Invalid Parameter Exception
description: Invalid Parameter Exception
value:
errors:
- code: ERR_INVALID_PARAMETER
message: Invalid Parameter Exception
'490':
description: Request blocked by WAF
get:
summary: Get a contact
description: "### Description:\n Returns the details of the specified contact, including its display name and associated email addresses.\n### Precondition:\n User must be authenticated and must own the contact.\n### Response:\n Returns the contact details.\n"
tags:
- contacts
parameters:
- in: path
name: id
required: true
description: The unique identifier of the entity.
schema:
type: integer
responses:
'200':
description: The contact has been successfully returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
'490':
description: Request blocked by WAF
delete:
summary: Delete a contact
description: "### Description:\n Permanently removes the specified contact from the current user's contact list.\n### Precondition:\n User must be authenticated and must own the contact.\n### Response:\n The contact has been deleted.\n"
tags:
- contacts
parameters:
- in: path
name: id
required: true
description: The unique identifier of the entity.
schema:
type: integer
responses:
'204':
description: The contact has been successfully deleted.
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
'490':
description: Request blocked by WAF
components:
schemas:
ContactEmail:
type: object
properties:
email:
type: string
format: email
description: Email address of the contact.
required:
- email
Errors:
type: object
properties:
error:
type: array
items:
$ref: '#/components/schemas/Error'
ContactList:
type: object
properties:
metadata:
description: Pagination metadata for the result set.
allOf:
- $ref: '#/components/schemas/MetaData'
data:
type: array
description: List of contacts.
items:
$ref: '#/components/schemas/Contact'
Error:
type: object
properties:
code:
type: string
description: Error code
message:
type: string
description: Error message
ContactItem:
type: object
properties:
email:
type: string
description: Email address of the contact.
isDistributionList:
type: boolean
description: Indicates whether the contact is a distribution list.
profileIcon:
type: string
description: URL or identifier of the contact's profile icon.
Contact:
type: object
properties:
id:
type: integer
description: Unique identifier of the contact.
userId:
type: string
name:
type: string
description: Display name of the contact.
created:
type: string
format: date
description: Date and time when the contact was created.
modified:
type: string
format: date
description: Date and time when the contact was last modified.
lastContactDate:
type: string
format: date
description: Date and time of the most recent interaction with this contact.
items:
type: array
description: List of email addresses or distribution lists for this contact.
items:
$ref: '#/components/schemas/ContactItem'
MetaData:
type: object
properties:
total:
type: integer
description: Total number of items available.
limit:
type: integer
description: Maximum number of items returned per page.
offset:
type: integer
description: Number of items skipped before the current page.
ContactCreate:
type: object
properties:
name:
type: string
description: Display name for the contact.
items:
type: array
minItems: 1
description: List of email addresses associated with this contact. At least one email address is required.
items:
$ref: '#/components/schemas/ContactEmail'
required:
- name