{
"openapi": "3.0.2",
"info": {
"version": "28",
"title": "Kiteworks API — contacts Operations"
},
"paths": {
"/rest/contacts": {
"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`.
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
Possible error codes: 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
Possible error codes: 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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/contacts\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/contacts\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"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
Possible error codes: 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
Possible error codes: 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
Possible error codes: 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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/contacts\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"string\",\n \"items\": [\n {\n \"email\": \"string\"\n }\n ]\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/contacts\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"name\": \"string\",\n \"items\": [\n {\n \"email\": \"string\"\n}\n]\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/contacts/{id}": {
"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
Possible error codes: 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
Possible error codes: 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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/contacts/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/contacts/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"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
Possible error codes: 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
Possible error codes: 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
Possible error codes: 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
Possible error codes: 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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PUT \\\n \"https://{instance}.kiteworks.com/rest/contacts/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"string\",\n \"items\": [\n {\n \"email\": \"string\"\n }\n ]\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/contacts/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"name\": \"string\",\n \"items\": [\n {\n \"email\": \"string\"\n}\n]\n}\nresponse = requests.put(url, headers=headers, json=payload)\nprint(response.json())"
}
]
},
"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
Possible error codes: 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
Possible error codes: 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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/contacts/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/contacts/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
}
},
"components": {
"schemas": {
"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"
}
}
}
},
"Errors": {
"type": "object",
"properties": {
"error": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"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"
]
},
"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"
}
}
}
},
"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."
}
}
},
"ContactEmail": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address of the contact."
}
},
"required": [
"email"
]
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
},
"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."
}
}
}
}
}
}