[Craig Brass]

Contents

• Introduction
  • SOAP
  • Parameters
  • Return Values
• Knowledge Base
  • getKnowledgeBaseCategories
  • getKnowledgeBaseArticles
  • getKnowledgeBaseArticle
  • rateKnowledgeBaseArticle
  • addKnowledgeBaseArticleComment
• Tickets
  • getDepartmentList
  • getDepartmentCustomFields
  • getPriorityList
  • getStatusList
  • getTotalSubmittedTickets
  • getSubmittedTicketsWithExtraRestrictions
  • getSubmittedTickets
  • getSubmittedTicket
  • submitTicket
  • postTicketReply
  • updateTicketProperties
  • getTicketAttachment
  • setCustomFieldValue
• Miscellaneous
  • updateEmailAddress
• Error Codes

Introduction

SOAP

Most of the functions in the SOAP interface operate in exactly the same way as the native PHP class; those functions which differ will be clearly documented as such.

Parameters

The first two parameters of each function are the API username ($user) and the API password ($password). The username must match the KAYAKO_API_USERNAME constant defined in /lib/config.php and the password must be the plain text (non-MD5 hashed) version of the KAYAKO_API_PASSWORD constant that was defined in the same file. These two parameters will not be documented below in order save space.

In addition, the SOAP API cannot support default parameter values, so if you're using SOAP you must pass every parameter, although you can use the shown default values which should have the same effect.

Return Values

Each API function can return either its expected return value (an array, integer, boolean, etc.) or a negative integer. Negative integers indicate errors. Please see the Error Codes section at the end of this document for details of the error values.

Note for SOAP users: If an error occurs while using the SOAP API, the error will be indicated as a SOAP fault. The fault's string will be "Kayako API Error" and the fault's detail will be the negative integer error code that would have been returned by the native class. You will almost certainly want to check for SOAP faults after every SOAP method call and display a more friendly error message. See our "example usage" thread for a SOAP demonstration showing an easy way of handling faults.

Knowledge Base

array getKnowledgeBaseCategories ( string $user , string $password , integer $categoryId = 0 )

This function allows you to get a list of categories inside another category or at root level.

Parameters

• integer categoryId The integer ID of the knowledgebase category to get a list of child categories for; use 0 for the root category

Returns

Returns an associative array of both category information and breadcrumb information. The "categories" element is a numeric array of category information, with each array looking like this:

• integer id: The numeric ID of this category
• string title: The title of this category

The "breadcrumbs" element contains an array of information that can be used to build a breadcrumb trail. There will be one element per parent category (of the specified category ID), in order of ancestry, with the root category first. Each element will be an array looking like this:

• integer categoryid: The numeric ID of the category
• string title: The title of the category

Possible Errors

• -1
• -20

Example Return Value

One category inside the "Example Category 2.1" category, which is inside the "Example Category 2" category:

array(2) {  ["categories"]=>  array(1) {    [0]=>    array(2) {      ["id"]=>      int(3)      ["title"]=>      string(20) "Example Category 2.1"    }  }  ["breadcrumbs"]=>  array(1) {    [0]=>    array(2) {      ["categoryid"]=>      int(2)      ["title"]=>      string(18) "Example Category 2"    }  }}

array getKnowledgeBaseArticles ( string $user , string $password , integer $categoryId )

This function allows you to get a list of articles and details about them that are inside a particular category or at root level.

Parameters

• integer categoryId The numeric ID of the knowledgebase category to get a list of articles for

Returns

Returns a 2-dimensional array of article information for the specified category, with the inner arrays looking like this:

• integer id: The numeric ID of this article
• string subject: The title of this article
• integer rating: The rating of this article as a number between 1 and 5

Possible Errors

• -1

Example Return Value

One article inside a category:

array(1) {  [0]=>  array(3) {    ["id"]=>    int(2)    ["subject"]=>    string(17) "Example Article 2"    ["rating"]=>    int(2)  }}

array getKnowledgeBaseArticle ( string $user , string $password , integer $articleId )

This function allows you to get the full details about a particular article for showing on a end user page for viewing one specific article. This function pulls all comments to the article as well.

Parameters

• integer articleId The numeric ID of the knowledgebase article to get information about

Returns

Returns an array of knowledgebase article details on success:

• array breadcrumb: An array of information that can be used to build a breadcrumbs trail. There will be one element per parent category, in order of ancestry, with the root category first. Each element will be an array looking like this:
  • integer categoryid: The numeric ID of the category
  • string title: The title of the category
• string title: The title of this article
• string body: The description of this article
• integer date: A Unix timestamp representing the time when this article was created
• integer rating: The rating of this article, as an integer from 1-5
• array comments: An array of comments on this article, with the earliest comments first. Each array element is an array looking like this:
  • string name: The full name of the poster of this comment
  • integer date: The time at which this comment was posted, as a Unix timestamp
  • string body: The body of the comment itself

Possible Errors

• -1
• -21

Example Return Value

Article inside the "Test 2" category:

