Parature, Inc
updated Sep 21, 2015

API Specification Guide

Clients who want to automate interaction with the Parature data by third-party systems can use a simple HTTP-based API. With the API, data can be added, updated, deleted and retrieved for the following object types:

  • Account
  • Asset
  • Chat
  • CSR
  • Customer
  • Download File
  • Knowledgebase Article
  • Product
  • Ticket

The API also supports performing workflow actions on Ticket and Asset objects.

The API adheres to REST principles. See the following references for general information on REST-based APIs.

Terminology

Object Type
A unique business entity type, such as Customer, Ticket, Knowledgebase Article, etc. These correlate with Parature Modules. The object type has a name and a set of fields that hold values pertinent to the type. For example, a 'Ticket' type contains the fields such as 'Assigned To' and 'Date Created'. All object types define a field called 'ID' that holds a value uniquely identifying a specific object of that type.
Object
A single data record of a particular object type. All objects of a given type share the same set of fields, but each object has field values that are independent of other objects. Every object has an 'ID' field value that is different from every other object of the same type.
Object Location
A URI that references the details of a particular object.
Field
A data item that has a name and a value. A field is defined as part of an object type and present on every object instance of the object type. The field value type could be a string, a date, a number, an option selected from a list, a Boolean, or the ID of an object.
Operation
A request that moves object data in and out of the Parature system. The Parature API supports six types of Operations:
  • Schema
  • List
  • Retrieve
  • Create
  • Update
  • Delete
Action
An additional object transition that can take place when an object is updated or created. For example, assigning a Ticket to a CSR.

Throttle Limits

The APIs are throttled to levels which will prevent performance degradation of your Service Desk and Portal. It is advisable to include the ability to throttle your own code in order to prevent triggering strict throttling rules. If a request is denied due to throttling, the system returns an HTTP 503 error.

The throttling rate at which requests are being made is tracked regardlesss of the API request used. If the rate exceeds 2 requests per second (120/minute) over a period of 2 minutes, the client is placed in 'throttled mode'. Once in 'throttled mode', the client's request rate is reduced to 1 request every 2 seconds (30/minute). The client will remain in 'throttled mode' for 120 seconds (2 minutes) at which time they are returned to normal throttling restrictions.

Error Codes

Success

200
OK
201
Created
Object was Created or Updated.
204
No Content
Object was Deleted.

Failure

400
Bad Request
401
Unauthorized
The supplied token is invalid for one of the following reasons:
  • Token is invalid.
  • Token is expired.
  • Account or Department IDs in the URI request are not valid for the supplied token.
403
Forbidden
The supplied token does not have permissions to perform that operation.
404
Not Found
An object with the object id does not exist.
500
Internal Server Error
An unrecoverable error occurred within the system.
502
Bad Gateway
The system is currently unavailable due to maintenance.
503
Service Unavailable
The system is temporarily unavailable due to throttling restrictions.

Best Practice

Development on Sandbox

For development and testing, use the API against your Sandbox data. Your Sandbox Environment contains a copy of your production configuration and data, allowing you to code against your schema and data without permanently altering your production data.

To access the Sandbox via the API, use your Service Desk hostname and append -sandbox to the subdomain.

Please visit the About Parature Sandbox article to find out more about your Sandbox Environment and how to access it.

Schema Changes

The schema operation returns a "live" schema/object. This schema will change each time you add, delete or modify a custom field within Parature. For integrations that must automatically adjust to changes in the schema, the integration should read the schema prior to each run and check for differences from the previous version to determine if there have been any changes.

Relative Date Queries

A specific date range can be specified as search criteria by using _min and _max field modifiers. However using these field modifiers to perform relative date queries places the burden of dynamically calculating date criteria on the API client. Instead, use Date_Created or Date_Updated along with any of the following relative date keywords:
Keywords
_today_ 12:00:00.000am to 11:59:59.999pm on the date the operation is performed
_yesterday_ 12:00:00.000am to 11:59:59.999pm on the date before the operation is performed
_tomorrow_ 12:00:00.000am to 11:59:59.999pm on the date after the operation is performed
_last_n_days_ 12:00:00.000am n days preceding the day operation is performed through 11:59:59.999pm on the day the operation is performed
_next_n_days_ 12:00:00.000am on the day the operation is performed through 11:59:59.999pm n days following the day the operation is performed
_this_week_ 12:00:00.000am the Sunday immediately prior to the day on which the operation is performed through 11:59:59.999pm on the Saturday immediately following the day on which the operation is performed
_last_week_ 12:00:00.000am the next to last Sunday prior to the day on which the operation is performed through 11:59:59.999pm on the Saturday immediately preceding the day on which the operation is performed
_next_week_ 12:00:00.000am the next to last Sunday following the day on which the operation is performed through 11:59:59.999pm on the Saturday immediately following the day on which the operation is performed
_this_month_ 12:00:00.000am on the first day of the month through 11:59:59.000pm on the last day of the month in which the operation is performed
_last_month_ 12:00:00.000am on the first day of the month through 11:59:59.999pm on the last day of the month immediately prior to the month in which the operation is performed
_next_month_ 12:00:00.000am on the first day of the month through 11:59:59.999pm on the last day of the month immediately following to the month in which the operation is performed
_last_n_months_ 12:00:00.000am on the first day of the month n months preceding the month in which the operation is performed through 11:59:59.999pm on the last day of the month immediately preceding the month in which the operation is performed
_next_n_months_ 12:00:00.000am on the first day of the month immediately following the month in which the oepration is performed through 11:59:59.000pm on the last day of the month n months following the month in which the operation is performed
_this_year_ 12:00:00.000am on the first day of the year through 11:59:59.999pm on the last day of the year in which the operation is performed
_last_year_ 12:00:00.000am on the first day of the year through 11:59:59.999 on the last day of the year immediately prior to the year in which the operation is performed
_next_year_ 12:00:00.000am on the first day of the year through 11:59:59.999pm on the last day of the year immediately following to the year in which the operation is performed

UTC is the default timezone reference for relative queries. To specify a different timezone as the reference, indicate the number of hours to add or subtract from UTC in the following format:

_keyword_UTC_plus_n_
_keyword_UTC_minus_n_

Integrations and Parature Maintenance Windows

The Parature system is periodically taken offline for maintenance procedures. During these procedures, you should stop your integration from running. If you cannot stop it, e.g. it is embedded inside a larger site or application, you'll need to make sure the integration recognizes and reacts to maintenance windows. When the Parature system is offline for maintenance, all API class will be returned with a 502 HTTP code. See API XML Return Codes for a list of all return codes.

Code Samples

Please note that these code samples are not officially maintained or supported by Parature. These code samples have been reviewed by our developers, but has not been extensively tested against multiple environments or scenarios. Parature always recommends testing any API integration thoroughly in the sandbox environment before deploying against the production system.

C#

Knowledgebase Find and Replace Element

This sample will search Articles for the occurrence of a string, and replace all occurrences of that string with the replacement string.

Java

Download Create (with file upload)

This sample shows the process of creating and updating a Download object.

PHP

Customer Create and Update

This sample demonstrates creating an Account, creating a Customer, and assigning that Customer to the Account.

Ruby

Ticket Create and Update Including Workflow

This sample shows the creation, then update of a Ticket. The sample Ticket contains at least one of each field type, to show how custom fields are accessed.

SDK

Parature from Microsoft provides a C# SDK for the API that may be used under the permissive MIT license. The source code is public on GitHub and binaries are periodically pushed to NuGet, and includes both an SDK and an example usage project. This SDK is provided as-is, without warranty and in active development, so the exact functionality and behaviors are subject to change. This is not a formally supported SDK. Any and all questions should be posted to the GitHub Issue Tracker, and all questions through standard support channels will defer to this location.

Knowledgebase Article

GET /Article

Description
Lists all Articles that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Article
Method
GET
Request Body
None
Parameters
Answer Returns all Articles whose answer matches the given strings.
Answer_like_ Returns all Articles whose answer contains the given strings.
Created_By_id_ Returns all Articles created by the given CSRs.

See CSRs for a list of available values.
Date_Created Returns all Articles created on the given dates. The specified date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

Also see Relative Date Queries.
Date_Created_min_ Returns all Articles created the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all Articles created on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Updated Returns all Articles updated on the given dates.

