Skip to end of metadata
Go to start of metadata
Table of contents

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
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
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.
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:

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

11 Comments

comments.show.hide

  1. Mar 06, 2012

    Dave Hall

    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. May 04, 2012

    Tomasz Sawicki

    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. Mar 07, 2012

      Tomasz Sawicki

      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. Mar 12, 2012

        Jamie Edwards

        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. May 04, 2012

    Tomasz Sawicki

    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. May 23, 2012

      Byron Mann

      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 Array[1][151]. The code fix selects the proper key instead of the first one from Array[1].

  4. May 22, 2012

    Albert VanderMeulen

    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. May 22, 2012

      Tomasz Sawicki

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

      1. May 22, 2012

        Albert VanderMeulen

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

        1. May 22, 2012

          Tomasz Sawicki

          I'm not sure if it's a bug or feature

  5. Jan 10, 2013

    Lairon

    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.