array(6) {  ["breadcrumbs"]=>  array(1) {    [0]=>    array(2) {      ["categoryid"]=>      int(2)      ["title"]=>      string(18) "Example Category 2"    }  }  ["title"]=>  string(18) "Example Category 2"  ["body"]=>  string(22) "Category 2 Description"  ["date"]=>  int(1203700518)  ["rating"]=>  int(2)  ["comments"]=>  array(3) {    [0]=>    array(3) {      ["name"]=>      string(7) "Foo Bar"      ["date"]=>      int(1214493071)      ["body"]=>      string(10) "Comment #1"    }    [1]=>    array(3) {      ["name"]=>      string(7) "Foo Bar"      ["date"]=>      int(1214493085)      ["body"]=>      string(10) "Comment #2"    }    [2]=>    array(3) {      ["name"]=>      string(7) "Foo Bar"      ["date"]=>      int(1214493354)      ["body"]=>      string(10) "Comment #3"    }  }}

boolean rateKnowledgeBaseArticle ( string $user , string $password , integer $articleId , boolean $rateType )

This allows you to submit a rating for a particular article (either the article was helpful or it wasn't) so that the rating inside Kayako can be updated.

Parameters

• integer articleId The numeric ID of the article to rate
• boolean rateType The type of rating to give this article; true to rate it positively, or false to rate it negatively

Returns

Returns true on success

Possible Errors

• -1
• -21

Example Return Value

Successful rating:

bool(true)

integer addKnowledgeBaseArticleComment ( string $user , string $password , integer $articleId , string $posterName , string $comment )

This allows you to submit the comment of an end user to a particular article.

Parameters

• integer articleId The numeric ID of the article to add this comment to
• string posterName The full name of the poster of this comment
• string comment The body of this comment

Returns

Returns the ID of the newly posted comment on success

Possible Errors

• -1
• -11
• -21

Example Return Value

Successful comment:

int(29)

Tickets

array getDepartmentList ( string $user , string $password )

This function gets a list of available departments which is useful for showing on the Submit Ticket page.

Parameters

(None)

Returns

Returns a 2-dimensional array of ticket department information on success, with the inner array looking like this:

• integer id: The numeric ID of this department
• string title: The title/name of this department, e.g. "General"
• boolean ispublic: A boolean indicating if this is a publicly visible department
• boolean isdefault: Whether this is the default department
• integer order: An integer representing the order in which this priority should be displayed in lists

Possible Errors

• -1

Example Return Value

One department:

array(1) {  [0]=>  array(4) {    ["id"]=>    int(1)    ["title"]=>    string(7) "General"    ["ispublic"]=>    bool(true)    ["isdefault"]=>    bool(true)    ["order"]=>    int(0)  }}

array getDepartmentCustomFields ( string $user , string $password , integer $departmentId )

This function returns a list of all of the custom fields (in custom field groups) associated with the specified department.

Parameters

• integer departmentId The department ID to return custom field information about

Returns

Returns a multi-dimensional array of custom field information. The outer array contains details of each custom field group:

• integer id: The numeric ID of the custom field group
• string title: The title of the custom field group
• integer displayorder: Indicates the order in which this group should be displayed
• array fields: An array of details about each custom field in this group:
  • integer id: The numeric ID of the custom field
  • string title: The title of this custom field
  • integer fieldtype: The type of field that this field is:
    1. Text ()
    2. Text area ()
    3. Password ()
    4. Checkbox ()
    5. Radio ()
    6. Select ()
    7. Select Multiple ()
  • string defaultvalue: The field's default value (only applies for text, text area and password fields)
  • string description: The description of the field
  • integer displayorder: The order in which this field should be displayed
  • boolean isrequired: Whether this field is required
  • string options: The available option values for this field, with each option separated with a newline character ("\n" in PHP, C#, etc.) (only applies for checkbox, radio, select and select multiple fields)
  • string optionorders: The order in which each option value should be displayed. As with the options element, this is a flattened array, using a newline ("\n") character to separate each option. Each option order entry corresponds with the same numbered entry in the options element (only applies for checkbox, radio, select and select multiple fields)
  • string optionsselected: Whether each option is selected by default. As with the options element, this is a flattened array, using a newline ("\n") character to separate each option. Each option selected entry corresponds with the same numbered entry in the options element (only applies for checkbox, radio, select and select multiple fields)

Possible Errors

• -1
• -8

Example Return Value

Example 1:

array(2) {  [0]=>  array(4) {    ["id"]=>    int(1)    ["title"]=>    string(12) "Test Group 1"    ["displayorder"]=>    int(1)    ["fields"]=>    array(6) {      [0]=>      array(10) {        ["id"]=>        int(1)        ["title"]=>        string(12) "Text Field 1"        ["fieldtype"]=>        int(1)        ["defaultvalue"]=>        string(5) "Value"        ["description"]=>        string(22) "Test Field Description"        ["displayorder"]=>        int(1)        ["isrequired"]=>        bool(true)        ["options"]=>        NULL        ["optionorders"]=>        NULL        ["optionsselected"]=>        NULL      }      [1]=>      array(10) {        ["id"]=>        int(2)        ["title"]=>        string(12) "Text Field 2"        ["fieldtype"]=>        int(1)        ["defaultvalue"]=>        string(0) ""        ["description"]=>        string(0) ""        ["displayorder"]=>        int(2)        ["isrequired"]=>        bool(false)        ["options"]=>        NULL        ["optionorders"]=>        NULL        ["optionsselected"]=>        NULL      }      [2]=>      array(10) {        ["id"]=>        int(3)        ["title"]=>        string(9) "Text Area"        ["fieldtype"]=>        int(2)        ["defaultvalue"]=>        string(10) "BlahBlah"        ["description"]=>        string(23) "Text field description."        ["displayorder"]=>        int(3)        ["isrequired"]=>        bool(false)        ["options"]=>        NULL        ["optionorders"]=>        NULL        ["optionsselected"]=>        NULL      }      [3]=>      array(10) {        ["id"]=>        int(4)        ["title"]=>        string(14) "Password Field"        ["fieldtype"]=>        int(3)        ["defaultvalue"]=>        string(0) ""        ["description"]=>        string(4) "Pass"        ["displayorder"]=>        int(4)        ["isrequired"]=>        bool(false)        ["options"]=>        NULL        ["optionorders"]=>        NULL        ["optionsselected"]=>        NULL      }      [4]=>      array(10) {        ["id"]=>        int(5)        ["title"]=>        string(13) "Checkbox Test"        ["fieldtype"]=>        int(4)        ["defaultvalue"]=>        NULL        ["description"]=>        string(23) "A checkbox description."        ["displayorder"]=>        int(5)        ["isrequired"]=>        bool(false)        ["options"]=>        string(69) "Check Value 1Check Value 2Check Value 3Check Value 4Check Value 5"        ["optionorders"]=>        string(9) "12345"        ["optionsselected"]=>        string(9) "10101"      }      [5]=>      array(10) {        ["id"]=>        int(6)        ["title"]=>        string(10) "Radio Test"        ["fieldtype"]=>        int(5)        ["defaultvalue"]=>        NULL        ["description"]=>        string(0) ""        ["displayorder"]=>        int(6)        ["isrequired"]=>        bool(false)        ["options"]=>        string(35) "Radio Val 1Radio Val 2Radio Val 3"        ["optionorders"]=>        string(5) "123"        ["optionsselected"]=>        string(5) "010"      }    }  }  [1]=>  array(4) {    ["id"]=>    int(2)    ["title"]=>    string(12) "Test Group 2"    ["displayorder"]=>    int(2)    ["fields"]=>    array(2) {      [0]=>      array(10) {        ["id"]=>        int(7)        ["title"]=>        string(11) "Select Test"        ["fieldtype"]=>        int(6)        ["defaultvalue"]=>        NULL        ["description"]=>        string(11) "Desc Select"        ["displayorder"]=>        int(7)        ["isrequired"]=>        bool(false)        ["options"]=>        string(51) "Select Val 1Select Val 2Select Val 3Select Val 4"        ["optionorders"]=>        string(7) "1234"        ["optionsselected"]=>        string(7) "0010"      }      [1]=>      array(10) {        ["id"]=>        int(8)        ["title"]=>        string(20) "Select Multiple Test"        ["fieldtype"]=>        int(7)        ["defaultvalue"]=>        NULL        ["description"]=>        string(12) "Select Multi"        ["displayorder"]=>        int(8)        ["isrequired"]=>        bool(true)        ["options"]=>        string(20) "Blah 3Blah 2Blah 1"        ["optionorders"]=>        string(5) "321"        ["optionsselected"]=>        string(5) "101"      }    }  }}

array getPriorityList ( string $user , string $password )

This function gets a list of available priorities which is useful for showing on the Submit Ticket page.

Parameters

(None)

Returns

Returns a 2-dimensional array of ticket priority information on success, with the inner array looking like this:

• integer id: The numeric ID of this priority
• string title: The title/name of this status, e.g. "Low"
• integer order: An integer representing the order in which this priority should be displayed in lists
• boolean ispublic: Whether this is a publicly visible priority
• string forecolor: The hexadecimal colour code to use for the text of this priority, e.g. "#FF0000". Will be "inherit" if no foreground colour was set.
• string backcolor: The hexadecimal colour code to use for the background of this priority, e.g. "#FFEEEE". Will be "inherit" if no background colour was set.
• boolean iscustom: Whether this is a custom priority

Possible Errors

• -1

Example Return Value

Three priorities:

array(3) {  [0]=>  array(7) {    ["id"]=>    int(1)    ["title"]=>    string(3) "Low"    ["order"]=>    int(1)    ["ispublic"]=>    bool(true)    ["forecolor"]=>    string(7) "#8A8A8A"    ["backcolor"]=>    string(0) "inherit"    ["iscustom"]=>    bool(false)  }  [1]=>  array(7) {    ["id"]=>    int(2)    ["title"]=>    string(6) "Medium"    ["order"]=>    int(2)    ["ispublic"]=>    bool(true)    ["forecolor"]=>    string(7) "#000000"    ["backcolor"]=>    string(0) "inherit"    ["iscustom"]=>    bool(false)  }  [2]=>  array(7) {    ["id"]=>    int(3)    ["title"]=>    string(4) "High"    ["order"]=>    int(3)    ["ispublic"]=>    bool(true)    ["forecolor"]=>    string(7) "#F07D18"    ["backcolor"]=>    string(0) "inherit"    ["iscustom"]=>    bool(false)  }}

array getStatusList ( string $user , string $password )

This function gets a list of available ticket statuses which is useful for showing on the Submit Ticket page.

Parameters

(None)

Returns

Returns a 2-dimensional array of ticket status information on success, with the inner array looking like this:

• integer id: The numeric ID of this status
• string title: The title/name of this status, e.g. "Open"
• integer order: An integer representing the order in which this status should be displayed in lists
• boolean ispublic: Whether this is a publicly visible status
• string forecolor: The hexadecimal colour code to use for the text of this status, e.g. "#FF0000". Will be "inherit" if no colour was set

Possible Errors

• -1

Example Return Value

Three statuses:

array(3) {  [1]=>  array(5) {    ["id"]=>    int(1)    ["title"]=>    string(4) "Open"    ["order"]=>    int(1)    ["ispublic"]=>    bool(true)    ["forecolor"]=>    string(7) "#5C83B4"  }  [2]=>  array(5) {    ["id"]=>    int(2)    ["title"]=>    string(7) "On Hold"    ["order"]=>    int(2)    ["ispublic"]=>    bool(true)    ["forecolor"]=>    string(7) "#8BB467"  }  [3]=>  array(5) {    ["id"]=>    int(3)    ["title"]=>    string(6) "Closed"    ["order"]=>    int(3)    ["ispublic"]=>    bool(true)    ["forecolor"]=>    string(7) "#CF5D60"  }}

integer getTotalSubmittedTickets ( string $user , string $password , string $email )

This function gets the total tickets submitted by a particular user. This can then be used to work out how many pages to list in your pagination list if say only showing x amount of tickets per page.

Parameters

• string email The email address of the customer you want to get the number of tickets of

Returns

Returns the total number of tickets that this user has on their account as an integer

Possible Errors

• -1
• -2
• -3

Example Return Value

Three submitted tickets for this customer in total:

int(3)

Notes

Combine this with the $numPerPage and $page parameters of the getSubmittedTickets() function to handle pagination of tickets.

array getSubmittedTicketsWithExtraRestrictions ( string $user , string $password , string $email , integer $numPerPage = 10 , integer $page = 1 , string $sortBy = "lastactivity" , boolean $orderAsc = false , integer $minStartDate = -2147483648 , integer $maxStartDate = 2147483647 , integer $minLastActivity = -2147483648 , integer $maxLastActivity = 2147483647 , integer $minDueDate = -2147483648 , integer $maxDueDate = 2147483647 , integer $specificDepartment = 0 , integer $specificStatus = 0, integer $specificPriority = 0 )

This function gets a list of tickets and details about each ticket for a particular user for showing on a View Submitted Tickets page to the end user.

Parameters

• string email The email address of the customer to fetch a list of tickets for
• integer numPerPage The number of tickets to return in this request (think of it as the "LIMIT" clause in an SQL query)
• integer page The page number for this request (used with $numByPage to determine the "OFFSET" for this request's results)
• string sortBy The database table column to sort these results by. Must be one of: lastactivity, lastreplier, ticketstatusid, priorityid, departmentid
• boolean orderAsc If true, the results will be sorted in ascending order. Otherwise they'll be sorted in descending order.
• integer minStartDate The minimum start (creation) date of tickets to be returned. Should be a (signed) Unix timestamp. The default value is the minimum time representable by a signed 32-bit Unix timestamp, i.e. 13th Dec 1901 20:45:52 UTC.
• integer maxStartDate The maximum start (creation) date of tickets to be returned. Should be a (signed) Unix timestamp. The default value is the maximum time representable by a signed 32-bit Unix timestamp, i.e. 19th Jan 2038 03:14:07 UTC.
• integer minLastActivity The minimum last activity date of tickets to be returned. Should be a (signed) Unix timestamp. The default value is the minimum time representable by a signed 32-bit Unix timestamp, i.e. 13th Dec 1901 20:45:52 UTC.
• maximum maxLastActivity The minimum last activity date of tickets to be returned. Should be a (signed) Unix timestamp. The default value is the maximum time representable by a signed 32-bit Unix timestamp, i.e. 19th Jan 2038 03:14:07 UTC.
• integer minDueDate The minimum due date of tickets to be returned. Should be a (signed) Unix timestamp. The default value is the minimum time representable by a signed 32-bit Unix timestamp, i.e. 13th Dec 1901 20:45:52 UTC.
• integer maxDueDate The maximum due date of tickets to be returned. Should be a (signed) Unix timestamp. The default value is the maximum time representable by a signed 32-bit Unix timestamp, i.e. 19th Jan 2038 03:14:07 UTC.
• integer specificDepartment If not 0 (zero), only tickets in this department ID will be returned.
• integer specificStatus If not 0 (zero), only tickets with this status ID will be returned.
• integer specificPriority If not 0 (zero), only tickets with this priority ID will be returned.

Returns

Returns a 2-dimensional array of ticket information, with the inner array having these elements:

• integer id: The numeric ID of this ticket
• string mask: The "mask ID" of this ticket, or the same numeric ID as the above "id" if Kayako's numbering is set to sequential
• integer startdate: A Unix timestamp representing the time when this ticket was created
• integer lastactivity: A Unix timestamp representing the time when this ticket was last replied to
• integer duetime: A Unix timestamp representing the time at which this ticket is due
• string lastreplier: The full name of the last user to reply to this ticket
• integer status: The numeric ID of the status of this ticket
• integer priority: The numeric ID of the priority of this ticket
• integer department: The numeric ID of the department of this ticket
• string subject: The subject of this ticket

Possible Errors

• -1
• -2
• -3
• -4
• -5
• -6

Example Return Value

Two tickets to list:

array(2) {  [0]=>  array(7) {    ["id"]=>    int(5)    ["mask"]=>    string(10) "ABC-111111"    ["startdate"]=>    int(1214405560)    ["lastactivity"]=>    int(1214405560)    ["duetime"]=>    int(1215516671)    ["lastreplier"]=>    string(7) "Foo Bar"    ["status"]=>    int(1)    ["priority"]=>    int(3)    ["department"]=>    int(1)    ["subject"]=>    string(7) "Example"  }  [1]=>  array(7) {    ["id"]=>    int(6)    ["mask"]=>    string(10) "FOO-999999"    ["startdate"]=>    int(1214580183)    ["lastactivity"]=>    int(1214580183)    ["duetime"]=>    int(1215691294)    ["lastreplier"]=>    string(7) "Foo Bar"    ["status"]=>    int(1)    ["priority"]=>    int(4)    ["department"]=>    int(1)    ["subject"]=>    string(15) "Another Example"  }}

Changelog

• This function was added in version 1.0.2.
• The "startdate" and "duetime" return array elements were added in version 1.0.2.

array getSubmittedTickets ( string $user , string $password , string $email , integer $numPerPage = 10 , integer $page = 1 , string $sortBy = "lastactivity" , boolean $orderAsc = false )

Acts as a wrapper for getSubmittedTicketsWithExtraRestrictions(), passing default values for that function's extra parameters, thus ensuring that the public interface of this API didn't change when the extra restriction parameters were added. Otherwise identical to getSubmittedTicketsWithExtraRestrictions().

array getSubmittedTicket ( string $user , string $password , string $email , integer $ticketId )

This function allows you to get all details about a particular ticket for showing on a end user page for viewing one specific ticket. This function pulls all replies to the ticket as well.

Parameters

• string email The email address of the user that owns this ticket
• integer ticketId The numeric ID of the ticket to retrieve

Returns

Returns a boolean false if the specified ticket ID doesn't exist, otherwise returns a serialize()'d form of the following array:

• integer id: The numeric ID of this ticket
• string mask: The "mask ID" of this ticket, or the same ticketid as above if the numbering system is set to sequential in Kayako
• integer department: The numeric ID of the department that this ticket was submitted to
• integer status: The numeric ID of the current status of this ticket
• integer priority: The numeric ID of the priority of this ticket
• integer startdate: A Unix timestamp of the time that this ticket was submitted at
• integer lastactivity: A Unix timestamp of the last time that this ticket was replied to
• string subject: The subject of this ticket
• array posts: An array of posts in this ticket in ascending order, with the earliest posts first. Each post is an array looking like this:
  • integer id: The numeric ID of this post
  • integer date: A Unix timestamp of the time that this post was made
  • integer userid: The numeric ID of the user who made this post
  • string fullname: The full name of the user who made this post
  • string email: The email address of the user who made this post
  • boolean edited: Whether this post has been edited
  • integer editedbystaffid: The numeric ID of the staff member who edited this post (or 0 if it has never been edited)
  • integer editeddate: A Unix timestamp of the time at which this post was last edited (or 0 if it has never been edited)
  • boolean ishtml: Whether this post is HTML
  • integer staffid: The ID of the staff member that made this post (or 0 if it was not posted by a staff member)
  • string contents: The body of this post
  • array attachments: An array of attachments. Each attachment is an array looking like this:
    • integer id: The ID of the attachment
    • string name: The original name of this attachment file (e.g. "example.txt")
    • string mimetype: The MIME type of this attachment (e.g. "text/plain")
    • integer size: The filesize in bytes of this attachment
• array custom: An array of custom field value groups for this ticket:
  • integer id: The ID of the custom field group with which the value is associated
  • string title: The title of the custom field group with which the value is associated
  • integer displayorder: The order in which this group should be displayed
  • array fields: An array of custom fields in this group
    • integer id: The ID of this custom field
    • string name: The name of this custom field
    • integer type: The field type of this custom field:
      1. Text ()
      2. Text area ()
      3. Password ()
      4. Checkbox ()
      5. Radio ()
      6. Select ()
      7. Select Multiple ()
    • string value: Value given for this custom field for this ticket (if the field type is checkbox or select multiple, this will be a newline ("\n") separated list of selected values)

Possible Errors

• -1
• -2
• -3
• -13
• -14

Example Return Value

Valid ticket with 1 post and an attachment:

array(9) {  ["id"]=>  int(25)  ["mask"]=>  string(10) "BAR-555555"  ["department"]=>  int(1)  ["status"]=>  int(1)  ["priority"]=>  int(6)  ["startdate"]=>  int(1214405583)  ["lastactivity"]=>  int(1214991346)  ["subject"]=>  string(7) "Example"  ["posts"]=>  array(1) {    [0]=>    array(12) {      ["id"]=>      int(34)      ["date"]=>      int(1214574104)      ["userid"]=>      int(4)      ["fullname"]=>      string(7) "Foo Bar"      ["email"]=>      string(19) "example@example.com"      ["edited"]=>      bool(false)      ["editedbystaffid"]=>      int(0)      ["editeddate"]=>      int(0)      ["ishtml"]=>      bool(false)      ["staffid"]=>      int(0)      ["contents"]=>      string(17) "Example Post Body"      ["attachments"]=>      array(1) {        [0]=>        array(4) {          ["id"]=>          int(4)          ["name"]=>          string(11) "example.txt"          ["type"]=>          string(10) "text/plain"          ["size"]=>          int(1346)        }      }    }  }  ["custom"]=>  array(2) {    [0]=>    array(4) {      ["id"]=>      int(1)      ["title"]=>      string(12) "Test Group 1"      ["displayorder"]=>      int(1)      ["fields"]=>      array(6) {        [0]=>        array(4) {          ["id"]=>          int(1)          ["name"]=>          string(12) "Text Field 1"          ["type"]=>          int(1)          ["value"]=>          string(6) "Valuez"        }        [1]=>        array(4) {          ["id"]=>          int(2)          ["name"]=>          string(12) "Text Field 2"          ["type"]=>          int(1)          ["value"]=>          string(14) "me@example.com"        }        [2]=>        array(4) {          ["id"]=>          int(3)          ["name"]=>          string(9) "Text Area"          ["type"]=>          int(2)          ["value"]=>          string(10) "BlahBlah"        }        [3]=>        array(4) {          ["id"]=>          int(4)          ["name"]=>          string(14) "Password Field"          ["type"]=>          int(3)          ["value"]=>          string(1) "z"        }        [4]=>        array(4) {          ["id"]=>          int(5)          ["name"]=>          string(13) "Checkbox Test"          ["type"]=>          int(4)          ["value"]=>          string(55) "Check Value 5Check Value 4Check Value 2Check Value 1"        }        [5]=>        array(4) {          ["id"]=>          int(6)          ["name"]=>          string(10) "Radio Test"          ["type"]=>          int(5)          ["value"]=>          string(11) "Radio Val 1"        }      }    }    [1]=>    array(4) {      ["id"]=>      int(2)      ["title"]=>      string(12) "Test Group 2"      ["displayorder"]=>      int(2)      ["fields"]=>      array(2) {        [0]=>        array(4) {          ["id"]=>          int(7)          ["name"]=>          string(11) "Select Test"          ["type"]=>          int(6)          ["value"]=>          string(12) "Select Val 4"        }        [1]=>        array(4) {          ["id"]=>          int(8)          ["name"]=>          string(20) "Select Multiple Test"          ["type"]=>          int(7)          ["value"]=>          string(13) "Blah 2Blah 3"        }      }    }  }}

Notes

By passing both the email address and ticket ID, this function can ensure that customers are only allowed to view their own tickets.

[Non-SOAP] array submitTicket ( string $user , string $password , string $email , integer $departmentId , integer $priorityId , string $fullName , string $subject , string $message , boolean $sendAuto = true , integer $passType = 0 , string $pass = NULL , array $customs = array() )

[SOAP] array submitTicket ( string $user , string $password , string $email , integer $departmentId , integer $priorityId , string $fullName , string $subject , string $message , array $attachments = array() , boolean $sendAuto = true , integer $passType = 0 , string $pass = NULL , array $customs = array() )

This function allows you to submit a new ticket for the end user to Kayako.

Parameters

• string email The email address of the customer who is submitting this new ticket
• integer departmentId The numeric ID of the department to submit this ticket to
• integer priorityId The numeric ID of the priority to submit this ticket as
• string fullName The full name of the user who is submitting this ticket
• string subject The subject to use for this ticket
• string message The body of this new ticket
• [SOAP only] array attachments An 2-dimensional array of attachment information, with the inner array looking like this:
  • string name The original filename of the attachment on the user's computer
  • string type The MIME type of the file
  • string url The URL at which the file is (temporarily) hosted. Your API client must make the attachment(s) available for download by this API; the API will then download the attachment while processing the ticket submission. Your client can then delete the attachment, if desired, once this submitTicket() method returns
• boolean sendAuto Whether Kayako will send an auto-response email for this ticket
• integer passType Indicates whether the $pass parameter is plain text (0) or an MD5 hash (1). Only used if a new Kayako user account needs to be created for this user before the ticket is submitted
• string pass The password to use for the new Kayako user account if one needs to be created before the ticket is submitted (i.e. if no account already exists with the email address passed as the $email parameter). If you don't want your customers to be able to log in to Kayako directly, this can just be a random string, or can be left as a blank string, in which case the API will generate a random password
• array customs Any custom field values to submit along with this ticket. This is an array with each element being another array with this structure:
  • integer id The ID of the custom field to supply a value for
  • string value The value of the custom field for this ticket (if the field is of the checkbox or multiple select type, this should be a newline ("\n") separated list of selected values)

Returns

Returns an associative array containing the newly submitted ticket's ID and mask:

• integer id: The new ticket's numeric ID
• string mask: The new ticket's "mask" ID

Possible Errors

• -1
• -2
• -7
• -8
• -9
• -10

Example Return Value

Successful submission:

array(2) {  ["id"]=>  int(1)  ["mask"]=>  string(10) "ABC-123456"}

Notes

The "attachment" parameter is only used by the SOAP interface. In the native PHP interface, the $_FILES superglobal is used, but note that the HTML file fields used to select the attachments must be named "opt_file[]"!

[Non-SOAP] boolean postTicketReply ( string $user , string $password , string $email , integer $ticketId , string $reply )

[SOAP] boolean postTicketReply ( string $user , string $password , string $email , integer $ticketId , string $reply , string $attachments = array() )

This function allows you to submit a reply to an existing ticket.

Parameters

• string email The email address of the user who owns this ticket (to ensure that people can only reply to their own tickets)
• integer ticketId The numeric ID of the ticket you wish to post a reply to
• string reply The message body to add to this ticket as a reply
• [SOAP only] array attachments An 2-dimensional array of attachment information, with the inner array looking like this:
  • string name The original filename of the attachment on the user's computer
  • string type The MIME type of the file
  • string url The URL at which the file is (temporarily) hosted. Your API client must make the attachment(s) available for download by this API; the API will then download the attachment while processing the ticket reply submission. Your client can then delete the attachment, if desired, once this postTicketReply() method returns

Returns

Returns true on success

Possible Errors

• -1
• -2
• -3
• -12
• -13
• -14

Example Return Value

Successful reply:

bool(true)

Notes

The "attachment" parameter is only used by the SOAP interface. In the native PHP interface, the $_FILES superglobal is used, but note that the HTML file fields used to select the attachments must be named "opt_file[]"!

boolean updateTicketProperties ( string $user , string $password , string $email , integer $ticketId , integer $newStatus = 0 , integer $newPriority = 0 )

This function allows you to change the status and/or priority of a ticket.

Parameters

• string email The email address of the creator of this ticket, to ensure that only the ticket owner can change properties of a ticket
• integer ticketId The numeric ID of the ticket you wish to change the status and/or priority of
• integer newStatus The numeric ID of the status you wish to change this ticket to
• integer newPriority The numeric ID of the priority you wish to change this ticket to

Returns

Returns true on success

Possible Errors

• -1
• -2
• -3
• -13
• -14
• -16
• -17
• -18

Example Return Value

Successful update:

bool(true)

boolean setCustomFieldValue ( string $user , string $password , integer $typeid , integer $customField , string $value )

This function allows you to change the value of custom fields on existing tickets.

Parameters

• integer typeid Despite its name, this is the ID of the ticket associated with the custom field that you want to change the value of (typeid is the internal Kayako name for this value)
• integer customField The ID of the custom field that you want to change the value of
• string value The new value of the specified custom field. For field types with multiple values (i.e. checkbox groups and fields allowing multiple selections), the selected values should be joined together with newline characters ("\n" in PHP, C#, etc.), for example "Checkbox Value 1\nCheckbox Value 2"

  Returns

  Returns true on success

  Possible Errors

  • -1
  • -23
  • -24
  • -25
  • -26

  Example Return Value

  Successful change:

  bool(true)

  array getTicketAttachment ( string $user , string $password , string $email , integer $ticketId , integer $attachmentId )

  Returns details for the specified ticket attachment, allowing your API client to act as a download proxy for the user.

  Parameters

  • string email The email address of the creator of this ticket
  • integer ticketId The numeric ID of the ticket you wish to fetch an attachment for
  • integer attachmentId The numeric ID of the attachment you wish to retrieve

  Returns

  Returns an associative array of attachment details:

  • integer size: The size of the attachment file in bytes (can be used to set the Content-Length header)
  • string name: The original filename of the attachment (can be used to set the Content-Disposition header's filename parameter)
  • string type: The MIME type of the attachment (can be used to set the Content-Type header)
  • [SOAP] string url: The URL that your client can use to download the attachment's content before sending it to the end-user
  • [Non-SOAP] string file: The absolute path and filename of the attachment file. Note that if the attachment was stored in the Kayako database, this file will be temporary and will only exist for the lifetime of the script!

  Possible Errors

  • -1
  • -2
  • -3
  • -13
  • -14
  • -19

  Example Return Value

  Example Attachment (Using SOAP):

  array(4) {  ["size"]=>  int(1346)  ["name"]=>  string(13) "example.txt"  ["type"]=>  string(10) "text/plain"  ["url"]=>  string(131) "http://www.example.com/helpdesk/integrationapi/index.php?getattachment=VGhlIGNvbnRlbnQgb2YgdGhpcyBwYXJhbWV0ZXIgaXMgaXJyZWxldmFudA=="}

  Example Attachment (Using Native PHP Class):

  array(4) {  ["size"]=>  int(1346)  ["name"]=>  string(13) "example.txt"  ["type"]=>  string(10) "text/plain"  ["file"]=>  string(52) "/home/example/public_html/helpdesk/files/example.txt"}

  Miscellaneous

  boolean updateEmailAddress ( string $user , string $password , string $oldEmail , string $newEmail )

  This function allows you to update the email address of a customer so that their ticket history is preserved. For example, you could use this function on a modify profile page so it automatically changes their email address inside Kayako when they update it in the connecting system.

  Parameters

  • string oldEmail The current email address of the customer whose email you want to change
  • string newEmail The email address that you want to change the customer's email address to

  Returns

  Returns true on success

  Possible Errors

  • -1
  • -2
  • -3
  • -15

  Example Return Value

  Successful update:

  bool(true)

  Notes

  We recommend that you call this function prior to changing the address in your connecting software, so that if the Kayako address change fails your customer's email address isn't left being different in Kayako to your software, which would prevent them being able to access their tickets.

  Error Codes

  • -1: The API username and password that you used are not valid
  • -2: An invalid email address was supplied
  • -3: A non-existent user was specified
  • -4: The number per page is not numeric
  • -5: The page number is not numeric
  • -6: An invalid 'sort-by' field was specified (must be one of: lastactivity, lastreplier, ticketstatusid, priorityid, departmentid)
  • -7: An incorrect password type was specified (must be 1 or 0)
  • -8: An invalid department ID was specified
  • -9: An invalid priority ID was specified
  • -10: Required ticket information was missing
  • -11: Required comment information was missing
  • -12: The reply specified was empty
  • -13: The specified ticket could not be found
  • -14: The requested ticket is not owned by the specified user
  • -15: The new email address specified is already in the database
  • -16: Both status and priority were empty
  • -17: A non-existent status was specified
  • -18: A non-existent priority was specified
  • -19: The specified attachment could not be found
  • -20: The specified category could not be found
  • -21: The specified article could not be found
  • -22: The API was unable to fetch the submitted attachment
  • -23: A non-existent custom field group was specified
  • -24: A non-existent custom field was specified
  • -25: An empty value was specified for a custom field marked as "required"
  • -26: An incorrect typeid (ticket ID) value was specified
  
  

  This post has been edited by Andrew Gillard: 06 July 2009 - 12:08 PM

  Craig Brass
  Managing Director and Chief Software Architect - Craig Brass Systems
  0
  • Back to top

  ---

  Forum Home Corporate   |-- Company News   |-- Feedback Viper Cart   |-- Pre-Sales Questions   |-- General Discussion   |-- Features Explained   |-- Tutorials   |-- Customer to Customer Assistance   |-- Feature Requests   |---- Pending Implementation   |---- Implementation Attempted   |---- Implemented   |---- Already a Feature   |---- Duplicate   |---- Currently Unviable   |-- Bug Reports   |---- Pending Being Fixed   |---- Fix Attempted   |---- Fixed   |---- Duplicate   |---- Not a Bug   |-- Payment Gateway / Alternative Checkout Updates   |-- Skin Design   |-- Modifications   |-- Language Packs   |-- Store Showcase Icon Headquarters   |-- Download Packs Cool App Lab   |-- Hold Window on Top for Windows   |---- More Information + Download   |-- Quick Tray Minimize for Windows   |---- More Information + Download   |-- Copy Plain Text for Mozilla Firefox / Thunderbird   |---- More Information + Download   |-- BlackBerry Ticket Client for Kayako SupportSuite / eSupport   |---- More Information + Download   |-- Windows Phone Live Support Client for Kayako SupportSuite / eSupport   |---- More Information + Download   |-- Integration API for Kayako SupportSuite / eSupport   |---- More Information + Download   |-- Attachments Migration Tool for Kayako SupportSuite / eSupport   |---- More Information + Download   |-- Database Importer / Exporter   |---- More Information + Download   |-- FireFox Client for Kayako   |-- OpenFire Ticket Alert Tool   |-- Ultimate Computer DAB / FM Radio   |---- More Information + Purchase Community Boards   |-- General Chat

• ← Previous Topic
• Integration API for Kayako SupportSuite / eSupport
• Next Topic →

Share this topic:

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

Page 1 of 1

• You cannot start a new topic
• This topic is locked

---

1 User(s) are reading this topic
0 members, 1 guests, 0 anonymous users

Delete Post

Remove From View

The post may still be visible to moderators in this topic

Reason:

Delete From Topic

The post will be removed from this topic completely

Skin and Language

Theme: IP.Board Mobile Craig Brass Systems

Language: English

Execution Stats

• Time Now: May 23 2012 04:50 AM

• Back To Top
• Forum Home
• Delete My Cookies
• Mark Board As Read

Community Forum Software by IP.Board
Licensed to: Craig Brass Systems