Page tree
Skip to end of metadata
Go to start of metadata

Custom field types

The type of custom field (e.g. text area, select box) is denoted by a unique identifier.

Field type

Identifier

Text

1

Text area

2

Password

3

Checkbox

4

Radio

5

Select

6

Multi select

7

Custom

8

Linked select fields

9

Date

10

File

11

GET /Tickets/TicketCustomField/$ticketid$

API method available in version 4.01.220

Icon

This API method is either only available or was modified in Kayako version 4.01.220 (and above). You should update your helpdesk before relying on this method.

Retrieve a list of a ticket's custom fields.

Arguments

Red = required

Name

Description

$ticketid$

The unique numeric identifier of the ticket.

Response

An 'HTTP 200 OK' with the following XML payload:

POST /Tickets/TicketCustomField/$ticketid$

API method available in version 4.40.882

Icon

This API method is either only available or was modified in Kayako version 4.40.882 (and above). You should update your helpdesk before relying on this method.

Icon

POST and PUT are not interchangeable. POST is only used to create a new record (so if you POST a custom field set to a ticket which already has a custom field set, it will overwrite the existing set).

Update the custom field values for a ticket.

Arguments (POST variables)

Red = required, Blue = Either of the value

Name

Description

$FIELDNAME$

The unique field name of the custom field with the corresponding values to be updated with. This field name is dispatched as an argument in the custom field result above.

Response

An 'HTTP 200 OK' with the following XML payload:

  • No labels

11 Comments

  1. I'm not clear on how to set a custom field value.  I see the parameter to identify the field to update but to parameter for the value.

  2. I also had trouble to understand how to update the values, but looking into this more closely I think that you need to send fieldname=value pairs as POST data. So to update "Test" field and "Date" field (as in example) you'll need to send:

    ab32ds122=New%20text%20value&z13nc8923=03%2F14%2F2012

    as your POST data.

    1. It seems that you need to send all field values in POST request (with an exception of file custom field), otherwise missing fields values will be changed to an empty string by the server.

      1. We are distinguishing between PUT/POST kind of like the ATOM post protocol. POST 'creates new' and PUT 'updates existing'. Because you're POSTing, it will 'create a new' custom field record. I think you're expecting the functionality of a PUT from our POST method. We haven't implemented PUT yet, but we will make sure you can selectively update fields.

  3. Things to remember when POSTing custom field values (I think it should go to the documentation above):

    1. General things:
      • all fields should be sent, with exceptions mentioned further
    2. Radio and Select fields:
      • the value is field option identifier
    3. Checkbox and Multi select fields:
      • the parameter name must contain [] at the end
      • the value is field option identifier
      • it should be repeated for each selected option
      • to clear all selected values don't send the field value at all
    4. Linked Select fields:
      • two parameters must be sent (parent is first level select, child is second level select):
        • <field name>[0]=<parent selected option id>
        • <field name>[1][<parent selected option id>]=<child selected option id>
    5. File fields:
      • if you don't want to update the file it don't have to be sent
      • whole POST body must be multipart/form-data encoded
    1. So I finally did get this to work using the notes above for Linked Select fields that Tomasz notes.

      The GET /Tickets/TicketCustomField/$ticketid$ seems to be the issue.

      I fixed the issue in our code in the class.Controller_TicketCustomField.php

      What was happening is if the parent select value was 151, the API would return correctly. Otherwise, things were always defaulting to Array1151. The code fix selects the proper key instead of the first one from Array1.

  4. I can't seem to get this to work. I am attempting set the values of two custom fields (of which there are only 2) one of type 1 (text) and one of type 6 (select).

    I am POSTing:

    <field name1>=Test%20Value&<field name2>=5&apikey=<apikey>&salt=<salt>&signature=<signature>

    (where 5 is a valid field option identifier for this field)

    to:

    http://myurl/api/index.php?/Tickets/TicketCustomField/<ticketid>

    The response I am getting does not match the one shown here, it looks like:

    <?xml version="1.0" encoding="UTF-8"?>
    <customfields>
      <group id="1" title="Group 1">
        <field id="4" title="Field 4" type="6" name=<field name2> />
      </group>
      <group id="2" title="Group 2">
        <field id="2" title="Field 2" type="1" name=<field name1> />
      </group>
    </customfields>

    It does set the fields, but it sets them both to empty strings.

    Any idea what I'm doing wrong?

    1. Make sure that User Editable flag is enabled for every field.

      1. Thanks! Such a simple solution, this should also be mentioned in the documentation above.

        1. I'm not sure if it's a bug or feature(smile)

  5. In the interest of helping the next person..  

    When POSTing, if you receive an error message  with a similar format as the following: 

    Custom Field Data is Invalid: ys4ssjpoce 

    This might mean that your custom field with CustomFieldName = ys4ssjpoce is required (and is not being set).  Obvious, I know, but it was less obvious to me, when I was trying to set a different CustomField (with a different CustomFieldName identifier) that the random characters was in reality, an identifier for a CustomFieldName.