Home →
API Manual →
Web Service API →
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>
|