HomeAPI ManualWeb Service APIPrivate Methods

4.5. Private Methods

Be sure you've read the API Basics before working with the private API.

You can find what each field/parameter is on the API Field Definitions page.

Methods:

private.customer.setPasswordByEmail

Set the portal password for an email account.
URL: /api/index.php?method=private.customer.setPasswordByEmail
HTTP Action: GET
Parameters:  
  • sEmail - Required
  • sPassword - Required
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.customer.setPasswordByEmail&sEmail=tsmith@companyco.com&sPassword=8!TrucK"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<results>
    <sPassword>8!TrucK</sPassword>
</results>

private.request.create

Create a new request.
URL: /api/index.php?method=private.request.create
HTTP Action: POST
Parameters:  
  • tNote - Required
  • xCategory - Required
  • xPersonAssignedTo
  • fNoteType (0 private (default), 1 public, 2 external)
  • fNoteIsHTML (1 HTML, 0 Text - defaults to Admin->Settings->HTML Emails on/off value)
  • xPersonOpenedBy (0 is the customer, defaults to user connecting to the API)
  • sTitle (Used as email subject)
  • reportingTags (Comma separated list of each xReportingTag ID)
  • fOpen
  • xStatus
  • sUserId
  • sFirstName
  • sLastName
  • sEmail
  • sPhone
  • fUrgent
  • fOpenedVia
  • xPortal
  • dtGMTOpened (defaults to current time in Unix timestamp format)
  • email_from (ID(xMailbox) of the mailbox to send the email from, use 0 to not send an email)
  • email_cc (Comma separated list of emails)
  • email_bcc (Comma separated list of emails)
  • email_to (Comma separated list of emails - external notes only)
  • email_staff (Comma separated list of staff ID's(xPerson))
  • File#_sFilename (# is the file number starting at 1)
  • File#_sFileMimeType
  • File#_bFileBody (Base64 Encoded File Body)
  • Custom# (# is the custom field ID)
  • skipCustomChecks (set to 1 to allow custom field checks to be skipped)
Other notes: In addition to tNote and xCategory you must also have at least one of the following set: sFirstName,sLastName,sUserId,sEmail,sPhone
Other notes: You can use this method to import requests from other systems by making sure you set email_from to 0 (so emails are not sent to customers) and setting dtGMTOpened to the time of the original request.
Simple Example:
curl -F"tNote=This is the request." -F"sUserId=12345" -F"xCategory=1" -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.create
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<request>
        <xRequest>12746</xRequest>
</request>

private.request.update

Update an existing request.
URL: /api/index.php?method=private.request.update
HTTP Action: POST
Parameters:  
  • xRequest - Required
  • tNote
  • xCategory
  • xPersonAssignedTo
  • xPerson (set to 0 to update as the customer)
  • fNoteType (0 private (default), 1 public, 2 external)
  • sTitle (Used as email subject)
  • reportingTags (Comma separated list of each xReportingTag ID)
  • fOpen
  • xStatus
  • sUserId
  • sFirstName
  • sLastName
  • sEmail
  • sPhone
  • fUrgent
  • dtGMTChange (defaults to current time in Unix timestamp format)
  • email_from (ID(xMailbox) of the mailbox to send the email from, use 0 to not send an email)
  • email_cc (Comma separated list of emails)
  • email_bcc (Comma separated list of emails)
  • email_to (Comma separated list of emails - external notes only)
  • email_staff (Comma separated list of staff ID's(xPerson))
  • File#_sFilename (# is the file number starting at 1)
  • File#_sFileMimeType
  • File#_bFileBody (Base64 Encoded File Body)
  • Custom# (# is the custom field ID)
  • skipCustomChecks (set to 1 to allow custom field checks to be skipped)
Simple Example:
curl -F"xRequest=12746" -F"tNote=Update the request." -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.update
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<request>
        <xRequest>12746</xRequest>
</request>

private.request.get

Return all information on a request.
URL: /api/index.php?method=private.request.get
HTTP Action: GET
Parameters:  
  • xRequest - Required
  • fRawValues (defaults to 0)
Other notes: As a convenience fRawValues is set to 0 (false) by default so that numeric values you would normally have to transform (staff ID's, dates, categories) are shown by their text representation. If you need the actual numeric values for these items set fRawValues to 1.
Merge notes If requesting a request which has been merged, the merged request will be returned. The new request ID is returned and will be different from the one you called for which you can use to check if knowing that the request was merged is important in your usage.
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.get&xRequest=12745"
Sample Response:
<request>
        <xRequest>12745</xRequest>
        <fOpenedVia>Web Service</fOpenedVia>
        <xOpenedViaId>0</xOpenedViaId>
        <xPersonOpenedBy />
        <xPersonAssignedTo>Ian Landsman</xPersonAssignedTo>
        <fOpen>1</fOpen>
        <xStatus>Active</xStatus>
        <fUrgent>0</fUrgent>
        <xCategory>Bugs</xCategory>
        <dtGMTOpened>September 24, 2007</dtGMTOpened>
        <dtGMTClosed />
        <sRequestPassword>itetxb</sRequestPassword>
        <sTitle />
        <sUserId>12345</sUserId>
        <sFirstName />
        <sLastName />
        <sEmail />
        <sPhone />
        <iLastReplyBy>Ian Landsman</iLastReplyBy>
        <fTrash>0</fTrash>
        <dtGMTTrashed />
        <fullname> </fullname>
        <reportingTags>
                <tag>
                        <xReportingTag>29</xReportingTag>
                        <sReportingTag>Payment Inquires</sReportingTag>
                </tag>
        </reportingTags>
        <request_history>
                <item>
                        <xRequestHistory>1378</xRequestHistory>
                        <xRequest>12745</xRequest>
                        <xPerson>Ian Landsman</xPerson>
                        <dtGMTChange>Tue, September 25, 2007, 11:00 AM</dtGMTChange>
                        <fPublic>1</fPublic>
                        <fInitial>0</fInitial>
                        <tLog />
                        <tNote><p>An HTML note example</p></tNote>
                        <tEmailHeaders />
                        <fNoteIsHTML>1</fNoteIsHTML>
                        <fMergedFromRequest>0</fMergedFromRequest>
                        <files>
                                <file>
                                        <sFileMimeType>application/pdf</sFileMimeType>
                                        <sFilename>Invoice.pdf</sFilename>
                                        <xDocumentId>60</xDocumentId>
                                        <public_url>http://www.domain.com/index.php?pg=file&from=3&id=60&reqid=12745&reqhisid=1378</public_url>
                                        <private_url>http://www.domain.com/admin.php?pg=file&from=0&id=60&showfullsize=1&download=1</private_url>
                                </file>
                        </files>
                </item>
                <item>
                        <xRequestHistory>1377</xRequestHistory>
                        <xRequest>12745</xRequest>
                        <xPerson>Ian Landsman</xPerson>
                        <dtGMTChange>Tue, September 25, 2007, 11:00 AM</dtGMTChange>
                        <fPublic>0</fPublic>
                        <fInitial>0</fInitial>
                        <tLog>Category changed from "" to "Bugs"</tLog>
                        <tNote />
                        <tEmailHeaders />
                        <fNoteIsHTML>0</fNoteIsHTML>
                        <fMergedFromRequest>0</fMergedFromRequest>
                </item>
                <item>
                        <xRequestHistory>1376</xRequestHistory>
                        <xRequest>12745</xRequest>
                        <xPerson> </xPerson>
                        <dtGMTChange>Mon, September 24, 2007, 08:03 PM</dtGMTChange>
                        <fPublic>1</fPublic>
                        <fInitial>0</fInitial>
                        <tLog />
                        <tNote>Plain text update to the request.</tNote>
                        <tEmailHeaders />
                        <fNoteIsHTML>0</fNoteIsHTML>
                        <fMergedFromRequest>0</fMergedFromRequest>
                        <files />
                </item>
                <item>
                        <xRequestHistory>1375</xRequestHistory>
                        <xRequest>12745</xRequest>
                        <xPerson> </xPerson>
                        <dtGMTChange>Mon, September 24, 2007, 07:44 PM</dtGMTChange>
                        <fPublic>1</fPublic>
                        <fInitial>1</fInitial>
                        <tLog />
                        <tNote>This is the request.</tNote>
                        <tEmailHeaders />
                        <fNoteIsHTML>0</fNoteIsHTML>
                        <fMergedFromRequest>0</fMergedFromRequest>
                        <files />
                </item>
        </request_history>
</request>

private.request.multiGet

Return request information for more than one request at a time.
URL: /api/index.php?method=private.request.multiGet
HTTP Action: GET
Parameters:  
  • xRequest - Required - an array of request ID's.
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.multiGet&xRequest[]=12745&xRequest[]=847373&xRequest[]=56733"
Response:

Returns an array of response details the same as private.request.get.

private.request.search

Search for requests.
URL: /api/index.php?method=private.request.search
HTTP Action: GET
Parameters:  
  • anyall (Should any or all(the default) search parameters be required to match)
  • xRequest
  • sUserId
  • sFirstName
  • sLastName
  • sEmail
  • sPhone
  • sSearch (full text search string)
  • xStatus
  • xCategory
  • fOpen
  • Custom#
  • fRawValues (defaults to 0)
  • beforeDate (Unix timestamp format)
  • afterDate (Unix timestamp format)
  • closedBeforeDate (Unix timestamp format)
  • closedAfterDate (Unix timestamp format)
  • relativedate (See API Definition page for details)
  • start
  • length
  • orderBy (accepts any of these parameters such as xRequest, sLastName)
  • orderByDir (desc or asc)
  • xPersonAssignedTo
Other notes: As a convenience fRawValues is set to 0 (false) by default so that numeric values you would normally have to transform (staff ID's, dates, categories) are shown by their text representation. If you need the actual numeric values for these items set fRawValues to 1.
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.search&sSearch=printer"
Sample Response:
<requests>
        <request>
                <xRequest>12650</xRequest>
                <fOpenedVia>Phone</fOpenedVia>
                <xOpenedViaId>0</xOpenedViaId>
                <xPersonOpenedBy>Ian Landsman</xPersonOpenedBy>
                <xPersonAssignedTo>Ian Landsman</xPersonAssignedTo>
                <fOpen>1</fOpen>
                <xStatus>Active</xStatus>
                <fUrgent>1</fUrgent>
                <xCategory>Bugs</xCategory>
                <dtGMTOpened>January 16, 2006</dtGMTOpened>
                <dtGMTClosed />
                <sRequestPassword>oxvgys</sRequestPassword>
                <sTitle>RE: Update on Your Request</sTitle>
                <sUserId />
                <sFirstName />
                <sLastName>landsman</sLastName>
                <sEmail />
                <sPhone />
                <iLastReplyBy>0</iLastReplyBy>
                <fTrash>0</fTrash>
                <dtGMTTrashed />
                <fullname> landsman</fullname>
                <tNote><span class="initsubject">Some text here</span> - Help with printer issue please.</tNote>
        </request>
        <request>
                <xRequest>12733</xRequest>
                <fOpenedVia>Web Service</fOpenedVia>
                <xOpenedViaId>0</xOpenedViaId>
                <xPersonOpenedBy />
                <xPersonAssignedTo>Ian Landsman</xPersonAssignedTo>
                <fOpen>1</fOpen>
                <xStatus>Active</xStatus>
                <fUrgent>0</fUrgent>
                <xCategory>Bugs</xCategory>
                <dtGMTOpened>September 13, 2007</dtGMTOpened>
                <dtGMTClosed />
                <sRequestPassword>bwpkqv</sRequestPassword>
                <sTitle />
                <sUserId>567</sUserId>
                <sFirstName />
                <sLastName />
                <sEmail />
                <sPhone />
                <iLastReplyBy>0</iLastReplyBy>
                <fTrash>0</fTrash>
                <dtGMTTrashed />
                <fullname> </fullname>
                <tNote><span class="initsubject">Text Here</span> - Need printer assistance.</tNote>
        </request>
</requests>

private.request.addTimeEvent

Add a time tracker time event to a request.
URL: /api/index.php?method=private.request.addTimeEvent
HTTP Action: POST
Parameters:  
  • xRequest - Required
  • xPerson - Required
  • iMonth - Required
  • iDay - Required
  • iYear - Required
  • tDescription - Required
  • tTime (time formatted in hh:mm or decimal hours, ex: 2.5) - Required
  • dtGMTDateAdded (set the exact unix timestamp of when the event was added)
  • fBillable
Simple Example:
curl -F"xRequest=12650" -F"xPerson=2" -F"iMonth=10" -F"iDay=21" -F"iYear=2007" -F"tDescription=fixed printer" -F"tTime=2:30" -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.addTimeEvent
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<results>
        <xTimeId>26</xTimeId>
</results>

private.request.deleteTimeEvent

Delete a time tracker time event.
URL: /api/index.php?method=private.request.deleteTimeEvent
HTTP Action: POST
Parameters:  
  • xTimeId - Required
Simple Example:
curl -F"xTimeId=754" -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.deleteTimeEvent
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<results>
        <deleted>1</deleted>
</results>

private.request.getTimeEvents

Return all time tracker time events from a request.
URL: /api/index.php?method=private.request.getTimeEvents
HTTP Action: GET
Parameters:  
  • xRequest - Required
  • fRawValues (defaults to 0)
Other notes: As a convenience fRawValues is set to 0 (false) by default so that numeric values you would normally have to transform (staff ID's, dates, categories) are shown by their text representation. If you need the actual numeric values for these items set fRawValues to 1.
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.getTimeEvents&xRequest=12650"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<time_events>
        <event>
                <xTimeId>27</xTimeId>
                <xRequest>12650</xRequest>
                <xPerson>Tina Andrews</xPerson>
                <iSeconds>9000</iSeconds>
                <dtGMTDate>September 25, 2007</dtGMTDate>
                <dtGMTDateAdded>Wed, September 26, 2007, 01:18 PM</dtGMTDateAdded>
                <tDescription>Delivered printer</tDescription>
        </event>
        <event>
                <xTimeId>28</xTimeId>
                <xRequest>12650</xRequest>
                <xPerson>Tina Andrews</xPerson>
                <iSeconds>9000</iSeconds>
                <dtGMTDate>September 26, 2007</dtGMTDate>
                <dtGMTDateAdded>Wed, September 26, 2007, 03:18 PM</dtGMTDateAdded>
                <tDescription>Installed printer</tDescription>
        </event>
</time_events>

private.request.getCategories

Returns a list of all categories along with each categories related information such as reporting tags.
URL: /api/index.php?method=private.request.getCategories
HTTP Action: GET
Parameters: none
Other notes: If using this information for a user interface, it's recommended you only show categories which are active (where fDeleted = 0).
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.getCategories
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<categories>
        <category>
                <xCategory>1</xCategory>
                <sCategory>Pre Sales Question</sCategory>
                <sCategoryGroup></sCategoryGroup>
                <fDeleted>0</fDeleted>
                <fAllowPublicSubmit>1</fAllowPublicSubmit>
                <xPersonDefault>1</xPersonDefault>
                <fAutoAssignTo>0</fAutoAssignTo>
                <sPersonList>
                        <person>
                                <xPerson>3</xPerson>
                                <fullname>Steve Benson</fullname>
                                <assigned_requests>6</assigned_requests>
                        </person>
                        <person>
                                <xPerson>4</xPerson>
                                <fullname>Tiffany Prince</fullname>
                                <assigned_requests>7</assigned_requests>
                        </person>
                        <person>
                                <xPerson>5</xPerson>
                                <fullname>Henry Yount</fullname>
                                <assigned_requests>8</assigned_requests>
                        </person>
                </sPersonList>
                <sCustomFieldList>
                        <xCustomField>2</xCustomField>
                        <xCustomField>13</xCustomField>
                </sCustomFieldList>
                <reportingTags>
                        <tag>
                                <xReportingTag>5</xReportingTag>
                                <sReportingTag>Pricing</sReportingTag>
                        </tag>
                        <tag>
                                <xReportingTag>9</xReportingTag>
                                <sReportingTag>Support Options</sReportingTag>
                        </tag>
                        <tag>
                                <xReportingTag>7</xReportingTag>
                                <sReportingTag>System Requirements</sReportingTag>
                        </tag>
                </reportingTags>
        </category>
</categories>

private.request.getMailboxes

Returns a list of mailboxes.
URL: /api/index.php?method=private.request.getMailboxes
HTTP Action: GET
Parameters:
  • fActiveOnly (defaults to 1, use 0 to find inactive mailboxes.)
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.getMailboxes
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<results>
        <mailbox>
                <xMailbox>3</xMailbox>
                <sReplyName>Test Account</sReplyName>
                <sReplyEmail>systest@userscape.com</sReplyEmail>
        </mailbox>
</results>

private.request.getStatusTypes

Returns a list of status types.
URL: /api/index.php?method=private.request.getStatusTypes
HTTP Action: GET
Parameters:
  • fActiveOnly (defaults to 1, use 0 to find inactive status types.)
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.getStatusTypes
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<results>
    <status>
        <sStatus>Active</sStatus>
        <xStatus>1</xStatus>
    </status>
    <status>
        <sStatus>Problem Solved</sStatus>

        <xStatus>3</xStatus>
    </status>
    <status>
        <sStatus>Not Fixable</sStatus>
        <xStatus>4</xStatus>
    </status>
    <status>

        <sStatus>Customer Unreachable</sStatus>
        <xStatus>5</xStatus>
    </status>
    <status>
        <sStatus>Customer Found Solution</sStatus>
        <xStatus>6</xStatus>
    </status>

    <status>
        <sStatus>Software Bug</sStatus>
        <xStatus>7</xStatus>
    </status>
    <status>
        <sStatus>SPAM</sStatus>
        <xStatus>2</xStatus>

    </status>
</results>

private.request.getCustomFields

Returns a list of custom fields.
URL: /api/index.php?method=private.request.getCustomFields
HTTP Action: GET
Parameters:
  • xCategory (Optionally limit the results to one categories custom fields)
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.getCustomFields
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<customfields>
        <field>
                <xCustomField>10</xCustomField>
                <fieldName>Ajax Lookup</fieldName>
                <isRequired>1</isRequired>
                <isPublic>0</isPublic>
                <fieldType>ajax</fieldType>
                <iOrder>0</iOrder>
                <sTxtSize />
                <lrgTextRows />
                <listItems />
                <iDecimalPlaces>0</iDecimalPlaces>
                <sRegex />
                <sAjaxUrl>http://www.domain.com/ajax_field_lookup.php</sAjaxUrl>
                <isAlwaysVisible>0</isAlwaysVisible>
        </field>
        <field>
                <xCustomField>7</xCustomField>
                <fieldName>VIP Customer</fieldName>
                <isRequired>0</isRequired>
                <isPublic>1</isPublic>
                <fieldType>checkbox</fieldType>
                <iOrder>0</iOrder>
                <sTxtSize />
                <lrgTextRows />
                <listItems />
                <iDecimalPlaces>0</iDecimalPlaces>
                <sRegex />
                <sAjaxUrl />
                <isAlwaysVisible>0</isAlwaysVisible>
        </field>
        <field>
                <xCustomField>2</xCustomField>
                <fieldName>Database Type</fieldName>
                <isRequired>0</isRequired>
                <isPublic>1</isPublic>
                <fieldType>select</fieldType>
                <iOrder>0</iOrder>
                <sTxtSize />
                <lrgTextRows />
                <listItems>
                        <item>MySQL</item>
                        <item>MS SQL Server</item>
                        <item>PostgreSQL</item>
                </listItems>
                <iDecimalPlaces>0</iDecimalPlaces>
                <sRegex />
                <sAjaxUrl />
                <isAlwaysVisible>0</isAlwaysVisible>
        </field>
</customfields>

private.request.merge

Merge two requests.
URL: /api/index.php?method=private.request.merge
HTTP Action: POST
Parameters:
  • xRequestFrom - Required (The ID of the request to merge)
  • xRequestTo - Required (The ID of the request to merge xRequestFrom into)
Simple Example:
curl -F"xRequestFrom=12678" -F"xRequestTo=12690" -u tim@ex.com:mypassword http://.../api/index.php?method=private.request.merge
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<results>
    <xRequest>12426</xRequest>
</results>

private.request.getChanged

Return all requests which have changed since the date given.
URL: /api/index.php?method=private.request.getChanged
HTTP Action: GET
Parameters:  
  • dtGMTChange - Required
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.getChanged&dtGMTChange=1309444160"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<requests>
    <xRequest>46550</xRequest>
    <xRequest>46550</xRequest>
    <xRequest>46554</xRequest>
    <xRequest>46554</xRequest>
    <xRequest>46554</xRequest>
    <xRequest>46554</xRequest>
</requests>

private.request.subscriptions

Find a users subscriptions.
URL: /api/index.php?method=private.request.subscriptions
HTTP Action: GET
Parameters:  
  • xPerson - Required
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.subscriptions&xPerson=1"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<subscriptions>
    <request>
        <xRequest>46632</xRequest>
        <xSubscriptions>30</xSubscriptions>
    </request>
    <request>
        <xRequest>46633</xRequest>
        <xSubscriptions>29</xSubscriptions>
    </request>
</subscriptions>

private.request.subscribe

Subscribe a user to a request.
URL: /api/index.php?method=private.request.subscribe
HTTP Action: POST
Parameters:  
  • xRequest - Required
  • xPerson - Required
Simple Example:
curl -F"xRequest=12345" -F"xPerson=4" -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.subscribe"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<results>
    <subscribed>4</subscribed>
</results>

private.request.unsubscribe

Unsubscribe a user from a request.
URL: /api/index.php?method=private.request.unsubscribe
HTTP Action: POST
Parameters:  
  • xRequest - Required
  • xPerson - Required
Simple Example:
curl -F"xRequest=12345" -F"xPerson=4" -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.unsubscribe"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<results>
    <unsubscribed>4</unsubscribed>
</results>

private.request.markTrash

Mark a request as trash.
URL: /api/index.php?method=private.request.markTrash
HTTP Action: POST
Parameters:  
  • xRequest - Required
Simple Example:
curl -F"xRequest=12345" -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.markTrash"
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<trashed>12400</trashed>
</result>

private.request.markSpam

Mark a request as spam.
URL: /api/index.php?method=private.request.markSpam
HTTP Action: POST
Parameters:  
  • xRequest - Required
Simple Example:
curl -F"xRequest=12345" -u tim@ex.com:mypassword "http://.../api/index.php?method=private.request.markSpam"
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<result>
	<spammed>12410</spammed>
</result>

private.document.get

Get a document based on its id.
URL: /api/index.php?method=private.document.get
HTTP Action: GET
Parameters:  
  • xDocumentId - Required
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.document.get&xDocumentId=1"
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
            <document>
                <xDocumentId>1</xDocumentId>
                <sFilename>unknown_filename.eml</sFilename>
                <sFileMimeType>message/rfc822</sFileMimeType>
                <sCID />
                <sBody>UmV0dXJuLVBhdGg6IDx0cmFp==</sBody>
            </document>;

private.response.listAll

Return all your responses.
URL: /api/index.php?method=private.response.listAll
HTTP Action: GET
Parameters:  
  • None
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.response.listAll"
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<responses>
	<response>
		<xResponse>1</xResponse>
		<sResponseTitle>Password Reset</sResponseTitle>
		<sFolder>My Responses</sFolder>
		<tResponse>Hello,

Please go to the website to reset your password.

Support Team</tResponse>
		<xPerson>1</xPerson>
		<fType>2</fType>
		<fDeleted>0</fDeleted>
		<fullname>Ian Landsman</fullname>
		<pathname>My Responses / Password Reset</pathname>
	</response>
</responses>

private.response.usersMostCommon

Return the 10 most common responeses for the authenticated user.
URL: /api/index.php?method=private.request.usersMostCommon
HTTP Action: GET
Parameters:  
  • None
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.response.usersMostCommon"
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<responses>
	<response>
		<xResponse>1</xResponse>
		<sResponseTitle>Password Reset</sResponseTitle>
		<stat_count>420</stat_count>
	</response>
</responses>

private.response.get

Get details on a response by ID.
URL: /api/index.php?method=private.response.get
HTTP Action: GET
Parameters:  
  • xResponse - Required
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.response.get&xResponse=1"
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
	<xResponse>1</xResponse>
	<sResponseTitle>Password Reset</sResponseTitle>
	<sFolder>My Responses</sFolder>
	<tResponse>Hello,

Please go to the website to reset your password.

Support Team</tResponse>
	<xPerson>1</xPerson>
	<fType>2</fType>
	<fDeleted>0</fDeleted>
</response>

private.filter.get

Return the results of a users filter.
URL: /api/index.php?method=private.filter.get
HTTP Action: GET
Parameters:  
  • xFilter - Required (a filter ID or 'inbox' or 'myq')
  • fRawValues (defaults to 0)
  • start
  • length
Other notes:

As a convenience fRawValues is set to 0 (false) by default so that numeric values you would normally have to transform (staff ID's, dates, categories) are shown by their text representation. If you need the actual numeric values for these items set fRawValues to 1.

tNote is not the full initial request, just the first few sentances.

Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.filter.get&xFilter=12"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<filter>
        <request>
                <xRequest>12624</xRequest>
                <fOpenedVia>Email</fOpenedVia>
                <xOpenedViaId>Customer.Service</xOpenedViaId>
                <xPersonOpenedBy />
                <xPersonAssignedTo>Henry Yount</xPersonAssignedTo>
                <fOpen>1</fOpen>
                <xStatus>Active</xStatus>
                <fUrgent>0</fUrgent>
                <xCategory>Feature Request</xCategory>
                <dtGMTOpened>July 12, 2007</dtGMTOpened>
                <dtGMTClosed />
                <sRequestPassword>pgupzu</sRequestPassword>
                <sTitle>Upload documents over 1gig</sTitle>
                <sUserId>8389332</sUserId>
                <sFirstName>Harry</sFirstName>
                <sLastName>Waterman</sLastName>
                <sEmail>hw@example.com</sEmail>
                <sPhone>845.555.1234</sPhone>
                <iLastReplyBy>0</iLastReplyBy>
                <fTrash>0</fTrash>
                <dtGMTTrashed />
                <fullname>Harry Waterman</fullname>
                <tNote>I would like to be able to upload documents over 1 gigabyte.</tNote>
        </request>
        <request>
                <xRequest>12451</xRequest>
                <fOpenedVia>Phone</fOpenedVia>
                <xOpenedViaId />
                <xPersonOpenedBy>Tiffany Prince</xPersonOpenedBy>
                <xPersonAssignedTo>Henry Yount</xPersonAssignedTo>
                <fOpen>0</fOpen>
                <xStatus>Problem Solved</xStatus>
                <fUrgent>0</fUrgent>
                <xCategory>Feature Request</xCategory>
                <dtGMTOpened>September 19, 2007</dtGMTOpened>
                <dtGMTClosed>September 30, 2007</dtGMTClosed>
                <sRequestPassword>vyzfua</sRequestPassword>
                <sTitle>Improved searching</sTitle>
                <sUserId />
                <sFirstName>Sarah</sFirstName>
                <sLastName>Ryan</sLastName>
                <sEmail />
                <sPhone />
                <iLastReplyBy>0</iLastReplyBy>
                <fTrash>0</fTrash>
                <dtGMTTrashed />
                <fullname>Sarah Ryan</fullname>
                <tNote>I would like to see the searching imrpoved in the upcoming release.</tNote>
        </request>
</filter>

private.filter.getColumnNames

Return column names for the fields returned in filters.
URL: /api/index.php?method=private.filter.getColumnNames
HTTP Action: GET
Parameters: none
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.filter.getColumnNames
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<labels>
        <iLastReplyBy>Replied To</iLastReplyBy>
        <fOpenedVia>Contacted Via</fOpenedVia>
        <mailbox>Mailbox</mailbox>
        <fOpen>Open</fOpen>
        <xRequest>ID</xRequest>
        <sUserId>Customer ID</sUserId>
        <fullname>Customer</fullname>
        <sLastName>Last Name</sLastName>
        <sEmail>Email</sEmail>
        <sPhone>Phone</sPhone>
        <xPersonOpenedBy>Opened By</xPersonOpenedBy>
        <xPersonAssignedTo>Assigned To</xPersonAssignedTo>
        <xStatus>Status</xStatus>
        <sCategory>Category</sCategory>
        <sTitle>Email Subject</sTitle>
        <reqsummary>Initial Request</reqsummary>
        <lastpublicnote>Latest Public Note</lastpublicnote>
        <lastpublicnoteby>Latest Public Note By</lastpublicnoteby>
        <dtGMTOpened>Opened</dtGMTOpened>
        <dtGMTClosed>Closed</dtGMTClosed>
        <dtGMTTrashed>Trashed On</dtGMTTrashed>
        <lastupdate>Last Update</lastupdate>
        <lastpubupdate>Last Public Update</lastpubupdate>
        <lastcustupdate>Last Customer Update</lastcustupdate>
        <ctPublicUpdates>#</ctPublicUpdates>
        <age>Age</age>
        <timetrack>Time</timetrack>
</labels>

private.filter.getStream

Return the note stream for a filter
URL: /api/index.php?method=private.filter.getStream
HTTP Action: GET
Parameters:  
  • xFilter - Required
  • sFilterView (stream, stream-priv, stream-cust, stream-cust-staff)
  • fromRequestHistory (Only return notes occuring after this xRequestHistory ID)
  • limit
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.filter.getStream&xFilter=1"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<stream>
    <history_note>
        <xRequestHistory>184347</xRequestHistory>
        <xRequest>46279</xRequest>
        <xPerson>2</xPerson>
        <dtGMTChange>1302652677</dtGMTChange>
        <fPublic>1</fPublic>
        <fInitial>0</fInitial>
        <tNote>A note body....</tNote>
        <fNoteIsHTML>1</fNoteIsHTML>
        <fMergedFromRequest>0</fMergedFromRequest>
    </history_note>
</stream>

private.timetracker.search

Return time events based on search criteria.
URL: /api/index.php?method=private.timetracker.search
HTTP Action: GET
Parameters:  
  • sUserId
  • sEmail
  • sFirstName
  • sLastName
  • fOpen
  • xStatus
  • xMailbox
  • fOpenedVia
  • xCategory
  • fUrgent
  • xPersonAssignedTo
  • xPersonOpenedBy
  • Custom#
  • start_time (30 days back by default, set to 0 for all time)
  • end_time (right now by default)
  • fRawValues
  • orderBy (defaults to dtGMTDate)
  • orderByDir (desc or asc)
Simple Example:
curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.timetracker.search&sUserId=76548"
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<time_events>
    <event>
        <xTimeId>4502</xTimeId>
        <xRequest>12481</xRequest>
        <xPerson>Ian Landsman</xPerson>
        <iSeconds>5400</iSeconds>
        <dtGMTDate>June  9, 2008</dtGMTDate>
        <dtGMTDateAdded>June  9 2008, 11:48 AM</dtGMTDateAdded>
        <tDescription>Fixed 3rd floor network printer</tDescription>
        <sUserId>76548</sUserId>
        <sFirstName>Ian</sFirstName>
        <sLastName>Landsman</sLastName>
        <sEmail>ian@userscape.com</sEmail>
    </event>
</time_events>

private.user.getFilters

Return the authenticated users filters.
URL: /api/index.php?method=private.user.getFilters
HTTP Action: GET
Parameters: none
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.user.getFilters
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<filters>
        <filter>
                <xFilter>inbox</xFilter>
                <sFilterName>Inbox</sFilterName>
                <displayColumns>
                        <takeit />
                        <fOpenedVia>Contacted Via</fOpenedVia>
                        <fullname>Customer</fullname>
                        <reqsummary>Initial Request</reqsummary>
                        <age>Age</age>
                </displayColumns>
                <fGlobal>0</fGlobal>
                <sFilterFolder />
                <count>22</count>
                <unread />
        </filter>
        <filter>
                <xFilter>myq</xFilter>
                <sFilterName>My Queue</sFilterName>
                <displayColumns>
                        <isunread />
                        <view />
                        <fOpenedVia>Contacted Via</fOpenedVia>
                        <fullname>Customer</fullname>
                        <reqsummary>Initial Request</reqsummary>
                        <age>Age</age>
                </displayColumns>
                <fGlobal>0</fGlobal>
                <sFilterFolder />
                <count>139</count>
                <unread>18</unread>
        </filter>
        <filter>
                <xFilter>9</xFilter>
                <sFilterName>Open over 24hr</sFilterName>
                <displayColumns>
                        <fOpenedVia>Contacted Via</fOpenedVia>
                        <fOpen>Open</fOpen>
                        <fullname>Customer</fullname>
                        <reqsummary>Initial Request</reqsummary>
                        <dtGMTOpened>Opened</dtGMTOpened>
                </displayColumns>
                <fGlobal>0</fGlobal>
                <sFilterFolder>My Filters</sFilterFolder>
                <count>14</count>
                <unread />
        </filter>        
</filters>

private.user.preferences

Return the authenticated users preferences.
URL: /api/index.php?method=private.user.preferences
HTTP Action: GET
Parameters: none
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.user.preferences
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<preferences>
        <xPerson>7</xPerson>
        <sFname>Henry</sFname>
        <sLname>Yount</sLname>
        <sUsername />
        <sEmail>ian@userscape.com</sEmail>
        <sEmail2 />
        <sSMS />
        <xSMSService>1</xSMSService>
        <sPhone>x345</sPhone>
        <tSignature>
        Henry Yount
        Help Desk Lead        
        </tSignature>
        <tMobileSignature>
        -- MOBILE --
        Henry Yount
        Help Desk Lead        
        </tMobileSignature>
        <fNotifyEmail>1</fNotifyEmail>
        <fNotifyEmail2>0</fNotifyEmail2>
        <fNotifySMS>0</fNotifySMS>
        <fNotifySMSUrgent>0</fNotifySMSUrgent>
        <xPersonPhotoId>39</xPersonPhotoId>
        <fUserType>1</fUserType>
        <xPersonOutOfOffice>0</xPersonOutOfOffice>
        <fNotifyNewRequest>1</fNotifyNewRequest>
        <fDeleted>0</fDeleted>
        <sWorkspaceDefault>myq</sWorkspaceDefault>
        <fDefaultToPublic>0</fDefaultToPublic>
        <fDefaultTTOpen>0</fDefaultTTOpen>
        <fHideWysiwyg>0</fHideWysiwyg>
        <fHideImages>0</fHideImages>
        <iRequestHistoryLimit>10</iRequestHistoryLimit>
        <fReturnToReq>0</fReturnToReq>
        <sHTMLEditor>wysiwyg</sHTMLEditor>
        <tSignature_HTML>
        &lt;b&gt;Henry Yount&lt;/b&gt;&lt;br /&gt;
        Help Desk Lead
        </tSignature_HTML>
</preferences>

private.util.getActiveStaff

Return all currently active staff in the system and their information.
URL: /api/index.php?method=private.util.getActiveStaff
HTTP Action: GET
Parameters: none
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.util.getActiveStaff
Sample Response:
<?xml version="1.0" encoding="iso-8859-1"?>
<staff>
        <person>
            <xPerson>7</xPerson>
            <sFname>Henry</sFname>
            <sLname>Yount</sLname>
            <sUsername />
            <sEmail>henry@domain.com</sEmail>
            <sEmail2 />
            <sSMS />
            <xSMSService>1</xSMSService>
            <sPhone>x345</sPhone>
            <tSignature>
            Henry Yount
            Help Desk Lead        
            </tSignature>
            <tMobileSignature>
            -- MOBILE --
            Henry Yount
            Help Desk Lead        
            </tMobileSignature>
            <fNotifyEmail>1</fNotifyEmail>
            <fNotifyEmail2>0</fNotifyEmail2>
            <fNotifySMS>0</fNotifySMS>
            <fNotifySMSUrgent>0</fNotifySMSUrgent>
            <xPersonPhotoId>39</xPersonPhotoId>
            <fUserType>1</fUserType>
            <xPersonOutOfOffice>0</xPersonOutOfOffice>
            <fNotifyNewRequest>1</fNotifyNewRequest>
            <fDeleted>0</fDeleted>
            <sWorkspaceDefault>myq</sWorkspaceDefault>
            <fDefaultToPublic>0</fDefaultToPublic>
            <fDefaultTTOpen>0</fDefaultTTOpen>
            <fHideWysiwyg>0</fHideWysiwyg>
            <fHideImages>0</fHideImages>
            <iRequestHistoryLimit>10</iRequestHistoryLimit>
            <fReturnToReq>0</fReturnToReq>
            <sHTMLEditor>wysiwyg</sHTMLEditor>
            <tSignature_HTML>
            &lt;b&gt;Henry Yount&lt;/b&gt;&lt;br /&gt;
            Help Desk Lead
            </tSignature_HTML>
            <fullname>Henry Yount</fullname>
        </person>
        <person>
                <xPerson>1</xPerson>
                <sFname>Tiffany</sFname>
                <sLname>Prince</sLname>
                <sUsername />
                <sEmail>tiffany@domain.com</sEmail>
                <sEmail2 />
                <sSMS />
                <xSMSService>1</xSMSService>
                <sPhone>x387</sPhone>
                <tSignature />
                <tMobileSignature />
                <fNotifyEmail>1</fNotifyEmail>
                <fNotifyEmail2>0</fNotifyEmail2>
                <fNotifySMS>0</fNotifySMS>
                <fNotifySMSUrgent>0</fNotifySMSUrgent>
                <xPersonPhotoId>39</xPersonPhotoId>
                <fUserType>1</fUserType>
                <xPersonOutOfOffice>0</xPersonOutOfOffice>
                <fNotifyNewRequest>1</fNotifyNewRequest>
                <fDeleted>0</fDeleted>
                <sWorkspaceDefault>myq</sWorkspaceDefault>
                <fDefaultToPublic>0</fDefaultToPublic>
                <fDefaultTTOpen>0</fDefaultTTOpen>
                <fHideWysiwyg>0</fHideWysiwyg>
                <fHideImages>0</fHideImages>
                <iRequestHistoryLimit>10</iRequestHistoryLimit>
                <fReturnToReq>0</fReturnToReq>
                <sHTMLEditor>wysiwyg</sHTMLEditor>
                <tSignature_HTML />
                <fullname>Tiffany Prince</fullname>
        </person>
</staff>

private.util.getAuditLog

Return admin audit logs
URL: /api/index.php?method=private.util.getAuditLog
HTTP Action: GET
Parameters:
  • start
  • length
Simple Example:
curl -u tim@ex.com:mypassword http://.../api/index.php?method=private.util.getAuditLog?start=0&length=10
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
        <results>
            <auditLog>
                <xAuditLog>130</xAuditLog>
                <sAction>edit</sAction>
                <sObject>HS_Settings</sObject>
                <xPerson>1</xPerson>
                <dtDateAdded>1715281119</dtDateAdded>
                <iValue/>
                <sValue>cHD_PORTAL_LOGIN_AUTHTYPE = ldap_ad</sValue>
                <dValue/>
                <sIPAddress>127.0.0.1</sIPAddress>
                <xRequest/>
                <sData>{&quot;cHD_DAYS_TO_LEAVE_TRASH&quot;:&quot;30&quot;,&quot;cHD_PORTAL_LOGIN_AUTHTYPE&quot;:&quot;ldap_ad&quot;}</sData>
            </auditLog>
            <auditLog>
                <xAuditLog>131</xAuditLog>
                <sAction>login</sAction>
                <sObject>HS_Person</sObject>
                <xPerson>1</xPerson>
                <dtDateAdded>1715284394</dtDateAdded>
                <iValue/>
                <sValue>someone@example.com</sValue>
                <dValue/>
                <sIPAddress>127.0.0.1</sIPAddress>
                <xRequest/>
                <sData/>
            </auditLog>
            <auditLog>
                <xAuditLog>132</xAuditLog>
                <sAction>export</sAction>
                <sObject>Customer</sObject>
                <xPerson>1</xPerson>
                <dtDateAdded>1715284440</dtDateAdded>
                <iValue>0</iValue>
                <sValue/>
                <dValue/>
                <sIPAddress>127.0.0.1</sIPAddress>
                <xRequest/>
                <sData>&quot;someone@example.com&quot;</sData>
            </auditLog>
        </results>

private.addressbook.createContact

Creates a contact in the internal addressbook.
URL: /api/index.php?method=private.addressbook.createContact
HTTP Action: POST
Parameters:
  • sFirstName - Required
  • sLastName - Required
  • sEmail - Required
  • sTitle
  • sDescription
  • fHighlight
Simple Example:
curl -X POST \
'http://.../api/index.php?method=private.addressbook.createContact' \
  --header 'Authorization: Bearer 3|QeJDIPybZSjykqjzuxVJ94WqlaoVruWWbEm4ffqc' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'sFirstName=John' \
  --data-urlencode 'sLastName=Doe' \
  --data-urlencode 'sEmail=John.Doe@example.com' \
  --data-urlencode 'sTitle=Director of HR' \
  --data-urlencode 'sDescription=Additional description values' \
  --data-urlencode 'fHighlight=0'
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<addressbook>
    <xContact>1</xContact>
</addressbook>

private.addressbook.deletedContact

Deletes a contact in the internal addressbook.
URL: /api/index.php?method=private.addressbook.deleteContact
HTTP Action: POST
Parameters:
  • xContact - Required
Simple Example:
curl -X POST \
'http://.../api/index.php?method=private.addressbook.deleteContact' \
  --header 'Authorization: Bearer 3|QeJDIPybZSjykqjzuxVJ94WqlaoVruWWbEm4ffqc' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'xContact=1'
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<addressbook>
    <deleted>1</deleted>
</addressbook>

private.addressbook.getContacts

Retreives all contacts in the internal addressbook.
URL: /api/index.php?method=private.addressbook.getContacts
HTTP Action: GET
Parameters: none
Simple Example:
curl -X POST \
'http://.../api/index.php?method=private.addressbook.getContacts' \
  --header 'Authorization: Bearer 3|QeJDIPybZSjykqjzuxVJ94WqlaoVruWWbEm4ffqc' \
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<addressbook>
    <contact>
        <xContact>3</xContact>
        <sFirstName>Jane</sFirstName>
        <sLastName>Doe</sLastName>
        <sEmail>Jane.Doe@example.com</sEmail>
        <sTitle>CEO</sTitle>
        <sDescription>Additional description values</sDescription>
        <fHighlight>1</fHighlight>
    </contact>
    <contact>
        <xContact>2</xContact>
        <sFirstName>John</sFirstName>
        <sLastName>Doe</sLastName>
        <sEmail>John.Doe@example.com</sEmail>
        <sTitle>Director of HR</sTitle>
        <sDescription>Additional description values</sDescription>
        <fHighlight>0</fHighlight>
    </contact>
</addressbook>

Knowledge Tags
API  / 

Related Pages
This page was: Helpful | Not Helpful