Udesk-Customer service solution leader

Get Custom Fields List

This interface is used to retrieve the list of created custom fields.

Request Method

GET /custom_fields To use this interface, you would send a GET request to the specified endpoint (/custom_fields) to receive a list of custom fields that have been set up in the system. These fields can be used to store additional information about contacts or other entities within the system. The response will likely be a JSON object containing the details of each custom field, such as the field name, type, and any other relevant metadata.

Request Parameters

Parameter Name	Required	Type	Description	Restrictions
category	Optional	String	The type of custom fields to retrieve, see details below, default is ticket	Enum, Value Range: `["ticket", "customer", "organization"]` If other values are passed in, it will not result in an error, but it will be treated as ticket

category Description

Option	Description
ticket	Ticket custom fields
customer	Customer custom fields
organization	Customer company custom fields

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
fields	Array	List of custom fields, see details below

custom_fields Element Description

Attribute Name	Type	Description
id	Integer	ID
field_name	String	Field identifier
field_label	String	Field display name
content_type	String	Field type, see details below
comment	String	Field remark
updated_at	DateTime	Last update time of the field
options	Array	Field options, only returned for select type fields, see details below
customer_permission	String	Customer permissions, only returned for customer and ticket fields
agent_permission	String	Agent permissions, only returned for customer and customer company fields
calculate_result_type	String	Calculation field result type, only returned for calculation fields

content_type Value Range

Value	Description
text	Single line text
area_text	Multi-line text
date	Date
time	Time
datetime	Date and time
link	Hyperlink
location	Location
number	Positive integer
numeric	Numeric
droplist	Dropdown list
radio	Radio button
checkbox	Checkbox
chained_droplist	Cascade
calculate	Calculation field

The value range of content_type will expand with the addition of features, it is recommended to maintain extensibility for new types in business logic.
The structure of options for each custom field type is shown in the example.

calculate_result_type Value Range

Value	Description
numeric	Number
duration	Duration
percentage	Percentage

options Description

Array element structure

Attribute Name	Type	Description
title	String	Option text description
value	String	Option value
default	Boolean	Whether it is the default option
is_hide	Boolean	Whether it is hidden
subs	Array	Sub-options, only included in cascade fields, with the same structure as options

customer_permission Value Range

Value	Description
none	Invisible to customers
readonly	Visible to customers, but not editable
readwrite	Editable by customers
must	Required by customers

agent_permission Value Range

Value	Description
readonly	Visible to agents, but not editable
readwrite	Editable by agents
must	Required by agents

Example

Request

curl -s https://demo.udesk.cn/open_api_v1/custom_fields?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&category=customer

Response

{
    "code": 1000,
    "custom_fields": [
        {
            "field_name": "TextField_1",
            "field_label": "text field",
            "content_type": "text",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "readwrite",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_2",
            "field_label": "multi-line text field",
            "content_type": "area_text",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "cusotmer_permission": "readwrite",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_3",
            "field_label": "date field",
            "content_type": "date",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "read",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_4",
            "field_label": "date time field",
            "content_type": "datetime",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "read",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_5",
            "field_label": "link field",
            "content_type": "link",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "must",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_6",
            "field_label": "location field",
            "content_type": "location",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_7",
            "field_label": "time field",
            "content_type": "time",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_8",
            "field_label": "number field",
            "content_type": "number",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "none",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_9",
            "field_label": "numeric field",
            "content_type": "numeric",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "SelectField_1",
            "field_label": "droplist field",
            "content_type": "droplist",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "customer_permission": "read",
            "agent_permission": "readwrite",
            "options": [
                {"title": "option1", "value": "0"},
                {"title": "option２", "value": "1"}
            ]
        },
        {
            "field_name": "SelectField_2",
            "field_label": "radio field",
            "content_type": "radio",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "customer_permission": "read",
            "agent_permission": "readwrite",
            "options": [
                {"title": "option1", "value": "1"},
                {"title": "option2", "value": "0"}
            ]
        },
        {
            "field_name": "SelectField_3",
            "field_label": "checkbox field",
            "content_type": "checkbox",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "customer_permission": "none",
            "agent_permission": "must",
            "options": [
                {"title": "option１", "value": "3"},
                {"title": "option２", "value": "4"},
                {"title": "option３", "value": "1"},
                {"title": "option４", "value": "7"}
            ]
        },
        {
            "field_name": "SelectField_4",
            "field_label": "chained_droplist field",
            "content_type": "chained_droplist",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": [
                {"title": "option1", "value": "0", "subs": [
                    {"title": "sub option 1", "value": "0", "subs": [
                        {"title": "sub option 2", "value": "0"}
                    ]}
                ]},
                {"title": "option2", "value": "0", "subs": [
                    {"title": "sub option3", "value": "0"}
                ]}
            ],
            "customer_permission": "none",
            "agent_permission": "must"
        }
    ]
}

