Home →
API Manual →
Web Service API →
Public Methods
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
xPortal
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:
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>Web Service</fOpenedVia>
<xOpenedViaId>0</xOpenedViaId>
<xPersonOpenedBy />
<xPersonAssignedTo>Ian Landsman</xPersonAssignedTo>
<fOpen>1</fOpen>
<xStatus>Active</xStatus>
<fUrgent>0</fUrgent>
<xCategory>Bugs</xCategory>
<dtGMTOpened>September 24, 2007</dtGMTOpened>
<dtGMTClosed />
<sRequestPassword>itetxb</sRequestPassword>
<sTitle />
<sUserId>12345</sUserId>
<sFirstName />
<sLastName />
<sEmail />
<sPhone />
<iLastReplyBy>Ian Landsman</iLastReplyBy>
<fTrash>0</fTrash>
<dtGMTTrashed />
<fullname> </fullname>
<reportingTags>
<tag>
<xReportingTag>2</xReportingTag>
<sReportingTag>Printer</sReportingTag>
</tag>
<tag>
<xReportingTag>3</xReportingTag>
<sReportingTag>Software</sReportingTag>
</tag>
</reportingTags>
<request_history>
<item>
<xRequestHistory>1378</xRequestHistory>
<xRequest>12745</xRequest>
<xPerson>Ian Landsman</xPerson>
<dtGMTChange>Tue, September 25, 2007, 11:00 AM</dtGMTChange>
<fPublic>1</fPublic>
<fInitial>0</fInitial>
<tLog />
<tNote><p>An HTML note example</p></tNote>
<tEmailHeaders />
<fNoteIsHTML>1</fNoteIsHTML>
<fMergedFromRequest>0</fMergedFromRequest>
<files>
<file>
<sFileMimeType>application/pdf</sFileMimeType>
<sFilename>Invoice.pdf</sFilename>
<xDocumentId>60</xDocumentId>
<public_url>http://www.domain.com/index.php?pg=file&from=3&id=60&reqid=12745&reqhisid=1378</public_url>
<private_url>http://www.domain.com/admin.php?pg=file&from=0&id=60&showfullsize=1&download=1</private_url>
</file>
</files>
</item>
<item>
<xRequestHistory>1377</xRequestHistory>
<xRequest>12745</xRequest>
<xPerson>Ian Landsman</xPerson>
<dtGMTChange>Tue, September 25, 2007, 11:00 AM</dtGMTChange>
<fPublic>0</fPublic>
<fInitial>0</fInitial>
<tLog>Category changed from "" to "Bugs"</tLog>
<tNote />
<tEmailHeaders />
<fNoteIsHTML>0</fNoteIsHTML>
<fMergedFromRequest>0</fMergedFromRequest>
</item>
<item>
<xRequestHistory>1376</xRequestHistory>
<xRequest>12745</xRequest>
<xPerson> </xPerson>
<dtGMTChange>Mon, September 24, 2007, 08:03 PM</dtGMTChange>
<fPublic>1</fPublic>
<fInitial>0</fInitial>
<tLog />
<tNote>Plain text update to the request.</tNote>
<tEmailHeaders />
<fNoteIsHTML>0</fNoteIsHTML>
<fMergedFromRequest>0</fMergedFromRequest>
<files />
</item>
<item>
<xRequestHistory>1375</xRequestHistory>
<xRequest>12745</xRequest>
<xPerson> </xPerson>
<dtGMTChange>Mon, September 24, 2007, 07:44 PM</dtGMTChange>
<fPublic>1</fPublic>
<fInitial>1</fInitial>
<tLog />
<tNote>This is the request.</tNote>
<tEmailHeaders />
<fNoteIsHTML>0</fNoteIsHTML>
<fMergedFromRequest>0</fMergedFromRequest>
<files />
</item>
</request_history>
</request>
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:
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:
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:
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:
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>
<tags>
<tag>Pricing</tag>
<tag>Pre-sales</tag>
<tag>Application</tag>
<tag>Service</tag>
</tags>
</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>
<tags>
<tag>Pricing</tag>
<tag>Pre-sales</tag>
<tag>Application</tag>
<tag>Service</tag>
</tags>
<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>
<tags>
<tag>Pricing</tag>
</tags>
</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:
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>
<tags>
<tag>Pricing</tag>
<tag>Pre-sales</tag>
<tag>Application</tag>
<tag>Service</tag>
</tags>
<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:
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:
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:
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>
Knowledge Tags
Related Pages