Kaiten API

KaitenDevelopers

rest external webhooks webhooks scim user metadata imports addons

Create custom directory

POST

https://example.kaiten.ru/api/latest/company/custom-directories

This endpoint is currently under active development. Parameters, attributes, and response formats are subject to change. Custom directories API is in beta and may change.

Creates a custom directory (catalog) with optional fields. Use `display_field_index` to choose which field is used as the display field; otherwise the first field is used.

All paths in this section are relative to /api/latest and require API authentication. Directory, field and record IDs are UUIDs. Creating, updating or deleting directories and fields requires the company's custom-properties management permission. To use a directory in cards, create a custom property through POST /company/custom-properties with type=directory and directory_id set to the returned directory ID.

Headers

Name	Value
Content-Type	application/json

Attributes

schema

{
 "$schema": "http://json-schema.org/draft-06/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "minLength": 1,
   "maxLength": 256,
   "description": "Custom directory name"
  },
  "description": {
   "oneOf": [
    {
     "type": "null",
     "description": "No description"
    },
    {
     "type": "string",
     "description": "Custom directory description"
    }
   ]
  },
  "multi_select": {
   "type": "boolean",
   "default": false,
   "description": "Allow selecting multiple directory records in a card's directory custom property"
  },
  "allow_editing": {
   "type": "boolean",
   "default": false,
   "description": "When enabled, directory records can be edited from cards without custom properties permission"
  },
  "display_field_index": {
   "type": "integer",
   "minimum": 0,
   "description": "Index of the field to use as a display field. If omitted, the first field is used."
  },
  "fields": {
   "type": "array",
   "description": "Directory fields definition",
   "items": {
    "type": "object",
    "properties": {
     "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "Field name"
     },
     "type": {
      "enum": [
       "string",
       "number",
       "date",
       "email",
       "url",
       "phone",
       "checkbox",
       "select",
       "user",
       "catalog",
       "directory_link",
       "file"
      ],
      "description": "Field type"
     },
     "required": {
      "type": "boolean",
      "default": false,
      "description": "Required field flag"
     },
     "sort_order": {
      "type": "integer",
      "minimum": 0,
      "description": "Field position"
     },
     "custom_property_uid": {
      "oneOf": [
       {
        "type": "null",
        "description": "Empty custom property reference"
       },
       {
        "type": "string",
        "format": "uuid",
        "description": "Custom property UID (required for select/user/catalog fields)"
       }
      ]
     },
     "linked_directory_id": {
      "oneOf": [
       {
        "type": "null",
        "description": "Empty linked directory reference"
       },
       {
        "type": "string",
        "format": "uuid",
        "description": "Linked custom directory ID (required for directory_link fields)"
       }
      ]
     }
    },
    "required": [
     "name",
     "type"
    ]
   }
  }
 },
 "required": [
  "name"
 ]
}

Name	Type	Constraints	Description
name required	string	minLength: 1 maxLength: 256	Custom directory name
description	null		No description
description	string		Custom directory description
multi_select	boolean default:false		Allow selecting multiple directory records in a card's directory custom property
allow_editing	boolean default:false		When enabled, directory records can be edited from cards without custom properties permission
display_field_index	integer	minimum: 0	Index of the field to use as a display field. If omitted, the first field is used.
fields	array of objects Schema		Directory fields definition

Responses

200

Description	Response type	Example
Success	Object	Open

Response Attributes

Name	Type	Description
id	string	Directory ID (UUID)
name	string	Directory name
description	null \| string	Directory description
condition	enum	Directory condition: active \| inactive \| removed
settings	object Schema	Directory settings
author_uid	string	Author user UID (UUID)
company_uid	string	Company UID (UUID)
created	string	Create date
updated	string	Last update timestamp
fields	array of objects Schema	Directory fields

400

Description	Response type	Example
Validation error	Object	Open

Response Attributes

Name	Type	Description
message	string	Error message

401

Description	Response type	Example
Invalid token	String	Open

403

Description	Response type	Example
Forbidden		Response body does not exist

Examples

Create custom directory

{
  "name": "Contacts",
  "description": "Company contacts directory",
  "multi_select": false,
  "allow_editing": false,
  "fields": [
    {
      "name": "Name",
      "type": "string",
      "required": true
    },
    {
      "name": "Email",
      "type": "email"
    },
    {
      "name": "Phone",
      "type": "phone"
    }
  ]
}

Kaiten

Addons terms of use Personal data processing policy

If you have any questions or need help with integration feel free to write us at support@kaiten.ru

Company domain

Raw Body(json format)

  1  curl --request POST \
  2       --url 'https://example.kaiten.ru/api/latest/company/custom-directories' \
  3       --header 'Accept: application/json' \
  4       --header 'Content-Type: application/json'
  5

Response

ClickTry It!to start a request and see the response here!