Also see Relative Date Queries.
Date_Updated_min_ Returns all Articles updated on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Updated_max_ Returns all Articles updated on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Expiration_Date Returns all Articles with an expiration on the given dates.

Also see Relative Date Queries.
Expiration_Date_min_ Returns all Articles with an expiration on or after the given dates.

See Date_Created for valid formats.
Expiration_Date_max_ Returns all Articles with an expiration on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Folders_id_ Returns only Articles to the given Folders and their subfolders.

See Article Folders for a list of available values.
Language Returns all Articles with the given language.
Modified_By_id_ Returns all Articles last updated by the given CSRs.

See CSRs for a list of available values.
Permissions_id_ Returns all Articles with the given SLAs.

See SLAs for a list of available values.
Products_id_ Returns all Articles associated with the given Products.

See Products for a list of available values.
Published
false Returns all Articles in the Draft status.
true Returns all Articles in the Published status.
Question Returns all Articles whose question matches the given strings.
Question_like_ Returns all Articles whose question contains the given strings.
Rating Returns all Articles whose rating matches the given integers.
Rating_max_ Returns all Articles whose rating is less than the given integers.
Rating_min_ Returns all Articles whose rating is greater than the given integers.
Related_Articles_id_ Returns all Articles related to the given Articles.
Times_Viewed Returns all Articles whose view count matches the given integers.
Times_Viewed_min_ Returns all Articles whose view count is greater than the given integers.
Times_Viewed_max_ Returns all Articles whose view count is less than the given integers.
_keywords_ The terms to search for in the Article's Question, Alternate Question, or Answer.

Encode spaces in terms with the plus sign +.

Keyword search can only be used in conjuction with:
Folders_id_
Products_id_
Published=true
_searchoption_
_search_subfolders_
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_searchoption_
allwords
anywords
exactwords
Default: allwords
_search_subfolders_ Choose whether to search through subfolders. Used in conjunction with Folder_id_.

Default: true
_startPage_ The page number to return.

Default: 1
_status_
all Returns all Articles.
active Returns all Articles not in the Trash Bin.
trash Returns all Articles in the Trash Bin.

Default: active
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /Article

Description
Creates an Article.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Article
Method
POST
Request Body
All required fields.
Parameters
_token_
required
Authentication token.
Notes

Article workflow is unavailable via the API. The Published attribute will be ignored.

Any extraneous whitespace for static fields with the string data-type will be removed.

GET /Article/{id}

Description
Retrieves information about an existing Article.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Article/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /Article/{id}

Description
Modify field values of an existing Article.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Article/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_token_
required
Authentication token.
Notes

Article workflow is unavailable via the API. The Published attribute will be ignored, and articles will remain in their current status.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /Article/{id}

Description
Deletes an existing Article.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Article/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Moves the Article to the Trash.
true Deletes the Article from the system.

Default: false
_token_
required
Authentication token.
Notes
Only Articles in the Trash can be permanently deleted from the system.

GET /Article/schema

Description
Retrieves a description of the Article object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Article/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Answer
required
string

The Answer of the Article.
Created_By entity

The CSR who created the Article.
Date_Created date

The Creation Date of the Article.
Date_Updated date

The Date the Article was last Updated.
Expiration_Date date

The Expiration Date of the Article.
Folders
required
entity

A list of folders the Article resides in.
Keywords string

The Keywords of the Article.
Language string

The Language the Article is written in.
Modified_By entity

The CSR who last updated the Article.
Permissions entity

A list of SLAs that can view the Article.
Products entity

A list of Products that are associated to the Article.
Published
required
boolean

Whether the Article is in the Published or Draft state.
Question
required
string

The Question of the Article.
Rating int

The rating of the Article.
Related_Articles entity

A list of Articles marked as related.
Times_Viewed int

The number of times the Article has been viewed from the Portal.
Translations entity

A list of Translations of the Article.

GET /Article/Search new

Description
Searches and returns all Articles that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Article/Search
Method
GET
Requet Body
None
Parameters
Folders_id_ Returns only Articles to the given Folders and their subfolders.

See Article Folders for a list of available values.
Language Returns all Articles with the given language. The specified language must be in the format of {language code}-{region code}.

Ex: en-us for English-United States
Products_id_ Returns all Articles associated with the given Products.

See Products for a list of available values.
Published
false Returns all Articles in the Draft status.
true Returns all Articles in the Published status.
_keywords_
required
The terms to search for in the Article's Question, Alternate Question, Answer or Keywords.

Encode spaces in terms with the plus sign +.
_order_ Sort the result set by the specified field. The list below are the fields you can sort by:
Date_Updated Sort the results by updated date of the Article
Date_Created Sort the results by the created date of the Article
Rating Sort the results by the rating received on the Article
Relevance Sort the results by the most relevant Article. Only supports sorting in descending order.
Times_Viewed Sort the results by the view count of the Article

The direction of the sort can be defined by appending:
_asc_ Ascending
_desc_ Descending

Default: _desc_
_pageSize_ Number of results per page.

Default: 25
_search_subfolders_ Choose whether to search through subfolders. Used in conjunction with Folder_id_.

Default: true
_startPage_ The page number to return.

Default: 1
_status_
all Returns all Articles.
active Returns all Articles not in the Trash Bin.
trash Returns all Articles in the Trash Bin.

Default: active
_token_
required
Authentication token.
Notes
Only supports the JSON format for output.

GET /ArticleTranslation

Description
Lists all Article Translations that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleTranslation
Method
GET
Request Body
None
Parameters
Published
false Returns all Article Translations in the Draft status.
true Returns all Article Translations in the Published status.
Language Returns all Article Translations whose language matches the given string.
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /ArticleTranslation

Description
Creates an Article Translation.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleTranslation
Method
POST
Request Body
All required fields.
Parameters
_token_
required
Authentication token.

GET /ArticleTranslation/{id}

Description
Retrieves information about an existing Article Translation.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleTranslation/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

GET /ArticleTranslation/schema

Description
Retrieves a description of the Article Translation object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleTranslation/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Answer_Translation
required
string

The Answer translation of the Article.
ArticleId
required
int

The id of the original Article.
Keywords_Translation string

The Keywords translation of the Article.
Language string

The Language of the translated Article.
Needs_Update
required
boolean

Whether the translated Article needs an update.
Published
required
boolean

Whether the translated Article is in the Published or Draft state.
Question_Translation
required
string

The Question translation of the Article.

GET /ArticleFolder

Description
Lists all Article Folders that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleFolder
Method
GET
Request Body
None
Parameters
Name Returns all Article Folders whose name matches the given strings.
Name_like_ Returns all Article Folders whose name contains the given strings.
Is_Private
false Returns all Article Folders marked as Public.
true Returns all Article Folders marked as Private.
Parent_Folder_id_ Returns all Article Folders with the given Parent Folders.
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /ArticleFolder

Description
Creates an Article Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleFolder
Method
POST
Request Body
All required fields.
Parameters
_token_
required
Authentication token.
Notes
Any extraneous whitespace for static fields with the string data-type will be removed.

GET /ArticleFolder/{id}

Description
Retrieves information about an existing Article Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleFolder/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /ArticleFolder/{id}

Description
Modify field values of an existing Article Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleFolder/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_token_
required
Authentication token.
Notes

To delete a value, include only the field's node in the request body. The value for non-editable fields cannot be deleted.

If a field's node is completely absent from the request body, the field value will remain unchanged.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /ArticleFolder/{id}

Description
Deletes an existing Article Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleFolder/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Returns 400 error.
true Deletes the Article Folder from the system.

Default: false
_token_
required
Authentication token.
Notes
Only empty folders can be deleted from the system.

GET /ArticleFolder/schema

Description
Retrieves a description of the Article Folder object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ArticleFolder/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Description string

Description of the Article Folder.
Is_Private boolean

Whether the Article Folder is visible on the Portal.
Name
required
string

Name of the Article Folder.
Parent_Folder
required
entity

The Parent Folder (if any) of the Article Folder.

Download File

GET /Download

Description
Lists all Downloads that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Download
Method
GET
Request Body
None
Parameters
Date_Created Returns all Downloads created on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

Also see Relative Date Queries.
Date_Created_min_ Returns all Downloads created on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all Downloads created on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Updated Returns all Downloads updated on the given dates.