Retrieve a Single Custom Field

This interface is used to retrieve details of a single custom field.

Request Method

GET /custom_fields/:field_name

Request Parameters

None

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
field	Object	Refer to the custom_fields element description above for specific field meanings

Example

curl https://demo.udesk.cn/open_api_v1/custom_fields/SelectField_1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
Response:
{
  "code": 1000,
  "field": {
    "id": 1,
    "field_name": "SelectField_1",
    "field_label": "Dropdown List",
    "content_type": "droplist",
    "comment": "",
    "updated_at": "2020-10-19T13:37:01.000+08:00",
    "customer_permission": "readwrite",
    "options": [
        {
            "title": "a",
            "value": "0"
        },
        {
            "title": "b",
            "value": "1",
            "default": true
        },
        {
            "title": "c",
            "value": "2"
        }
    ]
  }
}

Update Custom Field

This interface is used to update a specified custom field. Cascading fields are not supported.

Request Method

PUT /custom_fields/:field_name

You can obtain information about all custom fields through the Get Custom Field List interface.

Request Parameters

Parameter	Required	Type	Description
field_name	Yes	String	The `field_name` parameter can be obtained from the field ID column in the custom field configuration page, or from the `field_name` field in the response data of the Get Custom Field List API. For example, `TextField_97`, `SelectField_166`
title	No	String	Custom field title
comment	No	String	Custom field remark
select_options	No	Array	Selection field option parameters, required only when updating selection fields. If you do not update the options of a selection field, this parameter can be omitted.

Description of Elements in `select_options`

You can obtain information about custom fields through the Get Custom Field List interface.

Parameter	Required	Type	Description	Restrictions
title	Yes	String	Option title
value	Yes	String	Option value	1. `value` is automatically generated by the system and should not be modified! 2. When adding a new option, there is no need to pass the `value` option!
default	No	Boolean	Default active option	If this parameter is used, its value can only be `true`

value is automatically generated by the system and should not be modified! When adding a new option, there is no need to pass the value option!

Example

Update a Single Select Field

curl https://demo.udesk.cn/open_api_v1/custom_fields/SelectField_1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X PUT \
-H 'content-type:application/json' \
-d '
{
  "title": "API test change single select custom field",
  "comment": "API test change single select custom field",
  "select_options": [
      {
          "title": "First option",
          "value": "0",
          "default": true
      },
      {
          "title": "Second option",
          "value": "1",
          "is_hide": true
      },
      {
          "title": "Add third option",
      }
  ]
}'

Update a Single Line Text Field

curl https://demo.udesk.cn/open_api_v1/custom_fields/TextField_1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X PUT \
-H 'content-type:application/json' \
-d '
{
  "title": "API test change single line text custom field",
  "comment": "API test change single line text custom field",
}'

Response Value

{
  "code": 1000,
  "message": "Update successful"
}

Update Custom Fields

This interface is used to update specified custom fields and does not support cascading fields.

Request Method

PUT /custom_fields/:field_name

You can obtain all custom field information through the Get Custom Field List interface.

Request Parameters

Parameter	Required	Type	Description
field_name	Yes	String	The `field_name` parameter can be obtained from the field ID column in the custom field configuration page, or from the `field_name` field in the data returned by the Get Custom Field List API, such as `TextField_97`, `SelectField_166`
title	No	String	Custom field title
comment	No	String	Custom field note
select_options	No	Array	Selection field option parameters, only required when updating selection fields. If you do not update the options of a selection field, this parameter can be omitted

Explanation of Elements in `select_options`

You can obtain custom field information through the Get Custom Field List interface.

Parameter	Required	Type	Description	Restrictions
title	Yes	String	Option title
value	Yes	String	Option value	1. `value` is automatically generated by the system, do not modify it! 2. When adding a new option, there is no need to pass the `value` option!
default	No	Boolean	Default active option	If this parameter is used, its value can only be `true`

value is automatically generated by the system, do not modify it! When adding a new option, there is no need to pass the value option!

Examples

Update a Single Select Field

curl https://demo.udesk.cn/open_api_v1/custom_fields/SelectField_1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X PUT \
-H 'content-type:application/json' \
-d '
{
  "title": "API test modifies a single-choice select box custom field",
  "comment": "API test modifies a single-choice select box custom field",
  "select_options": [
      {
          "title": "First option",
          "value": "0",
          "default": true
      },
      {
          "title": "Second option",
          "value": "1",
          "is_hide": true
      },
      {
          "title": "Add third option",
      }
  ]
}'

