Support & Docs
Powered by HelpSpot

Home → API Manual → Printer Friendly Version

API Manual

Complete documentation on all of the HelpSpot API's.

1. Live Lookup
2. Request Push API
3. AJAX Selection Field
- 3.1. Overview
- 3.2. AJAX Selection Field Implementation Guide
4. Web Service API
5. Email Parser API
- 5.1. Email Parser: Using Email as a Service
- 5.2. Email Parser: Advanced Tags
Appendix
- 1. API Field Definitions

1. Live Lookup

1.1. Live Lookup Overview

Live lookup allows HelpSpot to communicate with an external database, CRM, or system storing customer information pertinent to the support staff.

The power of live lookup is it provides real-time access to data from external systems from within HelpSpot; ensuring accurate customer information and custom field data for reporting purposes.

Sample uses include looking up/inserting: customer ID, contact information, contract status, selected HR data, passwords, or even IT asset profiles.

Basic Workflow

Once enabled, use of live lookup follows this basic workflow.

↓    Staff click the Live Lookup tab found above the Customer Information box on the request page.

↓    HelpSpot sends all available customer information and custom field values to a script written by an Administrator (or other technical resource).

↓    The script will look up the customer information and compare to what is stored in the pre-defined system/database. (Examples: Active Directory, SalesForce).

↓    Customer information is returned and HelpSpot displays the results in an embedded window. If multiple matches are found, a list will be returned to the User for selecting the correct one.

↓    With the correct customer selected, their information (and any specified custom fields) can be inserted into HelpSpot.

Live Lookup in Action

The following shows live lookup as it appears for staff on the request page.

Subsequent pages in this chapter provide an in-depth look at configuration and implementation.

1.2. Configuration and Implementation

As mentioned in the previous page, live lookup works by passing information currently available about a customer in a request to an external script you specify.

This is done through either the command line or over http/https (recommended). Once HelpSpot sends all available information via HTTP or as arguments to the command line script, your script will then processes those arguments to find out additional details about the customer and returns a very simple XML document outlined below.

Steps to Set up

Enable live lookup in admin->settings. Specify if the script is http or command line and provide the full path.
Once enabled, the Live Lookup tab will become active in the customer information box. When this tab is clicked a live lookup request will be made to the location you specified.
The following attributes are passed to your script:
- customer_id
- first_name
- last_name
- email
- phone
- xStatus
- xCategory
- xPersonAssignedTo
- Custom# (# is the ID of the custom field being passed)
- acting_person_xperson (staffer running the Live Lookup)
- acting_person_fusertype (staffer level 1-admin, 2-HD, 3-L2, 4-Guest)
- acting_person_fname
- acting_person_lname
- acting_person_email
Note: When using live lookup in HTTP mode these are passed as shown. In command line mode they are passed in the order shown above.

For example, given the information in the image above, HelpSpot would pass this HTTP GET string to your script:
?customer_id=123456&first_name=Bob&last_name=Jones&email=&phone=
Your script will process the search parameters passed in and return a result set. A result set containing only one <customer> element is considered a direct match by HelpSpot and the data will be displayed. If multiple <customer> elements are returned then a list of possible matches will be shown to the staff member. They may then click on each to view the details.

Sample PHP Live Lookup scripts are available here:

XML Specification

Below is a description and samples of the XML file your script should return when called from HelpSpot Live Lookup. For quick studies here's a simple example:

<?xml version="1.0" encoding="utf-8"?>
<livelookup version="1.0" columns="first_name,last_name">
	<customer>
		<!-- These are standard elements which can be inserted back into a request -->
		<customer_id>12334</customer_id>
		<first_name>Bob</first_name>
		<last_name>Jones</last_name>
		<email>bjones@sampleinc.com</email>
		<phone>845-555-4278</phone>
		<!-- These are custom elements which may be useful to the help desk staff member -->
		<organization>Sample Inc</organization>
		<password>The Password</password>
	</customer>
</livelookup>

Here's a larger Sample File

Root element: <livelookup>

This element must always be the root element of your document. It can contain these attributes:

Attribute	Description	Example
version	A version string, currently 1.0	version="1.0"
columns	This attribute tells HelpSpot which columns to display to your staff when more than one <customer> element is returned.	columns="Organization,Contract_Date"

Sub element: <customer>

A live lookup result set may contain any number of <customer> sub elements. When none are returned HelpSpot will interpret this to mean no results were found for the search. One is a direct match and if more than one is found each customer element will be listed using the columns described above in the <livelookup> element.

Each <customer> element must return the sub element <customer_id>. All other elements are optional, but if found they will be insertable into HelpSpots request fields.

Element	Description	Example
<customer_id>	Required: should return a unique value for the customer	<customer_id>12334</customer_id>
<first_name>	The customers first name	<first_name>Bob</first_name>
<last_name>	The customers last name	<last_name>Jones</last_name>
<email>	The customers email address	<email>bjones@sampleinc.com</email>
<phone>	The customers phone number	<phone>845-555-8765</phone>
<Custom#>	A custom field value where # is the Custom field ID from Admin->Tools->Custom Request Fields.	<Custom1>New York City</Custom1>

User Defined Elements

In addition to the predefined elements listed above, user defined elements specific to your installation may be returned. These elements will be show in the results along with the predefined ones. For example, you may want to return the customers password so staff don't have to continue looking up the password in a seperate browser window. To do that you would simply return <password>The Password</password> along with the other elements in your <customer> tag. The examples below show this feature.

Returning HTML

You can return HTML in your Live Lookup results by using a standard cdata block such as:

<admin_link>
<![CDATA[ 
<a href="http://admin.company.com">Company Admin</a>
]]>
</admin_link>

This is very useful for passing back tables of information, links to other systems or to emphasize information such as turning an expired support contract into red text.

Custom Field Example

To pass information in which maps to a custom field you need to add your XML tags in a special format. The tags should be <Custom#> where # is the ID number of the custom field (shown on the custom field page within HelpSpot). This tag is case sensitive and will automatically show the correct name of the custom field when the field is displayed.

<?xml version="1.0" encoding="utf-8"?>
<livelookup version="1.0" columns="first_name,last_name">
	<customer>
		<customer_id>12334</customer_id>
		<first_name>Bob</first_name>
		<last_name>Jones</last_name>
		<email>bjones@sampleinc.com</email>
		<phone>845-555-4278</phone>
		<organization>Sample Inc</organization>
		<Custom1>New York</Custom1>
		<Custom5>Building 743</Custom5>
	</customer>
</livelookup>

Example: Single Match

<?xml version="1.0" encoding="utf-8"?>
<livelookup version="1.0" columns="first_name,last_name">
	<customer>
		<customer_id>12334</customer_id>
		<first_name>Bob</first_name>
		<last_name>Jones</last_name>
		<email>bjones@sampleinc.com</email>
		<phone>845-555-4278</phone>
		<organization>Sample Inc</organization>
		<password>The Password</password>
	</customer>
</livelookup>

Results in:

Example: Multiple Matches

<?xml version="1.0" encoding="utf-8"?>
<livelookup version="1.0" columns="first_name,last_name">
	<customer>
		<customer_id>12334</customer_id>
		<first_name>Bob</first_name>
		<last_name>Jones</last_name>
		<email>bjones@sampleinc.com</email>
		<phone>845-555-4278</phone>
		<organization>Sample Inc</organization>
		<password>The Password</password>
	</customer>
	<customer>
		<customer_id>56757</customer_id>
		<first_name>Tina</first_name>
		<last_name>Smith</last_name>
		<email>tsmith@sampleinc.com</email>
		<phone>845-555-8932</phone>
		<organization>Sample Inc</organization>
		<password>abcdefg</password>
	</customer>
	<customer>
		<customer_id>95544</customer_id>
		<first_name>Tim</first_name>
		<last_name>Myers</last_name>
		<email>tmyers@sampleinc.com</email>
		<phone>845-555-9812</phone>
		<organization>Sample Inc</organization>
		<password>thyekbg</password>
	</customer>
</livelookup>

Results in:

1.3. Configuration for Global Address Book