Also see Relative Date Queries.
Date_Updated_min_ Returns all Downloads updated on or after the given dates.

See Date_Created for valid formats.
Date_Updated_max_ Returns all Downloads updated on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Description Returns all Downloads whose description matches the given strings.
Description_like_ Returns all Downloads whose description contains the given strings.
Eula_id_ Returns all Downloads with the given EULAs.
Ext Returns all Downloads whose extension matches the given strings.
Ext_like_ Returns all Downloads whose extension contains the given strings.
External_Link Returns all Downloads whose external link matches the given strings.
External_Link_like Returns all Downloads whose external link contains the given strings.
File_Hits Returns all Downloads whose number of times downloaded matches the given intergers.
File_Hits_max_ Returns all Downloads whose number of times downloaded is less than the given intergers.
File_Hits_min_ Returns all Downloads whose number of times downloaded is greater than given intergers.
File_Size Returns all Downloads whose file size matches the given integers.
File_Size_max_ Returns all Downloads whose file size is less than the given integers.
File_Size_min_ Returns all Downloads whose file size is greater than given integers.
Folder_id_ Download Folders to limit the result set to.

See Download Folders for a list of available values.
Guid Returns all Downloads whose GUID matches the given strings.
Guid_like_ Returns all Downloads whose GUID contains the given strings.
_includeSubFolders_
false Only search through the given Folders, do not search through subfolders.
true Also search through the subfolders.

Used in conjunction with Folder_id_.

Default: false
Name Returns all Downloads whose name matches the given strings.
Name_like_ Returns all Downloads whose name contains the given strings.
Permissions_id_ Returns all Downloads with the given SLAs.

See SLAs for a list of available values.
Products_id_ Returns all Downloads associated with the given Products.

See Products for a list of available values.
Published
false Returns all Downloads in the Draft status.
true Returns all Downloads in the Published status.
Title Returns all Downloads whose title matches the given strings.
Title_like_ Returns all Downloads whose title contains the given strings.
Visible
false Returns all Downloads that requires permission validation in prior to download.
true Returns all Downloads that do not require permission validation to download.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_status_
all Returns all Downloads.
active Returns all Downloads not in the Trash Bin.
trash Returns all Downloads in the Trash Bin.

Default: active
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /Download

Description

Creates a Download.

Uploading a file to be hosted in the Parature system is a three-step process:

  1. Get an Upload URI GET /Download/upload

  2. Upload the file POST /FileManagement/Upload/

    The URI to use is returned in the href attribute when retrieving the Upload URI.

    Include the file in the request body in standard HTTP upload format (RFC 1867).

  3. Create the Download

    Include the GUID returned from the successful upload operation.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Download
Method
POST
Request Body
All required fields.
Parameters
_token_
required
Authentication token.
Notes

The Upload URI contains a temporary token that expires after 90 minutes. It is recommneded that the Upload URI is used for a single attachment operation.

Only GUID or External_Link should be supplied, not both.

Any extraneous whitespace for static fields with the string data-type will be removed.

GET /Download/{id}

Description
Retrieves information about an existing Download.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Download/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /Download/{id}

Description

Modify field values of an existing Download.

Updating the file to be hosted in the Parature system is a three-step process:

  1. Get an Upload URI GET /Download/upload

  2. Upload the file POST /FileManagement/Upload/

    The URI to use is returned in the href attribute when retrieving the Upload URI.

    Include the file in the request body in standard HTTP upload format (RFC 1867).

  3. Update the Download

    Include the GUID returned from the successful upload operation.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Download/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_token_
required
Authentication token.
Notes

The Upload URI contains a temporary token that expires after 90 minutes. It is recommneded that the Upload URI is used for a single attachment operation.

Only GUID or External_Link should be supplied, not both.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /Download/{id}

Description
Deletes an existing Download.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Download/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Moves the Download to the Trash.
true Deletes the Download from the system.

Default: false
_token_
required
Authentication token.
Notes
Only Downloads in the Trash can be permanently deleted from the system.

GET /Download/schema

Description
Retrieves a description of the Download object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Download/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Date_Created date

The Creation Date of the Download.
Date_Updated date

The Date the Download was last Updated.
Description string

Description of the Download.
Eula entity

The EULA associated to the Download.
Ext string

File extension of the Download.
External_Link string

The URL of the Download if hosted outside of the Parature system.
File_Hits int

The number of times the Download has been downloaded.
File_Size int

Size of the file in bytes.
Folders
required
entity A list of folders the Download resides in.
Guid string

The GUID of the Download File if hosted in the Parature system.
Name string

Name of the Download File.
Permissions entity

A list of SLAs that can view the Download.
Products entity

A list of Products that are associated to the Download.
Published
required
boolean

Whether the Download is in the Published or Draft state.
Title
required
string

Title of the Download.
Visible boolean

Whether permissions are checked prior to download.

GET /DownloadFolder

Description
Lists all Download Folders that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/DownloadFolder
Method
GET
Request Body
None
Parameters
Date_Updated Returns all Download Folders updated on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

Also see Relative Date Queries.
Date_Updated_min_ Returns all Download Folders updated on or after the given dates.

See Date_Updated for valid formats.
Date_Updated_max_ Returns all Download Folders updated on or before the given dates.

See Date_Updated for valid formats.

Also see Relative Date Queries.
Description Returns all Download Folders whose description matches the given strings.
Description_like_ Returns all Download Folders whose description contains the given strings.
Is_Private
false Returns all Download Folders marked as Public.
true Returns all Download Folders marked as Private.
Name Returns all Download Folders whose name matches the given strings.
Name_like_ Returns all Download Folders whose name contains the given strings.
Parent_Folder_id_ Returns all Download Folders with the given Parent Folders.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /DownloadFolder

Description
Creates a Download Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/DownloadFolder
Method
POST
Request Body
All required fields.
Parameters
_token_
required
Authentication token.
Notes
Any extraneous whitespace for static fields with the string data-type will be removed.

GET /DownloadFolder/{id}

Description
Retrieves information about an existing Download Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/DownloadFolder/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

POST /DownloadFolder/{id}

Description
Modify field values of an existing Download Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/DownloadFolder/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_token_
required
Authentication token.
Notes

To delete a value, include only the field's node in the request body. The value for non-editable fields cannot be deleted.

If a field's node is completely absent from the request body, the field value will remain unchanged.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /DownloadFolder/{id}

Description
Deletes an existing Download Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/DownloadFolder/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Returns 400 error.
true Deletes the Download Folder from the system.

Default: false
_token_
required
Authentication token.
Notes
Only empty folders can be deleted from the system.

GET /DownloadFolder/schema

Description
Retrieves a description of the Download Folder object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/DownloadFolder/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Date_Updated date

The Date the Download Folder was last Updated.
Description string

Description of the Download Folder.
Is_Private boolean

Whether the Download Folder is visible on the Portal.
Name
required
string

Name of the Download Folder.
Parent_Folder
required
entity

The Parent Folder (if any) of the Download Folder.

GET /Eula

Description
Lists all EULAs that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Eula
Method
GET
Request Body
None
Parameters
Short_Title Returns all EULAs whose short title matches the given strings.
Short_Title_like_ Returns all EULAs whose short title contains the given strings.
Title Returns all EULAs whose title matches the given strings.
Title_like_ Returns all EULAs whose title contains the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order.
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Eula/{id}

Description
Retrieves information about an existing EULA.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Eula/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

GET /Eula/schema

Description
Retrieves a description of the EULA object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Eula/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Description
required
string

The details of the EULA.
Short_Title
required
string

The short title of the EULA.
Title
required
string

The title of the EULA displayed on the Portal.

Account

GET /Account

Description
Lists all Accounts that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account
Method
GET
Request Body
None
Parameters
Account_Name Returns all Accounts whose name matches any of the given strings.
Account_Name_like_ Returns all Accounts whose name contains the given strings.
Date_Created Returns all Accounts created on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

Also see Relative Date Queries.
Date_Created_min_ Returns all Accounts created on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all Accounts created on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Updated Returns all Accounts updated on the given dates.

See Date_Created for valid formats.
Date_Updated_min_ Returns all Accounts updated on or after the given dates.

See Date_Created for valid formats.
Date_Updated_max_ Returns all Accounts updated on or before the given dates.