Update a Single Line Text Field

curl https://demo.udesk.cn/open_api_v1/custom_fields/TextField_1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X PUT \
-H 'content-type:application/json' \
-d '
{
  "title": "API test modifies a single-line text custom field",
  "comment": "API test modifies a single-line text custom field",
}'

Return Value

{
  "code": 1000,
  "message": "update success"
}

Get Corresponding Options for Large Drop-down Fields

Basic Information

Path：
/open_api_v1/custom_fields/large_droplists/{field_id} Method：
POST Interface Description:
This interface is for large drop-down fields and gets the corresponding options list based on the given filter conditions (supports pagination).

Request Parameters

Headers Content-Type: application/json Path Parameters

Parameter Name	Example	Remarks
field_id	SelectField_1	Drop-down field name
Query

Parameter Name	Required	Example	Remarks
email	Yes	<test@udesk.cn>	Administrator email
timestamp	Yes	1676616977	Timestamp
nonce	Yes	42a5551c	Nonce
sign_version	Yes	v2
sign	Yes	c24ad2a82901c1014572a51381ef0f32b278bd7ccf998af5a0ed592536e6ecc1	Signature

Body

Name	Type	Required	Notes	Additional Information
title	string	Not Required	Dropdown option title	Exact query
value	string	Not Required	Dropdown option value
create_range	string	Not Required	Option creation time range (YYYY-MM-DD HH:mm,YYYY-MM-DD HH:mm)
update_range	string	Not Required	Option update time range (YYYY-MM-DD HH:mm,YYYY-MM-DD HH:mm)
page	number	Not Required	Page number (default is 1)
per_page	number	Not Required	Number of records per page (maximum 100, default 20)

Response Data

Name	Type	Required	Notes	Additional Information
code	number	Not Required	Response status code (1000 for success)
message	string	Not Required	Description of response status
meta	object	Not Required
├─ page	number	Not Required	Page number
├─ total_pages	number	Not Required	Total number of pages
├─ total_count	number	Not Required	Total number of records
select_options	object []	Not Required		Item Type: object
├─ title	string	Not Required	Option title
├─ value	string	Not Required	Option value
├─ is_hide	boolean	Not Required	Whether to hide
├─ default	boolean	Not Required	Whether it is the default option
├─ created_at	string	Not Required	Creation time
├─ updated_at	string	Not Required	Update time

Request Example

{
    "page": 1,
    "update_range": "2023-02-17 08:00,2023-02-17 12:00"
}

Response Example

{
    "code": 1000,
    "message": "success",
    "meta": {
        "page": 1,
        "total_pages": 10,
        "total_count": 300
    },
    "select_options": [
        {
            "title": "Option Title",
            "value": "1",
            "is_hide": false,
            "default": true,
            "created_at": "2023-02-17 11:11:11",
            "updated_at": "2023-02-17 11:11:11"
        }
    ]
}

Custom Field Structure Description

Description

Udesk currently supports two types of custom field names SelectField and TextField

Field Name	Type	Description
SelectField_1	Array	Select field type (including dropdown, checkbox, and associative fields), Type Name_Unique ID
TextField_1	String	Text field type, Type Name_Unique ID

Error Codes

Error Code	message Information	exception:message Information	Description
2005	The resource was not found	The specified custom field was not found	The format of the passed field_name is incorrect or the corresponding resource cannot be found based on the passed field_name
2015	Non-administrators cannot operate	Non-administrators cannot operate	The email used to call the interface must be an administrator email, and non-administrators cannot operate
2059	Open API signature is incorrect	Open API signature is incorrect	Open API signature is incorrect, refer to the authentication section of the documentation for details
2062	Parameter error	The title in the select_options array element is required	When modifying a custom field, the title in the select_options array element is required
	Parameter error	The field_name parameter only supports TextField	SelectField

Get Custom Fields List

Request Method

Request Parameters

category Description

Response Data

custom_fields Element Description

content_type Value Range

calculate_result_type Value Range

options Description

customer_permission Value Range

agent_permission Value Range

Example

Retrieve a Single Custom Field

Request Method

Request Parameters

Response Data

Example

Update Custom Field

Request Method

Request Parameters

Description of Elements in select_options

Example

Update a Single Select Field

Update a Single Line Text Field

Response Value

Update Custom Fields

Request Method

Request Parameters

Explanation of Elements in select_options

Examples

Update a Single Select Field

Update a Single Line Text Field

Return Value

Get Corresponding Options for Large Drop-down Fields

Basic Information

Request Parameters

Response Data

Request Example

Response Example

Custom Field Structure Description

Description

Error Codes

Products

Solutions

Resources

Description of Elements in `select_options`

Explanation of Elements in `select_options`