HelpSpot's address book is designed to optionally query Live Lookup results for address book contacts. In additional to HelpSpot's own address book storage, this functionality allows a truly global address book that can return contacts from nearly any source.

Using Live Lookup as a global address book requires the same configuration as a standard Live Lookup, in fact it uses your existing Live Lookup search sources. The only difference is that the address book looks for some particular XML tags in the results and treats them special.

The main 3 XML elements (first_name, last_name, email) are standard in most Live Lookup scripts so in most cases the address book can use existing Live Lookup results with no changes, however, the additional 3 tags can be useful to make the results richer.

Live Lookup Address Book Tags

Element	Description	Example
<first_name>	The customers first name	<first_name>Bob</first_name>
<last_name>	The customers last name	<last_name>Jones</last_name>
<email>	The customers email address	<email>bjones@sampleinc.com</email>
<title>	This persons title	<title>Division Manager</title>
<description>	A description of what the person does or why they should be contacted.	<description>Overnight contact</description>
<highlight>	If the person should be listed at the top of the results	<highlight>1</highlight>

1.4. Sample Implementation: Salesforce.com

Integrate your Help Desk with SalesForce.com

The code linked below is everything you need to integrate HelpSpot into your Salesforce.com account using the Salesforce.com API and HelpSpot's Live Lookup API.

Seemlessly pull customer data out of Salesforce and display it on the HelpSpot request page. Even fill in customer data at the click of a button using HelpSpot's Live Lookup API

Who can use it?

Only Enterprise and Ultimate edition Salesforce.com customers can use this code because the API is only available at those levels. If Salesforce eventually makes the API available to other levels this code will work with those as well.

This will work with any HelpSpot installation version 1.5.5 or higher.

Installation

Instructions for installation and setup are within the ll-sforce.php file in the download zip.

1.5. Sample Implementation: Active Directory via Linked SQL Server

This code and instructions were graciously contributed by Richard Edwards of DNN Stuff.

This implementation explains how to connect to Active Directory via a link through Microsoft SQL Server rather than directly via PHP's LDAP functions. Using this linked method has shown significant performance improvements when querying for Live Lookup results.

Configuration

Create a linked server on MS SQL Server by issuing the following command: sp_addlinkedserver 'ADSI', 'Active Directory Service Interfaces', 'ADSDSOObject', 'adsdatasource'
In SQL Enterprise Manager, go to Security, Linked Servers, ADSI and right click, choose properties
On Security tab, select the last option 'Be made with this security context' and enter an account that has access to read Active Directory, click OK.
Put the live_lookup_ad_mssql_linkedserver.php file (downloadable below) into your HelpSpot custom_code directory
Edit the file and change the parameters for $myServer, $myUser, $myPass to point to your MS SQL server. Also, edit line 61 (the AD query) to use your domain. For example change DC=example,DC=com to OU=my org unit,DC=mydomain,DC=net if you wanted to just search the organizational unit 'my org unit' for the domain 'mydomain.net'. The query on lines 60-62 determines the scope of the search.
In HelpSpot under Admin->Settings change the Live Lookup URL to point to this file

1.6. Sample Implementation: 37Signals Highrise

This PHP script allows integration between HelpSpot and Highrise using HelpSpot's Live Lookup API. Using Live Lookup staff can view customer details stored in Highrise directly from the request screen.

The script also serves as an example of how Live Lookup can be used with another web service API in only a few lines of code.

Requirements

PHP 5+
PHP Curl Module installed

Installation

Download the file below and place on any web server in a location where HelpSpot can reach the file via HTTP. In HelpSpot set the location of the file in Admin->Settings->Live Lookup and integration is complete.

1.7. Sample Implementation: Address Book

This example shows Live Lookups flexibility. It's often desirable to be able to quickly set a TO/CC/BCC for a note. This sample shows how to use Live Lookup to create a simple address book for commonly used email addresses.

This sample creates a list of email addresses which can be clicked to be inserted as a TO/CC/BCC. The list of addresses are static in this example, but could easily be pulled from a dynamic source such as AD/LDAP, a database, etc. It would also be easy to modify this example to display more information than just the persons name.

Installation

Upload the file on your web server in an HTTP accessible location.
In Admin->Settings->Live Lookup and configure a new source for the file.
The address book will now be available for staff use

2. Request Push API

2.1. Overview

The Request Push API allows you to "push" a request out of HelpSpot into another system. Using this functionality you can tie HelpSpot to other business applications such as bug trackers, CRM tools, Intranets, and communication systems.

The basics of the Request Push API are as follows. Once you've created a Request Push API file (outlined in the Implementation Guide) each request page will have a Request Push link in the options area. An optional comment can be added before selecting the receiving system and clicking the push button to initiate the process.

Once initiated within HelpSpot, your code will pick-up the request information and perform the action(s) you defined. Normally this will be a call to another systems API, but it could be a database insert, sending an email, etc.

You can optionally return to HelpSpot a unique ID. If a unique ID is provided HelpSpot will make available a link in the request where an update can be retrieved from the receiving system.

Example: a request is pushed to a bug tracker. A link would be available inside the request page that allows staff to retrieve the status of this bug. Your code returns an HTML block formatted as you have defined to show the information you need displayed. The left column is information provided by HelpSpot, the right column is your returned HTML.

Note: Since HelpSpot 2.6 a Request Push can also be initiated via an Automation Rule. This can be very useful in automating the pushing of requests into other systems.

2.2. Request Push Implementation Guide

Implementing the Request Push API requires 4 steps.

Copy the /custom_code/RequestPush-base.php file to a new name
Rename class
Write the code for the push method of the PHP class
Write the code for the details method of the PHP class (optional)

Creating the Push File

HelpSpot determines the available request push destinations by the files and names of the files in the /custom_code directory in HelpSpot. To create a new push destination you must first copy the /custom_code/RequestPush-base.php file to /custom_code/RequestPush-YOURNAME.php (where YOURNAME is the name of your destination). The name should only contain letters, numbers, underscores and dashes. No spaces.

Valid file name: RequestPush-Mantis.php

Invalid name: RequestPush-Mantis Bug Tracker.php

Rename the Class

Once the new push file is created, open in a text editor. Near the top of the file you'll see a line that looks as follows:

class RequestPush_base{

You should rename the class and replace 'base' with the name you used in the file. So from the above example our class should now look like this:

class RequestPush_Mantis{

Be sure capitalization, dashes and/or underscores are consistent.

Writing the Push Method

The class has 2 methods. The first is the push method, this is the method that accepts the request information and processes it. Processing can be anything required by the system you're integrate with. Normally this will be an API call, a database insert, sending an email, or even a combination of actions.

There's a few important items to cover before you can write your push code:

Request Data Format

The request data is passed into the push method as an associative array. The array contains these keys:

Array(
    [xRequest] => 12400
    [fOpenedVia] => 7
    [xOpenedViaId] => 0
    [xPersonOpenedBy] => 0
    [xPersonAssignedTo] => 1
    [fOpen] => 1
    [xStatus] => 1
    [fUrgent] => 1
    [xCategory] => 4
    [dtGMTOpened] => 1183214861
    [dtGMTClosed] => 0
    [iLastReplyBy] => 1
    [iLastReadCount] => 21
    [fTrash] => 0
    [dtGMTTrashed] => 0
    [sRequestPassword] => "hckzke"
    [sTitle] => ""
    [sUserId] => ""
    [sFirstName] => "Bob"
    [sLastName] => "Jones"
    [sEmail] => "bobjones@gmail.com"
    [sPhone] => ""
    [sRequestHash] => 9582c31acbac5f8556df01f84817cf4c
    [Custom##] => ""
    [fullname] => "Bob Jones"
    [staff_comment] => ""
    [assigned_person_fname] => "Tom"
    [assigned_person_lname] => "Landers"
    [assigned_person_email] => "tlanders@company.com"
    [acting_person_xperson] => 7
    [acting_person_fusertype] => 1
    [acting_person_fname] => "Tina"
    [acting_person_lname] => "Jones"
    [acting_person_email] => "tjones@company.com"
    [request_history] => Array(
            [236] => Array(
                    [xRequestHistory] => 236
                    [xRequest] => 12403
                    [xPerson] => 1
                    [dtGMTChange] => 1184021870
                    [fPublic] => 0
                    [fInitial] => 0
                    [fNoteIsHTML] => 0
                    [fMergedFromRequest] => 0
                    [tLog] => ""
                    [tNote] => "Request history note"
                    [tEmailHeaders] => ""
                    [file] => Array(
                         [0] => Array(
                             [sFileMimeType] => image/jpeg
                             [sFilename] => icon.jpg
                             [xDocumentId] => 59
                             [public_url] => http://www.site.com/index.php?...
                             [private_url] => http://www.site.com/admin.php?...
                            )
                      )
                )
        )
)

You can read about each field on the API field definition page.

Return Unique ID

After you've pushed the request to your other system you may optionally return a unique ID. If you do return a unique ID, HelpSpot will retain this ID to allow staff to retrieve updates about this push. It's important that the ID be unique, it will be the only parameter passed to the "details" method of the Request Push class you're implementing. You'll need to use that ID to retrieve the update information.

The returned ID may contain any characters and be up to 255 characters long. You return the ID by adding a return statement to the push method as shown below:

function push($request){
	/* Perform actions with request data here */
	
	return "UNIQUE ID";
}

Error Handling

Error messaging in the classes $errorMsg property must be set to address situations when a push cannot be completed. If set, HelpSpot will detect this and display the error to the staff member attempting the push. Errors are not logged at this time.

function push($request){
	//Something has gone wrong
	$this->errorMsg = "Couldn't connect to database";
}

Writing the Details Method

If you opt to return unique ID's in the push method, you should also implement the details method so those ID's return information about a push.

The details method is passed only one argument, the unique ID of a previous Request Push. The details method should use that ID to query the system being pushed to and find out whatever information there is about the status of the pushed request. You can then format those details into HTML and return the HTML. Here's a short example:

function details($id){
	/* Go get details using ID here */
	
	//Format details into HTML
	$html = '<b>'.$status.'</b>';
	
	return $html;
}

Note in this very simple example we're returning a status code in bold. You could do much more with this. For instance you could build out a full HTML table to display the details. Also note, you don't have to build the HTML within the details method. You can have an external script which builds the HTML. In the details method you simply call that script with the ID and return the completed HTML.

2.3. Sample Implementation: FogBugz

This is a sample Request Push API file for the bug tracker FogBugz. This example is functional as is, but could also be expanded upon as needed for your particular installation. By adding this file to your HelpSpot installation you'll allow staff members in HelpSpot to push a request directly into FogBugz as well as check on the progress of that newly created case from within HelpSpot.

Screenshots:

Requirements:

FogBugz Version 6+
FogBugz API version 3+
PHP version 5.1.0+
PHP CURL module installed

Installation Instructions

Download the file below
Open the file in a text editor and edit the following 3 variables:
1. $fb_url - The URL to your FogBugz installation
2. $fb_user_email - The email of the user who should be used to login to the API
3. $fb_user_password - The password of the user who should be used to login to the API
Upload the file into HelpSpot's /custom_code folder

That's it, you'll now be able to push any existing request from HelpSpot into FogBugz.

2.4. Sample Implementation: 37 Signals Highrise

This is a sample Request Push API file for the CRM tool, Highrise. This example is functional as is, but could also be expanded upon as needed for your particular needs. By adding this file to your HelpSpot installation you'll allow staff members in HelpSpot to push a customer/person/contact directly into Highrise. The attached script will also check that you're not adding a person who already exists so that duplicates are not created.

Screenshots:

Requirements:

PHP version 5.1.0+
PHP CURL module installed

Installation Instructions

Download the file below
Open the file in a text editor and edit the following 2 variables:
1. $highrise_url - The URL to your Highrise installation
2. $api_token - An API token from your "my info" page
Upload the file into HelpSpot's /custom_code folder

That's it, you'll now be able to push any existing request from HelpSpot into Highrise.

2.5. Sample Implementation: 37 Signals Campfire

This is a sample Request Push API file for the group chat tool, Campfire. This script by default logs the staff comment to a Campfire chat room, though it could be modified to include other information like the initial request note, status, category and so on.

This script is particularly useful to use with Automation Rules. You can have an Automation Rule use this Request Push script as it's action, so each time a request meets a certain set of conditions post a note in your Campfire account.

Screenshots

Requirements:

PHP version 5.2.1+ Preferred, Should work with any version though if upload_tmp_dir is set.
PHP CURL module installed

Installation Instructions

Download the file below
Open the file in a text editor and edit the following 4 variables:
1. $campfire_url - The full URL to your account. ex: http://[account].campfirenow.com
2. $campfire_username - The Campfire user you want to log messages as. (usually an email address)
3. $campfire_password - The users Campfire password
4. $campfire_roomid - The room ID we want to log to. You can find this in the URL of the room when you enter it. ex: /room/182650 - 182650 is the ID
Upload the file into HelpSpot's /custom_code folder

That's it, you'll now be able to push any existing request from HelpSpot into Campfire.

2.6. Sample Implementation: ActiveCollab

This is a sample Request Push API file for the project management tool ActiveCollab. This example is functional as is, but could also be expanded upon as needed for your particular installation. By adding this file to your HelpSpot installation you'll allow staff members in HelpSpot to push a request directly into ActiveCollab to create a new ticket.

Requirements:

PHP version 5.1.0+
PHP CURL module installed

Installation Instructions

Download the file below
Open the file in a text editor and edit the following 3 variables:
1. $acollab_projid - The project ID to add a ticket to
2. $acollab_token - Your API token
3. $acollab_url - ActiveCollab URL from the API token page
Upload the file into HelpSpot's /custom_code folder

That's it, you'll now be able to push any existing request from HelpSpot into ActiveCollab.

3. AJAX Selection Field

3.1. Overview

The AJAX Selection Field is a dynamic way to enter information into a request. The AJAX Selection Field is similar to a regular text custom field, however, its value may be set by a drop down list created dynamically (in real time) through the use of AJAX (a web scripting technology). This allows the drop down list to be custom to the specific customer or even that specific request. It also proves to be useful in situations where the values of a drop down list may change periodically as it eliminates the need to edit the custom field values in HelpSpot.

When an AJAX Selection Field is used all the information about the request is passed to a script you write (outlined in the implementation guide). Your script can use that information to return drop down list items specific to that request.

One sample use of this is to return a list of billing codes that are specific to a customer or category.

Another feature of the AJAX Selection Field is that it can be used as a search box. Along with information on the request, your script is also sent the value of the AJAX Selection Field. So if you enter a search term in the text box and then click the AJAX Selection field button, the script can use that search term to produce the drop down list of results.

3.2. AJAX Selection Field Implementation Guide

The first step in creating an AJAX Selection field is to create a script file on your web server. This script can be in any language, common selections are PHP, ASP, Perl, Python, or Ruby. An example file in PHP is linked at the bottom of this page.

This script will be called via HTTP GET with the following query parameters:

xStatus
xPersonAssignedTo
xCategory
sUserId
sPhone
sLastName
sFirstName
sEmail
Custom## (note all custom fields will be included)
callingField

Details on the meaning of these parameters can be found on the API field definition page.

One field to note is "callingField". This parameter holds the value of the AJAX Selection Field who's button was pushed. This value can be useful if you want to use the AJAX Selection Field as a search box.

Using the parameters sent to your script, you'll query your data source. Once you have the selection list you'd like to return you simply format it in the XML specified below and return that to the HTTP call.

AJAX Selection Field XML Specification

The XML your script should return is very simple. An empty result set is below:

<ajaxfield>
	<option>
		<value></value>
		<description></description>
	</option>
</ajaxfield>

For each selection item you should have a pair of option tags. Each option tag has within it a set of value and description tags. The value holds the value which should be entered into the field when the option is selected. The description is the text shown to the staff member in the drop down select list. An example of the XML and the select list is produces is below:

<ajaxfield>
	<option>
		<value>#4878</value>
		<description>Support</description>
		</option>
	<option>
		<value>#9978</value>
		<description>Emergency Support</description>
	</option>
	<option>
		<value>#9775</value>
		<description>Custom Development</description>
		</option>
	<option>
		<value>#2111</value>
		<description>Training</description>
	</option>
</ajaxfield>

This XML results in:

4. Web Service API

4.1. Web Service API Overview

The HelpSpot web services API is designed to allow you to integrate HelpSpot with other applications. These may be desktop or web based, back office or for the public.

API Design

The HelpSpot API is an HTTP based API, meaning that all interactions take place over standard HTTP. For example, GET requests are used to retrieve information and POST requests to submit information.

The API supports 3 different types of return values: XML, JSON, or PHP. Depending on what client application you're accessing the API from one return format may be easier to use than another. For instance, if you're accessing the API from a javascript library using JSON will be easiest as JSON is javascript. For a desktop client using the API, XML is likely best since that will be the easiest to parse and display. The default return type is XML.

Public/Private Interfaces

The foundation of the API is the distinction between the public and private interfaces. The public API works just like the HelpSpot portal in that it requires no authentication to use. The private interface is designed for applications that need to access the system as a staff member and require authentication.

Public Interface

To use the public API you must first enable it in Admin->Settings->Web Services API. Once enabled any application that implements the API can submit API requests to that installation. A few simple example uses of the public API follow:

Add built in request submission and tracking to an application your company builds, removing the need for customers to leave the application to request support.
Allow web forms on different sites to all submit to the same HelpSpot installation.
Allow automated logging of server/hardware errors to HelpSpot as requests.
Pull knowledge book information into an intranet or application
Log maintenance issues to the public forum

Private Interface

To use the private API you must first enable it in Admin->Settings->Web Services API. Once enabled any clients which implement the private API can submit API requests to that installation. A few example uses of the private API follow:

Integrate a users filters into their intranet homepage.
Display a users filters in a custom desktop applicaiton.
Submit requests with full control over categories, custom fields and assignment from any external application.
Integrate HelpSpot with other server systems staff use and allow cross request generation and filter display.
Create a custom notification system

4.2. API Basics: URL, Methods, Return Formats, Authentication

How to Enable the API

By default both the public and private API's are disabled. You must enable them to use them in Admin->Settings->Web Services API

API URL

The API is accessed from the URL: http://www.domain.com/api/index.php.

Specific methods are accessed by using the "method" query string parameter. Example:

http://www.domain.com/api/index.php?method=request.get

Public vs Private

The HelpSpot API contains both public and private methods. Private methods require authentication, public do not. Private methods are those that start with "private". For example: private.filter.get

Return Format

3 return types are currently supported:

XML (this is the default)
JSON
Serialized PHP

You can specify the return type you wish to receive back from the API by adding the "output" query string parameter to your API URL. If you want to receive XML then you do not need to specify the output as that is the default. Example:

/api/index.php?method=request.get&output=json

The "output" parameter will accept xml, json, or php as valid values.

Private API Authentication

Private API requests require a staff members email address (or username if using Black Box) and password. There are 2 ways to pass this information to the API.

1. HTTP Basic Authentication
You may pass in the username and password via HTTP basic authentication. Libraries such as cURL generally support this.

2. URL Parameters
The information may be passed directly in the URL as parameters. Example:

/api/index.php?method=request.get&username=tim@domain.com&password=abc123

Character Set

The API currently expects iso-8859-1 data. Additional character sets may be supported in the future.

Version Information

You may always retrieve the current and minimum versions of the API by calling the "version" method. Example:

/api/index.php?method=version

/api/index.php?method=private.version (note this requires authentication as all private methods do)

This method will return:

version - The current version of the API the installation is using.
min_version - The minimum version of the API a client application must support in order to operate correctly with the server installation. For instance, if the server API is currently 3.0 with a minimum version of 2.0 then a client written to use the 1.0 API would not function properly. Clients should check this value before using the API.

Errors

If an error occurs instead of the methods XML an error XML data will be returned instead. The data is in this format:

<?xml version="1.0" encoding="iso-8859-1"?>
<errors>
	<error>
		<id>2</id>
		<description>User authentication failed</description>
	</error>
</errors>

More than one error tag may occur in the root errors tag.

If the API type being accessed (public or private) is not enabled in Admin->Settings an error in the following format will be returned.

<?xml version="1.0" encoding="iso-8859-1"?>
<reply>Private API not enabled</reply>

Errors always return a "400 Bad Request" HTTP header as well.

The Easiest Way to Try the API

The easiest way to start is by using curl or even FireFox to try some of the public API calls. Make sure the public API is enabled, then try these URL's:

Get the version:
/api/index.php?method=version
List the public knowledge books:
/api/index.php?method=kb.list
Get an existing request in the system:
/api/index.php?method=request.get&accesskey=####(use the access key for the request)

4.3. API Error Codes

This page lists the error codes that may be returned by the HelpSpot Web Service API. Details on the XML format of errors is available on the API Basics page.

ID	Error Message
001	Authentication information not sent
002	User authentication failed
101	Required parameter ### not supplied
102	Valid access key required
103	Valid request ID required
104	Email or password not valid
105	Valid email required
201	Invalid method provided
202	Could not create topic
203	Forum is closed
204	Could not create post
205	Topic ID does not exist
206	Could not create request
207	Could not create request: ###
208	Request has been merged
209	Time event could not be added
210	Request could not be updated
211	Password could not be updated
212	Could not update request: ###
213	Could not merge requests
301	Trial expired

If the API type being accessed (public/private) is not enabled in Admin->Settings the following errors will be returned.

Type	Message
Public	Public API not enabled
Private	Private API not enabled

4.4. Public Methods

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

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

Methods:

customer.getRequests
Return all requests for a customer.
Available as of HelpSpot version: 2.4.2
URL:	/api/index.php?method=customer.getRequests
HTTP Action:	GET
Parameters:
sEmail - Required sPassword - Required
Other notes:	Note that this method follows the settings used on the portal, so if Black Box Authentication for the portal login is in use that type of username should be in the sEmail field.
Other notes:	The results are also based on the setting for Admin->Settings->Portal->Show Request History Based On. This determines if matches are based on email address or customer ID. Email address is the default.
Simple Example: curl "http://.../api/index.php?method=customer.getRequests&sEmail=tsmith@companyco.com&sPassword=nusoxdln"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <requests> <request> <xRequest>12489</xRequest> <fOpenedVia>2</fOpenedVia> <xOpenedViaId>0</xOpenedViaId> <fOpen>1</fOpen> <xStatus>1</xStatus> <fUrgent>0</fUrgent> <xCategory>2</xCategory> <dtGMTOpened>1212776831</dtGMTOpened> <sRequestPassword>jiicxp</sRequestPassword> <sTitle>RE: Information on Your Request</sTitle> <sUserId /> <sFirstName>Tim</sFirstName> <sLastName>Smith</sLastName> <sEmail>tsmith@companyco.com</sEmail> <sPhone /> <sCategory>Account Inquiries</sCategory> <sStatus>Active</sStatus> <tNote>I am looking for information on my account.</tNote> <fullname>Tim Smith</fullname> <accesskey>12489jiicxp</accesskey> </request> </requests>

request.create
Create a new request. Acts exactly as the portal web form.
URL:	/api/index.php?method=request.create
HTTP Action:	POST
Parameters:
tNote - Required xCategory sFirstName sLastName sUserId sEmail sPhone fUrgent File#_sFilename (# is the file number starting at 1) File#_sFileMimeType File#_bFileBody Custom# (# is the custom field ID)
Other notes:	In addition to tNote you must also have at least one of the following set: sFirstName,sLastName,sUserId,sEmail,sPhone.
Other notes:	Custom field rules for selected category apply.
Simple Example: curl -F"tNote=This is the request." -F"sUserId=12345" http://.../api/index.php?method=request.create
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <request> <xRequest>12744</xRequest> <accesskey>12744uaxith</accesskey> </request>

request.update
Update an existing request. The only option is to add a note, just as in the web portal.
URL:	/api/index.php?method=request.update
HTTP Action:	POST
Parameters:
accesskey - Required tNote - Required File#_sFilename (# is the file number starting at 1) File#_sFileMimeType File#_bFileBody
Simple Example: curl -F"accesskey=12345abcxyz" -F"tNote=Update the request." http://.../api/index.php?method=request.update
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <request> <xRequest>12745</xRequest> </request>

request.getCategories
Returns a list of all the public categories
URL:	/api/index.php?method=request.getCategories
HTTP Action:	GET
Parameters:	none
Simple Example: curl http://.../api/index.php?method=request.getCategories
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <categories> <category> <xCategory>3</xCategory> <sCategory>Usage Question</sCategory> <sCustomFieldList> <xCustomField>7</xCustomField> <xCustomField>5</xCustomField> <xCustomField>11</xCustomField> <xCustomField>9</xCustomField> <xCustomField>2</xCustomField> </sCustomFieldList> </category> <category> <xCategory>1</xCategory> <sCategory>Report a Bug</sCategory> <sCustomFieldList> <xCustomField>2</xCustomField> </sCustomFieldList> </category> </categories>

request.getCustomFields
Returns a list of all the public custom fields
URL:	/api/index.php?method=request.getCustomFields
HTTP Action:	GET
Parameters:	none
Simple Example: curl http://.../api/index.php?method=request.getCustomFields
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <customfields> <field> <xCustomField>6</xCustomField> <fieldName>Office</fieldName> <isRequired>0</isRequired> <fieldType>text</fieldType> <iOrder>0</iOrder> <sTxtSize>30</sTxtSize> <lrgTextRows /> <listItems /> <iDecimalPlaces>0</iDecimalPlaces> <sRegex /> <isAlwaysVisible>1</isAlwaysVisible> </field> <field> <xCustomField>2</xCustomField> <fieldName>Database</fieldName> <isRequired>0</isRequired> <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 /> <isAlwaysVisible>0</isAlwaysVisible> </field> </customfields>

request.get
Return all public information on a request.
URL:	/api/index.php?method=request.get
HTTP Action:	GET
Parameters:
accesskey - Required
Simple Example: curl "http://.../api/index.php?method=request.get&accesskey=12345abcxyz"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <request> <xRequest>12745</xRequest> <fOpenedVia>6</fOpenedVia> <xOpenedViaId>0</xOpenedViaId> <fOpen>1</fOpen> <xStatus>1</xStatus> <fUrgent>0</fUrgent> <xCategory>0</xCategory> <dtGMTOpened>1190677473</dtGMTOpened> <dtGMTClosed>0</dtGMTClosed> <sRequestPassword>itetxb</sRequestPassword> <sTitle /> <sUserId>12345</sUserId> <sFirstName /> <sLastName /> <sEmail /> <sPhone /> <fullname> </fullname> <sStatus>Active</sStatus> <sCategory /> <sAssignedToFirstName>Ian</sAssignedToFirstName> <request_history> <item> <xRequestHistory>1376</xRequestHistory> <xRequest>12745</xRequest> <dtGMTChange>1190678625</dtGMTChange> <fInitial>0</fInitial> <tNote>Update the request.</tNote> <fNoteIsHTML>0</fNoteIsHTML> <files> <file> <sFileMimeType>application/pdf</sFileMimeType> <sFilename>Sample Document.pdf</sFilename> <xDocumentId>60</xDocumentId> <url>http://www.domain.com/index.php?pg=file&from=3&id=60&reqid=12745itetxb&reqhisid=1378</url> </file> </files> <firstname /> <lastname /> </item> <item> <xRequestHistory>1375</xRequestHistory> <xRequest>12745</xRequest> <dtGMTChange>1190677473</dtGMTChange> <fInitial>1</fInitial> <tNote>This is the request.</tNote> <fNoteIsHTML>0</fNoteIsHTML> <file /> <firstname /> <lastname /> </item> </request_history> </request>

forums.list
Returns a list of all the public forums
URL:	/api/index.php?method=forums.list
HTTP Action:	GET
Parameters:	none
Simple Example: curl http://.../api/index.php?method=forums.list
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <forums> <forum> <xForumId>1</xForumId> <sForumName>Product Beta</sForumName> <sDescription>Discuss questions, bugs, ideas and more</sDescription> <fClosed>0</fClosed> <iOrder>0</iOrder> </forum> </forums>

forums.get
Return information on a forum.
URL:	/api/index.php?method=forums.get
HTTP Action:	GET
Parameters:
xForumId - Required
Simple Example: curl "http://.../api/index.php?method=forums.get&xForumId=1"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <forum> <xForumId>1</xForumId> <sForumName>Product Beta</sForumName> <sDescription>Discuss questions, bugs, ideas and more</sDescription> <fClosed>0</fClosed> <iOrder>0</iOrder> </forum>

forums.getTopics
Return a list of topics from the given forum.
URL:	/api/index.php?method=forums.getTopics
HTTP Action:	GET
Parameters:
xForumId - Required start (record set position to start at) length (how many records to return)
Simple Example: curl "http://.../api/index.php?method=forums.getTopics&xForumId=1"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <topics> <topic> <xTopicId>43</xTopicId> <xForumId>1</xForumId> <fClosed>0</fClosed> <fSticky>0</fSticky> <dtGMTPosted>1190081243</dtGMTPosted> <sName>Bob Smith</sName> <sTopic>How do I get started with installation</sTopic> <postcount>2</postcount> </topic> <topic> <xTopicId>42</xTopicId> <xForumId>1</xForumId> <fClosed>0</fClosed> <fSticky>0</fSticky> <dtGMTPosted>1190080694</dtGMTPosted> <sName>Tiny Jones</sName> <sTopic>Bug in the installer</sTopic> <postcount>2</postcount> </topic> </topics>

forums.getPosts
Return a list of posts from the given topic.
URL:	/api/index.php?method=forums.getPosts
HTTP Action:	GET
Parameters:
xTopicId - Required
Simple Example: curl "http://.../api/index.php?method=forums.getPosts&xTopicId=1"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <posts> <post> <xPostId>171</xPostId> <xTopicId>43</xTopicId> <dtGMTPosted>1190081243</dtGMTPosted> <sName>Bob Smith</sName> <sURL /> <tPost>This is my post.</tPost> <sLabel /> </post> <post> <xPostId>172</xPostId> <xTopicId>43</xTopicId> <dtGMTPosted>1190081249</dtGMTPosted> <sName>Jen Tandy</sName> <sURL /> <tPost>Another post in reply.</tPost> <sLabel /> </post> </posts>

forums.createTopic
Create a new forum topic.
URL:	/api/index.php?method=forums.createTopic
HTTP Action:	POST
Parameters:
xForumId - Required sTopic - Required sName - Required tPost - Required sEmail sURL fEmailUpdate sIP sOS sBrowser
Simple Example: curl -F"xForumId=1" -F"sTopic=Help with things" -F"tPost=Initial post" -F"sName=Bob Jones" http://.../api/index.php?method=forums.createTopic
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <topic> <xTopicId>44</xTopicId> </topic>

forums.createPost
Create a new forum post in the topic specified.
URL:	/api/index.php?method=forums.createPost
HTTP Action:	POST
Parameters:
xTopicId - Required sName - Required tPost - Required sEmail sURL fEmailUpdate sIP sOS sBrowser
Simple Example: curl -F"xTopicId=43" -F"tPost=Reply to a post" -F"sName=Bob Jones" http://.../api/index.php?method=forums.createPost
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <post> <xPostId>174</xPostId> </post>

forums.search
Return a list of topics that match the search string.
URL:	/api/index.php?method=forums.search
HTTP Action:	GET
Parameters:
q - Required
Simple Example: curl "http://.../api/index.php?method=forums.search&q=installation"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <topics> <topic> <link>?pg=forums.posts&id=22</link> <desc>It would be great if the forums included a profile page.</desc> <sTopic>suggestion for forums</sTopic> <xTopicId>22</xTopicId> <sForumName>Product Beta</sForumName> <xForumId>1</xForumId> <dtGMTPosted>1127936511</dtGMTPosted> </topic> <topic> <link>?pg=forums.posts&id=13</link> <desc>The installer has been updated to 3.4, please download and try it.</desc> <sTopic>Update to the installer</sTopic> <xTopicId>13</xTopicId> <sForumName>Product Beta</sForumName> <xForumId>1</xForumId> <dtGMTPosted>1126815203</dtGMTPosted> </topic> </topics>

kb.list
Returns a list of all the public knowledge books
URL:	/api/index.php?method=kb.list
HTTP Action:	GET
Parameters:	none
Simple Example: curl http://.../api/index.php?method=kb.list
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <books> <book> <xBook>1</xBook> <sBookName>HelpSpot Manual</sBookName> <iOrder>0</iOrder> <tDescription>Everything you need to install, administer, and use HelpSpot.</tDescription> </book> </books>

kb.get
Return information on a knowledge book.
URL:	/api/index.php?method=kb.get
HTTP Action:	GET
Parameters:
xBook - Required
Simple Example: curl "http://.../api/index.php?method=kb.get&xBook=1"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <book> <xBook>1</xBook> <sBookName>Product Manual</sBookName> <iOrder>0</iOrder> <tDescription>Everything you need to install, administer, and use our product.</tDescription> </book>

kb.getBookTOC
Return a knowledge books table of contents. Can optionally include the full HTML of each page of the book.
URL:	/api/index.php?method=kb.getBookTOC
HTTP Action:	GET
Parameters:
xBook - Required fWithPageHTML (Optionally return the full HTML of each page)
Simple Example: curl "http://.../api/index.php?method=kb.getBookTOC&xBook=1"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <toc> <chapter> <name>1. Getting Started</name> <xChapter>2</xChapter> <sChapterName>Getting Started</sChapterName> <iOrder>1</iOrder> <fAppendix>0</fAppendix> <pages> <page> <name>1.1. Getting your help desk up and running</name> <xPage>5</xPage> <xChapter>2</xChapter> <sPageName>Getting your help desk up and running</sPageName> <iOrder>1</iOrder> <fHighlight>1</fHighlight> </page> </pages> </chapter> <chapter> <name>2. Installation</name> <xChapter>3</xChapter> <sChapterName>Installation</sChapterName> <iOrder>2</iOrder> <fAppendix>0</fAppendix> <pages> <page> <name>2.1. Requirements</name> <xPage>2</xPage> <xChapter>3</xChapter> <sPageName>Requirements</sPageName> <iOrder>1</iOrder> <fHighlight>0</fHighlight> <relatedpages> <relatedpage> <xRelatedPage>215</xRelatedPage> <sPageName>User Configuration</sPageName> <sChapterName>Setup</sChapterName> <sBookName>Admin Manual</sBookName> <xBook>1</xBook> </relatedpage> <relatedpage> <xRelatedPage>102</xRelatedPage> <sPageName>Installing on SQL Server</sPageName> <sChapterName>Installation</sChapterName> <sBookName>Admin Manual</sBookName> <xBook>1</xBook> </relatedpage> </relatedpages> </page> <page> <name>2.2. Installing the Product</name> <xPage>3</xPage> <xChapter>3</xChapter> <sPageName>Installing the Product</sPageName> <iOrder>3</iOrder> <fHighlight>1</fHighlight> </page> <page> <name>2.3. Creating the Microsoft SQL Server Full Text Index</name> <xPage>4</xPage> <xChapter>3</xChapter> <sPageName>Creating the Microsoft SQL Server Full Text Index</sPageName> <iOrder>4</iOrder> <fHighlight>0</fHighlight> </page> <page> <name>2.4. Upgrading</name> <xPage>14</xPage> <xChapter>3</xChapter> <sPageName>Upgrading</sPageName> <iOrder>5</iOrder> <fHighlight>1</fHighlight> </page> <page> <name>2.5. Clean Upgrade</name> <xPage>16</xPage> <xChapter>3</xChapter> <sPageName>Clean Upgrade</sPageName> <iOrder>6</iOrder> <fHighlight>0</fHighlight> </page> </pages> </chapter> </toc>

kb.getPage
Return information on a knowledge book page.
URL:	/api/index.php?method=kb.getPage
HTTP Action:	GET
Parameters:
xPage - Required
Simple Example: curl "http://.../api/index.php?method=kb.getPage&xPage=16"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <page> <name>2.5. Clean Upgrade</name> <xPage>16</xPage> <xChapter>3</xChapter> <sPageName>Clean Upgrade</sPageName> <tPage><p>This is the HTML body of the page.</p></tPage> <iOrder>6</iOrder> <fHighlight>0</fHighlight> <relatedpages> <relatedpage> <xRelatedPage>215</xRelatedPage> <sPageName>User Configuration</sPageName> <sChapterName>Setup</sChapterName> <sBookName>Admin Manual</sBookName> <xBook>1</xBook> </relatedpage> <relatedpage> <xRelatedPage>102</xRelatedPage> <sPageName>Installing on SQL Server</sPageName> <sChapterName>Installation</sChapterName> <sBookName>Admin Manual</sBookName> <xBook>1</xBook> </relatedpage> </relatedpages> </page>

kb.search
Return a list of pages that match the search string.
URL:	/api/index.php?method=kb.search
HTTP Action:	GET
Parameters:
q - Required
Simple Example: curl "http://.../api/index.php?method=kb.search&q=installation"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <pages> <page> <link>?pg=kb.page&id=16</link> <desc>Page about installation</desc> <sBookName>Product Manual</sBookName> <sPageName>Installing the product</sPageName> <xPage>16</xPage> </page> <page> <link>?pg=kb.page&id=8</link> <desc>How to install on Linux</desc> <sBookName>Product Manual</sBookName> <sPageName>Installing on Linux</sPageName> <xPage>8</xPage> </page> </pages>

kb.voteHelpful
Adds a vote for this page as "helpful"
Available as of HelpSpot version: 2.4.2
URL:	/api/index.php?method=kb.voteHelpful
HTTP Action:	GET
Parameters:
xPage - Required
Simple Example: curl "http://.../api/index.php?method=kb.voteHelpful&xPage=125"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <page> <iHelpful /> </page>

kb.voteNotHelpful
Adds a vote for this page as "not helpful"
Available as of HelpSpot version: 2.4.2
URL:	/api/index.php?method=kb.voteNotHelpful
HTTP Action:	GET
Parameters:
xPage - Required
Simple Example: curl "http://.../api/index.php?method=kb.voteNotHelpful&xPage=125"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <page> <iNotHelpful /> </page>

util.getFieldLabels
Returns a list of field labels for use in your interfaces.
URL:	/api/index.php?method=util.getFieldLabels
HTTP Action:	GET
Parameters:	none
Simple Example: curl http://.../api/index.php?method=util.getFieldLabels
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>

4.5. Private Methods

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

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

Methods:

private.customer.getPasswordByEmail
Retrieve the portal password for an email or create a portal password for an email if that email doesn't have a password yet.
URL:	/api/index.php?method=private.customer.getPasswordByEmail
HTTP Action:	GET
Parameters:
sEmail - Required sPassword
Other notes:	This method will always return a password for an email account. If HelpSpot has never seen the email address before it will generate a password for the email address and store it, otherwise it will return the password already set for the email address.
Other notes:	If a password is provided and the email address is unknown to HelpSpot that password will be used for the email address. In this way you can use the function to create email/password logins for customers ahead of time.
Simple Example: curl -u tim@ex.com:mypassword "http://.../api/index.php?method=private.customer.getPasswordByEmail&sEmail=tsmith@companyco.com"
Sample Response: <?xml version="1.0" encoding="iso-8859-1"?> <results> <sPassword>nusoxdln</sPassword> </results>

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 fTrash sUserId sFirstName sLastName sEmail sPhone fUrgent fOpenedVia 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 Custom# (# is the custom field ID)
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 fNoteType (0 private (default), 1 public, 2 external) sTitle (Used as email subject) reportingTags (Comma separated list of each xReportingTag ID) fOpen xStatus fTrash 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 Custom# (# is the custom field ID)
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> <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.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)
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)
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> <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.filter.get
Return the results of a users filter.
URL:	/api/index.php?method=private.filter.get
HTTP Action:	GET
Parameters:
xFilter - Required 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 note 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.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> <b>Henry Yount</b><br /> 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> <b>Henry Yount</b><br /> 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>

4.6. API Implementations in PHP, Cocoa, Ruby, Python

PHP
Created By:	Joe Landsman for UserScape, Inc
Features:	Support for all API calls, both public and private. Built in caching system to cache common requests. Automatic conversion of XML response into PHP array's.
Documentation:	Yes, within the downloaded file itself
Supported by UserScape:	Yes
Requirements:	PHP cURL Module
Download:	http://www.helpspot.com/downloads/api/php.zip

Cocoa / Objective-C
Created By:	http://www.audiofile-engineering.com/
Supported by UserScape:	No
Download:	http://www.helpspot.com/downloads/api/cocoa.zip

Ruby / Merb
Created By:	jbrw
Supported by UserScape:	No
Download:	http://github.com/jbrw/help_spot/tree/master

Python
Created By:	John Speno, Purplestork
Supported by UserScape:	No
Download:	http://github.com/JohnSpeno/python-helpspot/tree

4.7. Sample Implementation: Apple iPhone Interface

Note: This download is no longer required, HelpSpot includes a dedicated iPhone UI as of version 2.6.0. This page remains in the manual as a reference for using javascript to interact with the Web Service API.

The files linked below allow you to add a special interface for using an Apple iPhone with HelpSpot in a user interface specifically designed for the Apple iPhone. These files use HelpSpot's web services API to create the interface and are also useful as an example implementation of the HelpSpot web service API.

Screenshots

Full Size	Full Size	Full Size
Full Size	Full Size	Full Size

Features

Access to the Inbox, My Queue, and all filters
Unread/replied status in My Queue
Complete request history and common request details
Ability to perform a public update to a request and change categories and assignment
Access to all public forums
Ability to post to public forums
Access to all public knowledge books

Installation

Note, HelpSpot 2.1.1 or higher required.

Download the files below
Create a folder in the root HelpSpot folder (where config.php is located). This folder can be named anything you like. show example
Upload the files into the folder
In "Admin->Settings->Web Services API" enable the public and private API's
Visit the folder in your iPhone and login

About Request Updates

The iPhone interface currently only allows for public updates to requests, category assignemnt, and staff assignment. This is primarily to keep the forms simple. This could be expanded an may be in a future release. If you do need to access more request details there's a link to the full HelpSpot UI at the bottom of the update form. This will work in mobile Safari.

Potential Problems

Installations that have required custom fields will not be able to answer new requests as there's no way to set those fields.

iUi Library

The HelpSpot iPhone interface makes use of the wonderful iUi iPhone library by Joe Hewitt.

4.8. Sample Implementation: NetVibes Widget

This simple widget allows you to see your My Queue from the NetVibes homepage. It implements the private API and uses JSON to communicate with NetVibes. Download the file at the bottom of the page.

How to install the widget

Make sure the private API is enabled in Admin->Settings
Download the file and upload it to your web server in a public directory
Go to www.netvibes.com
In the left navigation of NetVibes select the Widgets tab
Select "external widgets"
Select "UWA Module"
In the box that opens click "edit" enter the URL to the file you uploaded to your server, click OK.
Click the "add to my page" link
Once the widget is added, click the "edit" box and enter your username, password, and URL to your HelpSpot installation.

5. Email Parser API

5.1. Email Parser: Using Email as a Service

HelpSpots email parser allows you to use the built in email integration as a basic web service. If you need to create requests in remote systems you can add a few basic tags to an email you generate for accurate importing into HelpSpot. Every email sent to HelpSpot is automatically sent through the email parser so your remote system can email requests with tags to the same accounts you already use for support.

The following tags are available for use within email bodies. Replace XXXXXX with your data. All tags are automatically stripped after being parsed so only the email body will remain as the request.

Tag	Description
##hs_customer_id:XXXXXX##	The customers ID.
##hs_customer_firstname:XXXXXX##	The customers first name.
##hs_customer_lastname:XXXXXX##	The customers last name.
##hs_customer_phone:XXXXXX##	The customers phone number.
##hs_customer_email:XXXXXX##	The customers email address.

Example:

Here's an example of an email generated with customer tags. This type of email could be generated from a remote service, desktop application, or intranet.

Hello,

I'm having trouble logging into the time reporting system. Yesterday I was 
able to enter the system via the link on the intranet, but today when I click 
that link all I see is the login screen. 

Tim

//Note: You would programatically append the tags below//

##hs_customer_id:589GK42##
##hs_customer_firstname:Timothy##
##hs_customer_lastname:Ryan##
##hs_customer_phone:(845) 765-4321##
##hs_customer_email:t.ryan@mycompany.com##

The email above when sent to a HelpSpot integrated account will be transformed to:

There are also advanced tags available to submit category and custom field information.

5.2. Email Parser: Advanced Tags

Beyond the basic customer parser tags, HelpSpot also supports passing in categories and custom field data via the email parser. In order to use these more advanced tags you’ll need to know the category ID’s and custom field ID’s in your installation. You can find these in each ID’s respective area of the admin.

Commands:

Tag	Description
##forward:true##	Treat the email as a forward. HelpSpot will attempt to determine the original senders email address (not the person forwarding the email) and use that as the HelpSpot customer information instead of the forwarding users information as would normally be the case. (Note: this tag may also be used in the email subject line)

Category Tag:

Category ID’s are displayed in the left most column on the category management page:
Admin->Categories

Tag	Description
##hs_category:XX##	The category ID should be passed in this tag. It must be numeric and it must be a valid active category.

Assignment Tag:

Staff ID's are displayed in the left most column on the staff management page:
Admin->Staff

Tag	Description
##hs_assigned_to:XX##	The staff member ID should be passed in this tag. It must be numeric and it must be a valid active staff member.

Custom Field Tags:

Custom field ID’s are displayed in the left most column on the custom field page:
Admin->Tools->Custom Request Fields

Tag	Description
##hs_customX:XXXXXX##	In the left part of the tag you must place the custom field ID for the information you’re passing. In the right part of the tag after the colon pass the data. Data must be appropriate for the field type as specified below.

Table of appropriate values for each type of custom field. Note that improperly passed data or data of the wrong type will default the custom field to empty.

Custom Field Type	Value Accepted
Predefined List	Any one of the values in the list. The value must be exactly as it appears on the drop down including spacing.
Text Field	Up to 255 characters of data. Should not include line breaks.
Large Text Field	Large blocks of text data. This may include line breaks.
Checkbox	The number 1 if the checkbox should be checked, a 0 if not checked.
Numeric Field	An integer value.

Complete Example:

Here’s an example of an email generated with customer tags as well as category and custom field tags. This type of email could be generated from a remote service, desktop application, or intranet.

Hello,

I'm having trouble logging into the time reporting system. Yesterday I was 
able to enter the system via the link on the intranet, but today when I click 
that link all I see is the login screen. 

Tim

//Note: You would programatically append the tags below//

##hs_category:6##
##hs_assigned_to:4##

##hs_custom1:Time Reporting##
##hs_custom2:Accounting Department##
##hs_custom3:1##

##hs_customer_id:589GK42##
##hs_customer_firstname:Timothy##
##hs_customer_lastname:Ryan##
##hs_customer_phone:(845) 765-4321##
##hs_customer_email:t.ryan@mycompany.com##

Appendix

1. API Field Definitions

accesskey	The request ID and random characters string that together allow access to a request from the portal. The access key is also used in the API to make request lookups via the public interface.
acting_person_xperson	The ID of the person logged in and acting within HelpSpot causing the action to occur.
acting_person_fusertype	The user type of the person logged in and acting within HelpSpot causing the action to occur. 1 - Admin 2 - Help Desk Staff 3 - Level 2 4 - Guest
acting_person_fname	The first name of the person logged in and acting within HelpSpot causing the action to occur.
acting_person_lname	The last name of the person logged in and acting within HelpSpot causing the action to occur.
acting_person_email	The email of the person logged in and acting within HelpSpot causing the action to occur.
afterDate	A unix timestamp (timezone adjusted) of the date/time to search after based on open date.
anyall	When searching this specifies if you're doing an AND or an OR type search. The default is "all".
assigned_person_fname	The assigned users first name
assigned_person_lname	The assigned users last name
assigned_person_email	The assigned users email
beforeDate	A unix timestamp (timezone adjusted) of the date/time to search before based on open date.
closedBeforeDate	A unix timestamp (timezone adjusted) of the date/time to search before based on closing date.
closedAfterDate	A unix timestamp (timezone adjusted) of the date/time to search after based on closing date.
Custom#	A custom field value. See the custom field section for more details.
dtGMTDateAdded	A unix timestamp (timezone adjusted) of the date/time the event was added. Defaults to the current date/time.
email_from	The xMailbox ID of the mailbox to send emails from for this request or request update.
email_cc	Comma separated list of emails to CC on a request note. EX: tim@domain.com,bill@example.com
email_bcc	Comma separated list of emails to BCC on a request note. EX: tim@domain.com,bill@example.com
email_to	External notes only. Comma separated list of emails to send the note to. EX: tim@domain.com,bill@example.com
email_staff	Comma separated list of staff ID's (this is the staffers xPerson value) to notify on the note. EX 4,8,14
fEmailUpdate	1 if the forum poster is subscribing via email to the topic, 0 otherwise.
fOpen	1 if the request is open, 0 otherwise.
File#_sFilename	A file name for the uploading file. See the file upload section for more details.
File#_sFileMimeType	The mime type of the uploading file. EX: text/text or text/html. See the file upload section for more details.
File#_bFileBody	The base 64 encoded body of the uploading file. See the file upload section for more details.
fNoteIsHTML	If the note contains HTML or plain text. Defaults to the on/off values of Admin->Settings->HTML Emails. 0 - Plain text 1 - HTML
fNoteType	The type of note being posted via the API. 0 - A private note. Will not be emailed to customer or available via the portal. 1 - A public note. Emailed to customer, available in portal. 2 - An external note. Emailed to specified email addresses. Not available to customer.
fOpenedVia	The ID of the method in which the request was opened. Valid values are: 1 - Email 2 - Phone 3 - Walk In 4 - Mail 5 - Other 6 - Web Service 7 - Web Form 8 - Forum 9 - Instant Messenger 10 - Fax 11 - Voicemail 12 - Staff Initiated 13 - Tab Widget
fRawValues	This is a special flag. By default in the API most method calls will automatically translate dates, xPerson values, xCategory values, xStatus values and other reference ID's into their true values. This greatly reduces the number API calls which are required to display the results of a method. However, in some circumstances you may actual want the raw reference numbers. In this case you should set this value to 1 and the raw data will be returned.
fTrash	1 if the request is in the trash, 0 otherwise.
fUrgent	1 if the request is urgent, 0 otherwise.
iDay	The day of the month a time event occured. (1-31)
iMonth	The month of the year a time event occured. (1-12)
iYear	The year a time event occured.
length	Number of results to return in a result set.
q	A search query string.
relativedate	Searches for requests in the time period relative to the current time based on open date. today - Today's date yesterday - Yesterday's date past_7 - The past 7 days past_14 - The past 14 days past_30 - The past 30 days past_90 - The past 90 days past_365 - The past 365 days this_week - The current week this_month - The current month this_year - The current year last_week - The previous week last_month - The previous month last_year - The previous year
reportingTags	A comma separated list of reporting tag ID's (xReportingTag). Normally these are retrieved with the private.request.getCategories API call. Each categories reporting tags are included along with their ID's.
sBrowser	The browser of the forum poster.
sEmail	The customers email address.
sFirstName	The customers first name.
sIP	The IP of the forum poster.
sLastName	The customers last name.
sName	The name provided by a forum poster.
sOS	The operating system of the forum poster.
sPhone	The customers phone number.
sSearch	When searching a request this is a full text search string that will be used to search against all the request history notes.
start	Result sets should start from this row, defaults to 0. Use this to paginate results in methods which support it.
sTitle	In a request this is the original email subject. If submitting a request update this field holds the value of the subject line you intend to use in the email. If not provided the standard default will be used.
sTopic	The name of a forum topic.
sURL	The URL provided by a forum poster.
sUserId	The customers ID. This is not a HelpSpot ID, but rather is your companies ID for the customer. The value is a string and may contain letters along with numbers.
tDescription	The description of a time event.
tNote	The text of a request history item. Usually the body of an email or a post from the web form. You'll usually need to check the fNoteIsHTML value to see if the note is HTML or plain text.
tPost	The text of a forum post.
tTime	The lenght of time to be registered as a time event. 2 formats are supported. Hours and minutes (hh:mm, ex 2 hours 15 minutes would be 2:15) and decimal hours (2.5 hours).
xBook	The ID of a knowledge book.
xCategory	The ID of a category.
xFilter	The ID of a users filter.
xForumId	The ID of a forum.
xPage	The ID of a knowledge book page.
xPerson	The ID of a staff member.
xPersonAssignedTo	The ID of the staff member the request is assigned to.
xPersonOpenedBy	The ID of the staff member who opened the request. Use 0 to set the customer as the person opening the request.
xRequest	The ID of a request.
xStatus	The ID of a status.
xTimeId	The ID of a time event.
xTopicId	The ID of a forum topic.

Custom Fields

Throughout the system custom fields are referenced by Custom# where the # is the ID of the custom field. So to reference custom field 5 you would use Custom5.

When setting custom field values through the API some field types have special requirements. A description of these fields is below.

Predefined List	Values you set should be a valid part of the list.
Drill Down List	Drill down values must be returned in a special serialized format. Each level of the drill down is separate by #-#. So for a 2 level drill down the value to set would look like this: Boston#-#8st
Date Fields	Should be a Unix Timestamp of the date.
Date/Time Fields	Should be a Unix Timestamp of the date/time.
Regular Expression Field	Your API client should check for regex correctness. The regex is stored and checked in Javascript.
AJAX Selection Field	Your API client should check for a valid value based on what your ajax field would normally supply.
Checkbox	1 for checked, 0 for not.

File Uploads

The methods which accept file uploads all work in the same fashion. Up to 9 files may be uploaded at a time with each request. Each file should be numbered 1-9 and the fields created with appropriate names. For example these would be the valid field names for 2 files being uploaded:

File1_sFilename
File1_sFileMimeType
File1_bFileBody

File2_sFilename
File2_sFileMimeType
File2_bFileBody

Also note that the bFileBody value should be base64 encoded and that sFileMimeType should be a valid mime type so that the file is served correctly.

Support & Docs Powered by HelpSpot

API Manual

1. Live Lookup

1.1. Live Lookup Overview

Basic Workflow

Live Lookup in Action

1.2. Configuration and Implementation

Steps to Set up

XML Specification

1.3. Configuration for Global Address Book

Live Lookup Address Book Tags

1.4. Sample Implementation: Salesforce.com

Integrate your Help Desk with SalesForce.com

Who can use it?

Installation

1.5. Sample Implementation: Active Directory via Linked SQL Server

Configuration

1.6. Sample Implementation: 37Signals Highrise

Requirements

Installation

1.7. Sample Implementation: Address Book

Installation

2. Request Push API

2.1. Overview

2.2. Request Push Implementation Guide

Creating the Push File

Rename the Class

Writing the Push Method

Request Data Format

Return Unique ID

Error Handling

Writing the Details Method

2.3. Sample Implementation: FogBugz

Screenshots:

Requirements:

Installation Instructions

2.4. Sample Implementation: 37 Signals Highrise

Screenshots:

Requirements:

Installation Instructions

2.5. Sample Implementation: 37 Signals Campfire

Screenshots

Requirements:

Installation Instructions

2.6. Sample Implementation: ActiveCollab

Requirements:

Installation Instructions

3. AJAX Selection Field

3.1. Overview

3.2. AJAX Selection Field Implementation Guide

AJAX Selection Field XML Specification

4. Web Service API

4.1. Web Service API Overview

API Design

Public/Private Interfaces

Public Interface

Private Interface

4.2. API Basics: URL, Methods, Return Formats, Authentication

How to Enable the API

API URL

Public vs Private

Return Format

Private API Authentication

Character Set

Version Information

Errors

The Easiest Way to Try the API

4.3. API Error Codes

4.4. Public Methods

Methods:

customer.getRequests

request.create

request.update

request.getCategories

request.getCustomFields

request.get

forums.list

forums.get

forums.getTopics

forums.getPosts

Support & Docs
Powered by HelpSpot