See Date_Created for valid formats.
Default_Customer_Role_id_ Returns all Accounts for the given Default Customer Roles.
Modified_By_id_ Return all Accounts last updated by the given CSRs.

See CSRs for a list of available values.
Owned_By_id_ Return all Accounts created by the given CSRs.

See CSRs for a list of available values.
Sla_id_ Returns all Accounts with the given SLAs.

See SLAs for a list of available values.
FIDnnnn Custom Field value match using field ID, where nnnn is the ID of the custom field.
_fields_ A comma-delimited list of custom field IDs to include in the resulting object list.

Default: none
_order_ A comma-delimited list of field names and/or IDs to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page up to a maximum of 500.

Default: 25
_startPage_ The page number to return.

Default: 1
_status_
all Returns all Accounts.
active Returns all Accounts not in the Trash.
trash Returns all Accounts in the Trash.

Default: active
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false
_view_ Return all Tickets using the query defined by the given view.

See Account Views for a list of available values.

POST /Account

Description

Creates an Account.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account
Method
POST
Request Body
All required fields.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_token_
required
Authentication token.
Notes

Custom fields with default values will be applied when a value is not supplied in the request body.

Any extraneous whitespace for static fields with the string data-type will be removed.

GET /Account/{id}

Description
Retrieves information about an existing Account.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /Account/{id}

Description
Modify field values of an existing Account.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_token_
required
Authentication token.
Notes

To delete a value, include only the field's node in the request body. The value for non-editable fields cannot be deleted.

If a field's node is completely absent from the request body, the field value will remain unchanged.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /Account/{id}

Description
Deletes an exisitng Account.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Moves the Account to the Trash.
true Deletes the Account from the system.

Default: false
_token_
required
Authentication token.
Notes
Only Accounts in the Trash can be permanently deleted from the system.

GET /Account/schema

Description
Retrieves a description of the Account object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Account_Name
required
string

Name of the Account.
Date_Created date

The Creation Date of the Account.
Date_Updated date

The Date the Account was last Updated.
Default_Customer_Role entity

Determines which Customer Role is assigned to new Customers for this Account if one is not specified when creating or updating a Customer.

Default: 'Customer'
Modified_By entity

The CSR who last updated the Account.
Owned_By entity

The CSR who created the Account.
Shown_Accounts entity

A list of related child Accounts.
Sla
required
entity

The SLA associated to the Account.

GET /Account/view

Description
Lists all Account Views that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account/view
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Account/view/{id}

Description
Retrieves information about an existing Account View.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account/view/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

Customer

GET /Customer

Description
Lists all Customers that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer
Method
GET
Request Body
None
Parameters
Account_id_ Returns all Customers associated to the given Accounts.

See Accounts for a list of available values.
Customer_Role_id_ Returns all Customers with the given Customer Roles.

See Customer Roles for a list of available values.
Date_Created Returns all Customers created on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

Also see Relative Date Queries.
Date_Created_min_ Returns all Customers created on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all Customers created on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Updated Returns all Customers updated on the given dates.

See Date_Created for valid formats.
Date_Updated_min_ Returns all Customers updated on or after the given dates.

See Date_Created for valid formats.
Date_Updated_max_ Returns all Customers updated on or before the given dates.

See Date_Created for valid formats.
Date_Visited Returns all Customers visited on the given dates.

See Date_Created for valid formats.
Date_Visited_max_ Returns all Customers visited less than the given dates.

See Date_Created for valid formats.
Date_Visited_min_ Returns all Customers visited greater than the given dates.

See Date_Created for valid formats.
Email Returns all Customers whose email matches the given strings.
Email_like_ Returns all Customers whose email contains the given strings.
First_Name Returns all Customers whose first name matches the given strings.
First_Name_like_ Returns all Customers whose first name contains the given strings.
Full_Name Returns all Customers whose full name (first last) matches the given strings.
Full_Name_like_ Returns all Customers whose full name (first last) contains the given strings.
Last_Name Returns all Customers whose last name matches the given strings.
Last_Name_like_ Returns all Customers whose last name contains the given strings.
Sla_id_ Returns all Customers with the given SLAs.

See SLAs for a list of available values.
Status_id_ Returns all Customers with the given Statuses.

See Customer Statuses for a list of available values.
User_Name Returns all Customers whose username matches the given strings.
User_Name_like_ Returns all Customers whose username contains the given strings.
FIDnnnn Custom Field value match using field ID, where nnnn is the ID of the custom field.
_fields_ A comma-delimited list of custom field IDs to include in the resulting object list.
_order_ A comma-delimited list of field names and/or IDs to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_status_
all Returns all Accounts.
active Returns all Accounts not in the Trash.
trash Returns all Accounts in the Trash.

Default: active
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false
_view_ Return all Tickets using the query defined by the given view.

See Customer Views for a list of available values.

POST /Customer

Description

Creates a Customer.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer
Method
POST
Request Body
All required fields.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_includePassword_
false Do not include a link to reset their password in the email sent to the Customer.
true Include a link to reset their password in the email sent to the Customer.

Can only be used when _notify_=true.

Default: false
_notify_
false Do not send an email to the Customer that a profile has been created.
true Send an email to the Customer that a profile has been created.

Default: false
_token_
required
Authentication token.
Notes

If Customer_Role is not specified, a default will be assigned:

  • Default_Customer_Role will be used if the Customer is associated to an Account, otherwise
  • 'Customer'

Custom fields with default values will be applied when a value is not supplied in the request body.

Any extraneous whitespace for static fields with the string data-type will be removed.

GET /Customer/{id}

Description
Retrieves information about an existing Customer.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /Customer/{id}

Description
Modify field values of an existing Customer.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_includePassword_
false Do not include a link to reset their password in the email sent to the Customer.
true Include a link to reset their password in the email sent to the Customer.

Can only be used when _notify_=true.

Default: false
_notify_
false Do not send an email to the Customer that a profile has been udpated.
true Send an email to the Customer that their profile has been updated.

Default: false
_token_
required
Authentication token.
Notes

To delete a value, include only the field's node in the request body. The value for non-editable fields cannot be deleted.

If a field's node is completely absent from the request body, the field value will remain unchanged.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /Customer/{id}

Description
Deletes an exisitng Customer.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Moves the Customer to the Trash.
true Deletes the Customer from the system.

Default: false
_token_
required
Authentication token.
Notes
Only Customers in the Trash can be permanently deleted from the system.

GET /Customer/schema

Description
Retrieves a description of the Account object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Account/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Account entity

The Account the Customer is associated to.
Customer_Role entity

The Role of the Customer.
Date_Created date

The Creation Date of the Customer.
Date_Updated date

The Date the Customer was last Updated.
Date_Visited date

Date Customer last visited the Portal.
Email string

Email address of the Customer.
First_Name string

Customer's first name.
Full_Name string

Customer's full name (first and last name).
Last_Name string

Customer's last name.
Password string

Customer's password. Only available on create and update.
Password_Confirm string

Customer's password. Only available on create and update.
Sla entity

The SLA associated to the Customer.
Status entity

Whether the Customer can log into the Portal.
User_Name string

Customer's username.

GET /Customer/view

Description
Lists all Customer Views that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer/view
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Customer/view/{id}

Description
Retrieves information about an existing Customer View.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer/view/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

GET /Customer/status

Description
Lists all Customer Statuses that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer/status
Method
GET
Request Body
None
Parameters
Name Returns all Customer Statuses whose name matches the given strings.
Name_like_ Returns all Customer Statuses whose name contains the given strings.
Description Returns all Customer Statuses whose description matches the given strings.
Description_like_ Returns all Customer Statuses whose description contains the given strings.
Text Returns all Customer Statuses whose text matches the given strings.
Text_like_ Returns all Customer Statuses whose text contains the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Customer/role

Description
Lists all Customer Roles that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer/role
Method
GET
Request Body
None
Parameters
Name Returns all Customer Roles whose name matches the given strings.
Name_like_ Returns all Customer Roles whose name contains the given strings.
Description Returns all Customer Roles whose description matches the given strings.
Description_like_ Returns all Customer Roles whose description contains the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Customer/auth

