Home → API Manual → Appendix → API Field Definitions

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
fBillable 1 if the time event should be tracked as billable, 0 otherwise.
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.
sFilterView The type of notes to return for a filter stream.
  • stream - Staff created public notes to customers
  • stream-priv - Staff created public and private notes
  • stream-cust - Customer notes
  • stream-cust-staff - Staff and customer public notes
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.
xPortal The ID of a secondary portal to associate the request with
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. If you do reference a custom field when creating or updating a request and do not provide a value you will receive an error: "Required parameter Custom# not supplied".

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.

Skipping Custom Field Checks

When creating a request or updating it using the private api you may want to skip the custom field requirement checks for certain operations. This is possible by setting the api variable skipCustomChecks to 1.

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.

Knowledge Tags
API  /  API Fields  / 

This page was: Helpful | Not Helpful