Description
Verfies the credentials of the Customer.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Customer/auth
Method
GET
Request Body
None
Parameters
_email_ Customer's email to authenticate.
_password_ Corresponding password to the Customer's email or username to authenticate.
_username_ Customer's username to authenticate.
_token_
required
Authentication token.
Returns
Valid
Invalid
LockedOut 3 unsuccessful validation attemps made within the defined lockout timeframe.
PasswordNotRequired Department is not configued to required a password to log in.
Notes
Either the email or the username parameter can be included, not both.

Product

GET /Product

Description
Lists all Products that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Product
Method
GET
Request Body
None
Parameters
Date_Created Returns all Products created on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

Also see Relative Date Queries.
Date_Created_min_ Returns all Products created on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all Products created on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Updated Returns all Products updated on the given dates.

also see Relative Date Queries
Date_Updated_min_ Returns all Products updated on or after the given dates.

See Date_Created for valid formats.
Date_Updated_max_ Returns all Products updated on or before the given dates.

See Date_Created for valid formats.

also see Relative Date Queries
Folder_id_ Product Folders and its subfolders to limit the result set to.

See Product Folders for a list of available values.
Instock
false Returns all Products that are not in stock.
true Returns all Products that are in stock.
Longdesc Returns all Products whose long description matches the given strings.
Longdesc_like_ Returns all Products whose long description contains the given strings.
Name Returns all Products whose name matches the given strings.
Name_like_ Returns all Products whose name contains the given strings.
Price Returns all Products whose price matches the given strings.
Price_like_ Returns all Products whose price contains the given strings.
Shortdesc Returns all Products whose short description matches the given strings.
Shortdesc_like_ Returns all Products whose short description contains the given strings.
Sku Returns all Products whose SKU matches the given strings.
Sku_like_ Returns all Products whose SKU contains the given strings.
Visible
false Returns all Products that are not available during the Product Registration process.
true Returns all Products that are available during the Product Registration process.
_fields_ A comma-delimited list of custom field IDs to include in the resulting object list.
FIDnnnn Custom Field value match using field ID, where nnnn is the ID of the custom field.
_order_ A comma-delimited list of field names and/or IDs to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_status_
all Returns all Products.
active Returns all Products not in the Trash.
trash Returns all Products in the Trash.
Default: active
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /Product

Description

Creates a Product.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Product
Method
POST
Request Body
All required fields.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_token_
required
Authentication token.
Notes

Custom fields with default values will be applied when a value is not supplied in the request body.

Any extraneous whitespace for static fields with the string data-type will be removed.

GET /Product/{id}

Description
Retrieves information about an existing Product.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Product/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /Product/{id}

Description
Modify field values of an existing Product.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Product/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_token_
required
Authentication token.
Notes

To delete a value, include only the field's node in the request body. The value for non-editable fields cannot be deleted.

If a field's node is completely absent from the request body, the field value will remain unchanged.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /Product/{id}

Description
Deletes an exisitng Product.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Product/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Moves the Product to the Trash.
true Deletes the Product from the system.

Default: false
_token_
required
Authentication token.
Returns
Notes
Only Products in the Trash can be permanently deleted from the system.

GET /Product/schema

Description
Retrieves a description of the Product object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Product/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Date_Created date

The Creation Date of the Product.
Date_Updated date

The Date the Product was last Updated.
Folder
required
entity

The folder the Product resides in.
Instock boolean

Whether the Product is in stock.
Longdesc string

The long description of the Product.
Name
required
string

The name of the Product.
Price string

The price of the Product.
Shortdesc string

The short description of the Product.
Sku string

The SKU of the Product.
Visible boolean

Whether the Product is available to the Customer during the Product Registration process.

GET /ProductFolder

Description
Lists all Product Folders that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ProductFolder
Method
GET
Request Body
None
Parameters
Date_Updated Returns all Product Folders updated on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

also see Relative Date Queries
Date_Updated_min_ Returns all Product Folders updated on or after the given dates.

See Date_Updated for valid formats.
Date_Updated_max_ Returns all Product Folders updated on or before the given dates.

See Date_Updated for valid formats.

also see Relative Date Queries
Description Returns all Product Folders whose description matches the given strings.
Description_like_ Returns all Product Folders whose description contains the given strings.
Is_Private
false Returns all Product Folders marked as Public.
true Returns all Product Folders marked as Private.
Name Returns all Product Folders whose name matches the given strings.
Name_like_ Returns all Product Folders whose name contains the given strings.
Parent_Folder_id_ Returns all Product Folders with the given Parent Folders.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /ProductFolder

Description
Creates a Product Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ProductFolder
Method
POST
Request Body
All required fields.
Parameters
_token_
required
Authentication token.

GET /ProductFolder/{id}

Description
Retrieves information about an existing Product Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ProductFolder/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /ProductFolder/{id}

Description
Modify field values of an existing Product Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ProductFolder/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_token_
required
Authentication token.
Notes

To delete a value, include only the field's node in the request body. The value for non-editable fields cannot be deleted.

If a field's node is completely absent from the request body, the field value will remain unchanged.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /ProductFolder/{id}

Description
Deletes an existing Product Folder.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ProductFolder/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Returns 400 error.
true Deletes the Product Folder from the system.

Default: false
_token_
required
Authentication token.
Returns
Notes
Only empty folders can be deleted from the system.

GET /ProductFolder/schema

Description
Retrieves a description of the Product Folder object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/ProductFolder/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Date_Updated date

The Date the Product Folder was last Updated.
Description string

Description of the Product Folder.
Is_Private
required
boolean Whether the Product Folder is visible on the Portal.
Name
required
string

Name of the Product Folder.
Parent_Folder
required
entity

The of the Parent Folder (if any) of the Product Folder.

Asset

GET /Asset

Description
Lists all Assets that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Asset
Method
GET
Request Body
None
Parameters
Account_Owner_id_ Returns all Assets owned by the given Accounts.

See Accounts for a list of available values.
Created_By_id_ Returns all Assets created by the given CSRs.

See CSRs for a list of available values.
Customer_Owner_id_ Returns all Assets owned by the given Customers.

See Customers for a list of available values.
Date_Created Returns all Assets created on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

Also see Relative Date Queries.
Date_Created_min_ Returns all Assets created on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all Assets created on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Updated Returns all Assets updated on the given dates.

Also see Relative Date Queries.
Date_Updated_min_ Returns all Assets updated on or after the given dates.

See Date_Created for valid formats.
Date_Updated_max_ Returns all Assets updated on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Modified_By_id_ Returns all Assets last updated by the given CSRs.

See CSRs for a list of available values.
Name Returns all Assets whose name matches the given strings.
Name_like_ Returns all Assets whose name contains the given strings.
Product_id_ Returns all Assets for the given Products.

See Products for a list of available values.
Serial_Number Returns all Assets whose serial number matches the given strings.
Serial_Number_like_ Returns all Assets whose serial number contains the given strings.
Status_id_ Returns all Assets in the given Statuses.

See Asset Statuses for a list of available values.
_fields_ A comma-delimited list of custom field IDs to include in the resulting object list.
FIDnnnn Custom Field value match using field ID, where nnnn is the ID of the custom field.
_order_ A comma-delimited list of field names and/or IDs to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_status_
all Returns all Assets.
active Returns all Assets not in the Trash.
trash Returns all Assets in the Trash.
Default: active
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /Asset

Description

Creates an Asset.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Asset
Method
POST
Request Body
All required fields.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_token_
required
Authentication token.
Notes

Custom fields with default values will be applied when a value is not supplied in the request body.

Any extraneous whitespace for static fields with the string data-type will be removed.

GET /Asset/{id}

Description
Retrieves information about an existing Asset.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Asset/{id}
Method
GET
Request Body
None
Parameters
_history_
false Do not return the history of the Asset.
true Return the history of the Asset.

Default: false
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /Asset/{id}

Description

Modify field values of an existing Asset.

Executing an action is a three-step process:

  1. Retrieve the Asset
  2. Get the Action schema for the action you want to execute
  3. Execute the action

    Include the action in the PUT /Asset/{id} request.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Asset/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_token_
required
Authentication token.
Notes

To delete a value, include only the field's node in the request body. The value for non-editable fields cannot be deleted.

If a field's node is completely absent from the request body, the field value will remain unchanged.

Any extraneous whitespace for static fields with the string data-type will be removed.

DELETE /Asset/{id}

Description
Deletes an exisitng Asset.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Asset/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Moves the Asset to the Trash.
true Deletes the Asset from the system.

Default: false
_token_
required
Authentication token.
Notes
Only Assets in the Trash can be permanently deleted from the system.

GET /Asset/schema

Description
Retrieves a description of the Asset object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Asset/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Account_Owner entity

The Account that owns the Asset.
Created_By entity

The CSR who created the Asset.
Customer_Owner entity

The Customer that owns the Asset.
Date_Created date

The Creation Date of the Asset.
Date_Updated date

The Date the Asset was last Updated.
Modified_By date

The CSR who last updated the Asset.
Name string

Name of the Asset.
Product entity

The Product the Asset belongs to.
Serial_Number string

Serial number of the Asset.
Status entity

The status of the Asset.
Vendor entity

The vendor of the Asset.

GET /Ticket/status

Description
Lists all Ticket Statuses that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket/status
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Asset/action/{id}

Description
Retrieves a description of the Asset Action object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Asset/action/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Name string
Type string
Comment string

The comment provided with the action.

Ticket

GET /Ticket

Description
Lists all Tickets that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket
Method
GET
Request Body
None
Parameters
Additional_Contact_id_ Returns all Tickets for the given Additional Customer.

See Customers for a list of available values.
Additional_Contact_Account_id_ Returns all Tickets for the given Additional Customer's Accounts.

See Accounts for a list of available values.

Cannot be used in _order_.
Assigned_To_id_ Returns all Tickets assigned to the given CSRs.

See CSRs for a list of available values.
Date_Created Returns all Tickets created on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

Also see Relative Date Queries.
Date_Created_min_ Returns all Tickets created on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all Tickets created on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Updated Returns all Tickets updated on the given dates.

Also see Relative Date Queries.
Date_Updated_min_ Returns all Tickets updated on or after the given dates.

See Date_Created for valid formats.
Date_Updated_max_ Returns all Tickets updated on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Email_Notification
false Returns all Tickets where the Customer will not receive any notifications about the Ticket via email.
true Returns all Tickets where the Customer will receive any notifications about the Ticket via email.
Email_Notification_Additional_Contact
false Returns all Tickets where the Additional Customer will not receive any notifications about the Ticket via email.
true Returns all Tickets where the Additional Customer will receive any notifications about the Ticket via email.
Entered_By_id_ Returns all Tickets created by the given CSRs.

See CSRs for a list of available values.
Hide_From_Customer
false Returns all Tickets that are visible to the Customer.
true Returns all Tickets that are hidden from the Customer.
Initial_Resolution_Date Returns all Tickets initially solved on the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Initial_Resolution_Date_min_ Returns all Tickets initially solved on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Initial_Resolution_Date_max_ Returns all Tickets initially solved on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Initial_Resolution_Duration_Bh Returns all Tickets whose resolution duration is equal to the given durations. Business hours is respected in the calculation of duration.
Initial_Resolution_Duration_Bh_max_ Returns all Tickets whose resolution duration is less than the given durations. Business hours is respected in the calculation of duration.
Initial_Resolution_Duration_Bh_min_ Returns all Tickets whose resolution duration is greater than the given durations. Business hours is respected in the calculation of duration.
Initial_Resolution_Target_Duration Returns all Tickets whose target resolution duration is equal the given durations. Business hours is respected in the calculation of duration.
Initial_Resolution_Target_Duration_max_ Returns all Tickets whose target resolution duration is less than the given durations. Business hours is respected in the calculation of duration.
Initial_Resolution_Target_Duration_min_ Returns all Tickets whose target resolution duration is greater than the given durations. Business hours is respected in the calculation of duration.
Initial_Resolution_Userid Returns all Tickets where the initial resolution was provided by the given CSRs.

See CSRs for a list of available values.
Initial_Response_Duration_Bh Returns all Tickets whose inital response duration is equal to the given durations. Business hours is respected in the calculation of duration.
Initial_Response_Duration_Bh_max_ Returns all Tickets whose inital response duration is less than the given durations. Business hours is respected in the calculation of duration.
Initial_Response_Duration_Bh_min_ Returns all Tickets whose inital response duration is greater than the given durations. Business hours is respected in the calculation of duration.
Initial_Response_Target_Duration Returns all Tickets whose target inital response duration is equal the given durations. Business hours is respected in the calculation of duration.
Initial_Response_Target_Duration_max_ Returns all Tickets whose target inital response duration is less than the given durations. Business hours is respected in the calculation of duration.
Initial_Response_Target_Duration_min_ Returns all Tickets whose target inital response duration is greater than the given durations. Business hours is respected in the calculation of duration.
Initial_Response_Userid Returns all Tickets where the initial response was provided by the given CSRs.

See CSRs for a list of available values.
Last_Resolution_Duration_Bh Returns all Tickets whose resolution duration is equal to the given durations. Business hours is respected in the calculation of duration.
Last_Resolution_Duration_Bh_max_ Returns all Tickets whose resolution duration is less than to the given durations. Business hours is respected in the calculation of duration.
Last_Resolution_Duration_Bh_min_ Returns all Tickets whose resolution duration is greater than to the given durations. Business hours is respected in the calculation of duration.
Resolution_Sla_id_ Returns all Tickets where the SLA used to calculate resolution matches the given SLAs.

See SLAs for a list of available values.
Resolution_Violation_Date_Bh Returns all Tickets where the resolution violation occurred on the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Resolution_Violation_Date_Bh_min_ Returns all Tickets where the resolution violation occurred on or after the given dates. See Date_Created for valid formats.

Also see Relative Date Queries.
Resolution_Violation_Date_Bh_max_ Returns all Tickets where the resolution violation occurred on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Response_Sla_id Returns all Tickets where the SLA used to calculate resolution matches the given SLAs.

See SLAs for a list of available values.
Response_Violation_Date_Bh Returns all Tickets where the initial response violation occurred on the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Response_Violation_Date_Bh_min_ Returns all Tickets where the initial response violation occurred greater than to the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Response_Violation_Date_Bh_max_ Returns all Tickets where the initial response violation occurred less than to the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Ticket_Account_id_ Returns all Tickets for the given Customer's Accounts.

See Accounts for a list of available values.
Ticket_Children_id_ Returns all Tickets that have the associated childrens.
Ticket_Customer_id_ Returns all Tickets for the given Customer.

See Customers for a list of available values.
Ticket_Parent_id_ Returns all Tickets that have the associate parents.
Ticket_Product_id_ Returns all Tickets for the given Assets.

See Assets for a list of available values.
Ticket_Queue_id_ Returns all Tickets in the given Queues.

See Ticket Queues for a list of available values.
Ticket_Sla_id_ Returns all Tickets for the given SLAs.

See SLAs for a list of available values.
Ticket_Status_id_ Returns all Tickets in the given Ticket Statuses.

See Ticket Statuses for a list of avaialble values.
_fields_ A comma-delimited list of custom field IDs to include in the resulting object list.
FIDnnnn Custom Field value match using field ID, where nnnn is the ID of the custom field.
_my_tickets_ Returns all Tickets currently assigned to the CSR identified by the _token_ used in the request.

Default: false
_order_ A comma-delimited list of field names and/or IDs to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_status_
all Returns all Tickets.
active Returns all Tickets not in the Trash.
trash Returns all Tickets in the Trash.
Default: active
_status_type_
open Returns all Tickets in all open Ticket Statuses.
closed Returns all Tickets in all closed Ticket Statuses.
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false
_view_ Return all Tickets using the query defined by the given view.

See Ticket Views for a list of available values.

POST /Ticket

Description

Creates a new Ticket.

Attaching a file to a Ticket is a three-step process:

  1. Get an Upload URI GET /Ticket/upload

  2. Upload the file POST /FileManagement/Upload/

    The URI to use is returned in the href attribute when retrieving the Upload URI.

    Include the file in the request body in standard HTTP upload format (RFC 1867).

  3. Create the Ticket

    Include the GUID returned from the successful upload operation.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket
Method
POST
Request Body
All required fields.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_token_
required
Authentication token.

GET /Ticket/{id}

Description
Retrieves information about an existing Ticket.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket/{id}
Method
GET
Request Body
None
Parameters
_history_
false Do not return the history of the Ticket.
true Return the history of the Ticket.

Default: false
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /Ticket/{id}

Description

Modify field values or execute an action on an existing Ticket.

Attaching a file to a Ticket is a three-step process:

  1. Get an Upload URI GET /Ticket/upload

  2. Upload the file POST /FileManagement/Upload/

    The URI to use is returned in the href attribute when retrieving the Upload URI.

    Include the file in the request body in standard HTTP upload format (RFC 1867).

  3. Update the Ticket

    Include the GUID returned from the successful upload operation.

Executing an action is a three-step process:

  1. Retrieve the Ticket
  2. Get the Action schema for the action you want to execute
  3. Execute the action

    Include the action in the PUT /Ticket/{id} request.

URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_enforceRequiredFields_
false Ignore field dependency and required validation on custom fields.
true Apply field dependency and required validation on custom fields.

Default: true
_token_
required
Authentication token.
Notes

The following action types cannot be performed via the API:

  • Copy
  • Move
  • Template Copy

Files cannot be attached to the Action.

DELETE /Ticket/{id}

Description
Deletes an existing Ticket.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket/{id}
Method
DELETE
Request Body
None
Parameters
_purge_
false Moves the Ticket to the Trash.
true Deletes the Ticket from the system.

Default: false
_token_
required
Authentication token.

GET /Ticket/schema

Description
Retrieves a description of the Ticket object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Additional_Contact entity

The Additional Customer on the Ticket (if any).
Assigned_To entity

The CSR assigned to the Ticket.
Cc_Csr string

A list of CSR email addresses to be included in notifications about the Ticket.
Cc_Customer string

A list of Customer email addresses to be included in notifications about the Ticket.
Date_Closed date

Date the Ticket was last closed.
Date_Created date

The Creation Date of the Ticket.
Date_Responded date

Date of initial response for the Ticket.
Date_Updated date

The Date the Ticket was last Updated.
Department date

The department the Ticket is in.
Dont_Overwrite_Sla_In_Rr boolean

Whether to allow New Ticket Routing Rules to overwrite the given SLA on creation of the Ticket.
Email_Notification boolean

Whether the Customer will receive notifications for the Ticket via email.
Email_Notification_Additional_Contact boolean

Whether the Additional Customer will receive notifications for the Ticket via email.
Entered_By entity

The CSR who created the Ticket (if any).
Final_Resolution_Userid entity

The CSR who resolved the Ticket.
Hide_From_Customer boolean
Whether the Ticket is hidden from the Customer.
Initial_Resolution_Date date

Date of the initial resolution provided on the Ticket.
Initial_Resolution_Duration_Bh int

The time it took to provide an initial resolution on the Ticket with respect to business hours.
Initial_Resolution_Target_Duration int

The target duration to provide an initial resolution on the Ticket with respect to business hours.
Initial_Resolution_Userid entity

The CSR who provided the initial resolution on the Ticket.
Initial_Response_Duration_Bh int

The time it took to provide an initial response on the Ticket with respect to business hours.
Initial_Response_Target_Duration int

The target duration to provide an initial response on the Ticket with respect to business hours.
Inital_Response_Userid entity

The CSR who provided the initial response on the Ticket.
Last_Resolution_Duration_Bh date

The time it took to resolve the Ticket with respect to business hours.
Related_Chats A list of Chats associated to the Ticket.
Resolution_Sla entity

The SLA used to calculate resolution for the Ticket.
Resolution_Violation_Date_Bh Date of the resolution violation (if any).
Response_Sla entity

The SLA used to calculate initial response for the Ticket.
Response_Violation_Date_Bh date

Date of the inital response violation for the Ticket.
Ticket_Attachments attachment

A list of attachments on the Ticket.
Ticket_Children entity

A list of children Tickets.
Ticket_Customer
required
entity

The Customer on the Ticket.
Ticket_Number string

The Ticket number.
Ticket_Parent entity

The parent of the Ticket (if any).
Ticket_Asset entity

The Asset associated to the Ticket.
Ticket_Queue entity

The Ticket Queue the Ticket is assigned to.
Ticket_Sla entity

The SLA of the Ticket.
Ticket_Status entity

The Status of the Ticket.
Warning_Time int

The amount of time prior to initial response and resolution violation on the Ticket before a warning is displayed.

GET /Ticket/view

Description
Lists all Ticket Views that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket/view
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Ticket/status

Description
Lists all Ticket Statuses that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket/status
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Queue

Description
Lists all Ticket Queues that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Queue
Method
GET
Request Body
None
Parameters
Name Returns all Ticket Queues whose name matches any of the given strings.
Name_like_ Returns all Ticket Queues whose name contains any of the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Queue/{id}

Description
Retrieves information about an existing Ticket Queue.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Queue/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

GET /Queue/schema

Description
Retrieves a description of the Ticket Queue object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Queue/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Name string

Name of the Ticket Queue.

GET /Ticket/action/{id}

Description
Retrieves a description of the Ticket Action object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Ticket/action/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Name string
Type string
Comment string

The comment provided with the action.
ShowToCust boolean

Whether to make the action visible on the Portal. Default: false
ShowToAdditionalContact boolean

Whether to make the action visible on the Portal. Default: false
NotifyParent boolean

Whether to notify the CSR assigned to the Parent Ticket.
EmailText string
EmailCsrList string

A comma-delimited list of CSR email addresses to be notified of the action performed on the Ticket.
EmailCustList string

A comma-delimited list of Customer email addresses to be notified of the action performed on the Ticket.
TimeSpentHours int

Time spent in hours.
TimeSpentMinutes int

Time spent in minutes.
Action_Attachments attachment

List of attachments to be associated to the action.
AssignToCsr int

Only avaialble for Assign to CSR action type.
AssignToQueue int

Only available for Assign to Queue action type.
ResolutionField Only available for Solve or Close action types.
Notes
The following actions types cannot be performed via the API:
  • Copy
  • Move
  • Template Copy

GET /Department

Description
Lists all Departments that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Department
Method
GET
Request Body
None
Parameters
Description Returns all Departments whose description matches any of the given strings.
Description_like_ Returns all Departments whose description contains any of the given strings.
Name Returns all Departments whose name matches any of the given strings.
Name_like_ Returns all Departments whose name contains any of the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Department/{id}

Description
Retrieves information about an existing Department.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Department/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

GET /Department/schema

Description
Retrieves a description of the Department object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Department/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Description string

Description of the Department.
Name string

Name of the Department.

Chat

GET /Chat

Description
Lists all ended Chats that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Chat
Method
GET
Request Body
None
Parameters
Browser_Language Returns all Chats where the Customer's browser languages matches the given strings.
Browser_Language_like_ Returns all Chats where the Customer's browser languages contains the given strings.
Browser_Type Returns all Chats where the Customer's browser matches the given strings.
Browser_Type_like_ Returns all Chats where the Customer's browser contains the given strings.
Browser_Version Returns all Chats where the Customer's browser version matches the given strings.
Browser_Version_like_ Returns all Chats where the Customer's browser version contains the given strings.
Customer_id_ Returns all Chats for the given Customers.

See Customers for a list of available values.
Date_Created Returns all Chats started on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

also see Relative Date Queries
Date_Created_min_ Returns all Chats started on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all Chats started on or before the given dates.

See Date_Created for valid formats.

also see Relative Date Queries
Date_Ended Returns all Chats ended on the given dates.

also see Relative Date Queries
Date_Ended_min_ Returns all Chats ended on or after the given dates.

See Date_Created for valid formats.
Date_Ended_max_ Returns all Chats ended on or before the given dates.

See Date_Created for valid formats.

also see Relative Date Queries
Email Returns all Chats where the unknown Customer's email address matches the given strings.
Email_like_ Returns all Chats where the unknown Customer's email address contains the given strings.
Initial_Csr_id_ Returns all Chats initially assigned to the given CSRs.

See CSRs for a list of available values.
Ip_Address Returns all Chats where the Customer's IP Address matches the given strings.
Ip_Address_like_ Returns all Chats where the Customer's IP Address contains the given strings.
Is_Anonymous
false Returns all Chats for known Customers.
true Returns all Chats by unknown Customers (guest).
Referrer_Url Returns all Chats where the referrer URL matches the given strings.
Referrer_Url_like_ Returns all Chats where the referrer URL contains the given strings.
Related_Tickets_id_ Returns all Chats associated to the given Tickets.

See Tickets for a list of available values.
Sla_Violations Returns all Chats that matches the given number of SLA violations.
Status_id_ Returns all Chats in the given Chat Statuses.
Summary Returns all Chats whose summary matches the given strings.
Summary_like_ Returns all Chats whose summary contains the given strings.
User_Agent Returns all Chats where the Customer's user agent matches the given strings.
User_Agent_like_ Returns all Chats where the Customer's user agent contains the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false
Notes
Only chats that have ended will be returned.

GET /Chat/{id}

Description
Retrieves information about an existing Chat.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Chat/{id}
Method
GET
Request Body
None
Parameters
_history_
false Do not return the history of the Chat.
true Return the history of the Chat.

Default: false
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

GET /Chat/{id}/Transcript

Description
Retrieves the transcript for an existing Chat.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Chat/{id}/Transcript
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

GET /Chat/schema

Description
Retrieves a description of the Chat object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Chat/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Browser_Language
required
string

The Customer's browser language used in the Chat.
Browser_Type
required
string

The Customer's browser type used in the Chat.
Browser_Version
required
string

The Customer's browser version used in the Chat.
Chat_Number string

The Chat number.
Customer entity

The Customer on the Chat.
Date_Created date

The Start Date of the chat.
Date_Ended date

End date of the chat.
Email string

The email address of the unknown Customer on the Chat.
Initial_Csr entity The first CSR assigned to the chat.
Ip_Address
required
string

The Customer's IP Address used in the Chat.
Is_Anonymous
required
boolean

Whether the Customer on the Chat is known.
Referrer_Url
required
string

The referrer URL for the Chat.
Related_Tickets entity

A list of Tickets associated to the chat.
Sla_Violations int

The number of SLA violations that occurred in the Chat.
Status entity

The status of the Chat.
Summary string

A summary of the Chat.
User_Agent
required
string

The Customer's user agent used in the Chat.

CSR

GET /CSR

Description
Lists all CSRs that match the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Csr
Method
GET
Request Body
None
Parameters
Date_Created Returns all CSRs created on the given dates. Date must be in one of the following formats:
MM/DD/YYYY Searches by date only.
YYYY-MM-DD Searches by date only.
YYYY-MM-DDThh:mm:ssZ Search by date and time.

Time must be represented in UTC, indicated by Z.

T indicates the start of the time portion of the value.

See Relative Date Queries.
Date_Created_min_ Returns all CSRs created on or after the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Created_max_ Returns all CSRs created on or before the given dates.

See Date_Created for valid formats.

Also see Relative Date Queries.
Date_Format Returns all CSRs whose date format preference matches any of the given strings.
Date_Format_like_ Returns all CSRs whose date format preference contains any of the given strings.
Email Returns all CSRs whose email matches any of the given strings.
Email_like_ Returns all CSRs whose email contains any of the given strings.
Fax Returns all CSRs whose fax matches any of the given strings.
Fax_like_ Returns all CSRs whose fax contains any of the given strings.
Full_Name Returns all CSRs whose full name matches any of the given strings.
Full_Name_like_ Returns all CSRs whose full name contains any of the given strings.
Phone_1 Returns all CSRs whose work phone number matches any of the given strings.
Phone_1_like_ Returns all CSRs whose work phone number contains any of the given strings.
Phone_2 Returns all CSRs whose mobile phone number matches any of the given strings.
Phone_2_like_ Returns all CSRs whose mobile phone number contains any of the given strings.
Role_id_ Returns all CSRs with the given Roles.

See CSR Roles for a list of available values.
Screen_Name Returns all CSRs whose screen name matches any of the given strings.
Screen_Name_like_ Returns all CSRs whose screen name contains any of the given strings.
Status_id_ Returns all CSRs with the given Statuses.

See CSR Statuses for a list of available values.
Timezone_id_ Returns all CSRs with the given Timezone Preferences.

See Timezones for a list of available values.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

POST /CSR

Description
Creates a CSR.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Csr
Method
POST
Request Body
All required fields.
Parameters
_token_
required
Authentication token.
Notes

If a value is not supplied in the request body for the following fields, the corresponding values will be applied:

Any extraneous whitespace for static fields with the string data-type will be removed.

GET /CSR/{id}

Description
Retrieves information about an existing CSR.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Csr/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

PUT /CSR/{id}

Description
Modify an existing CSR.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Csr/{id}
Method
PUT
Request Body
All required fields and the fields that are being changed.
Parameters
_token_
required
Authentication token.

GET /Csr/schema

Description
Retrieves a description of the CSR object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Csr
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Date_Created date

The Creation Date of the CSR.
Date_Format date

The date format preference of the CSR.
mm/dd/yyyy
mm/dd/yy
dd/mm/yyyy
dd/mm/yy
month dd, yyyy
month dd, yy

Default: mm/dd/yyyy
Email
required
string

The email address used to log into the Service Desk.
Fax string

Fax Number.
Full_Name
required
string

Name displayed throughout the Service Desk.

If set to display the Name, this will be displayed externally to Customers (e.g. on the Portal, in Chat, in Forums) as the CSRs name.
Password
required on create only
string

The password used to log into the Service Desk. Will not be returned in GET /Csr or GET /Csr/{id}.
Phone_1 string

Work Phone number.
Phone_2 string

Mobile Phone number.
Role entity

Permissions the CSR has in the Service Desk.
Screen_Name string

If set to display the Alias, this will be displayed externally to Customers (e.g. on the Portal, in Chat, in Forums) as the CSRs name.
Status entity

Only active 1 CSRs can log into the Service Desk.
Timezone entity

The timezone preference of the CSR.

GET /CSR/role

Description
Lists all available permissions to the Service Desk that can be assigned to a CSR.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Csr/role
Method
GET
Request Body
None
Parameters
Description Returns all CSR Roles whose description matches any of the given strings.
Description_like_ Returns all CSR Roles whose description contains any of the given strings.
Name Returns all CSR Roles whose name matches any of the given strings.
Name_like_ Returns all CSR Roles whose name contains any of the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Csr/status

Description
Lists all CSR Statuses that matches the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Csr/status
Method
GET
Request Body
None
Parameters
Description Returns all CSR Statuses whose description matches any of the given strings.
Description_like_ Returns all CSR Statuses whose description contains any of the given strings.
Name Returns all CSR Statuses whose name matches any of the given strings.
Name_like_ Returns all CSR Statuses whose name contains any of the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /SLA

Description
Lists all SLAs that matches the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Sla
Method
GET
Request Body
None
Parameters
Name Returns all SLAs whose name matches any of the given strings.
Name_like_ Returns all SLAs whose name contains the given strings.
_order_ A comma-delimited list of field names to specify the result set sort order. For each field, the direction of the sort must be defined by appending:
_asc_ Ascending
_desc_ Descending
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Sla/{id}

Description
Retrieves information about an SLA.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Sla/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.

GET /Sla/schema

Description
Retrieves a description of the SLA object.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Sla/schema
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Name string

Name of the SLA.

GET /Timezone

Description
Lists all Timezones that matches the provided query.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Timezone
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_pageSize_ Number of results per page.

Default: 25
_startPage_ The page number to return.

Default: 1
_token_
required
Authentication token.
_total_
false Return the results set.
true Return only the count of the results set.

Mutually exclusive with _startPage_ and _pageSize_.

Default: false

GET /Timezone/{id}

Description
Retrieves information about a timezone.
URI Structure
https://{hostname}/api/v1/{account id}/{department id}/Timezone/{id}
Method
GET
Request Body
None
Parameters
_output_ Output format.
rss
json

Default: xml
_token_
required
Authentication token.
Returns

Field Descriptions

field description
Abbreviation string

Timezone abbreviation.
Timezone string

Name of the timezone.

Appendix

In List

In addition to filtering a list by a single value, you can specify a set of values, separated by commas. When more than one value is specified, the API interprets the query search criteria as Field = value1 OR Field = value2 OR Field = value3, etc.

This is supported for all field types except for boolean.

IS NULL / IS NOT NULL

In addition to filtering a list by an exact value match, you can specify whether the field contains a value.

_IS_NULL_
Returns all objects where the specified field does not contain a value.
_IS_NOT_NULL_
Returns all objects where the specified field contains a value.