Introduction to the Developer API

Notice: This service is currently in beta.  Please send bug reports or questions to support@trackops.com.

Overview

Trackops currently offers a limited REST API to programmatically access various data throughout the system, and optionally connect your Trackops data to other 3rd party services.  Keep in mind that while we are excited to offer API functionality to our customers, it is your responsibility to respect our usage restrictions and responsibilities.  Please be a good API citizen and do not abuse or misuse API functionality.  If at any time, we determine that you are abusing API privileges, we reserve the right to suspend or permanently revoke API access.

Note: The API is currently only available in Read-Only mode.  We do not have an ETA on when the API will be able to be used for creating/importing new data.

Access Points

Accessing the Trackops REST API is as simple as activating API access, and connecting to a fully qualified API end point via the subdomain on your account.  

Example Access Point (getting a client list):

https://{subdomain}.viewcases.com/api/v1/clients

Authentication

The Trackops API is an SSL-only API, meaning that non-SSL connections are not allowed.  Access to the API requires a active Full Access employee username, and your company API Token.  Accessing the API on behalf of a Limited Access employees or client contacts is not permitted.

Authentication takes place in the form of a specially formatted username in the form of "{username}/token", in conjunction with an API token.

Example of basic authentication:

{username}/token:{api_token}

Note: History logs will be recorded using the user information that corresponds to username supplied.  If you need to specifically identify API activity, it is best practice to perform API calls using a separate Full Access employee account that is easy to identify as such.

If you aren't sure how to connect to the Trackops API, we recommend the use of cURL.  cURL is a common cross-platform tool used to connect to transfer data through various protocols.  

Generic Example using cURL:

curl -u {username}/token:{api_token} https://{subdomain}.viewcases.com/api/v1/...

Specific Example using cURL (fetching a client list):

curl -u samspade/token:d29d3136-1251-5041-9e1c-428c77edb64d https://mycompany.viewcases.com/api/v1/clients

Rate Limiting

This API is rate limited, meaning that you must throttle your requests.  Currently, you cannot perform more than 1 request per second.  If too many requests are made at once, you will receive an HTTP 429 Too Many Requests response, along with the supporting error message.

Tip: If you routinely require access to many records at once for reporting or other purposes, it is best practice to routinely cache new and updated records to a local data store.  For more information, please read about Caching Collection Data below.

Responses

All responses from the API are returned in JSON format.  A typical response will contain a 200 OK status, indicating a successful response.  Should an error occur, the response will contain standard HTTP Status Codes to indicate the problem.  In most cases, the response will also include an error message or other information to provide more insight about the error.  This most common error is 404 Not Found, indicating that the URL you are attempting to access is incorrect or has a typo.

Note: All responses that include dates with time (i.e. timestamp fields) are served in UTC.  It is up to you to convert times to your own timezone if so desired.

Collections

Collections are responses that include multiple records.  To improve performance and manageability, collections are limited to 100 records per page.  You can use the per_page request parameter to limit results to a smaller number, and the page parameter to jump to a specific page of the results.  

Tip: If a collection is empty, or the amount of records returned is less than the per_page parameter, this indicates there are no more records to fetch based on the specified search criteria.

Collection results can also be sorted in ascending (asc) or descending (desc) order through the use of the dir parameter.  By default, collections are always returned in descending order (newest records at the top).

As an alternative to returning the records themselves, you can opt to return the record count (total number of records found).  To do so, simply append the mode parameter with the value of "count" to your query.

Example of a Collection Sorted by Direction (sorted ascending)

curl -u {username}/token:{api_token} "https://{subdomain}.viewcases.com/api/v1/case/updates?dir=asc"

Example of a Collection Count (number of invalid updates)

curl -u {username}/token:{api_token} "https://{subdomain}.viewcases.com/api/v1/case/updates?is_valid=0&mode=count"

Searching Collections

Using request parameters, you can filter your requests to return a specific subset of records.  Each request object has a specific set of available request parameters that can be used.  For more information on specific parameters available for a query, examine the documentation for the specific object you are interested in (listed under the Objects section below).

Note: All collection based queries recognize the per_page, page, and dir parameters.

Passing invalid request parameters to the resource will result in a 400 Bad Request response.

If your search query contains strings, they must be URL encoded for the API to properly parse them.

Example cURL Request with Parameters:

curl -u {username}/token:{api_token} "https://{subdomain}.viewcases.com/api/v1/clients?name=ACME+Insurance"

Caching Collection Data

The Trackops REST API is not designed to provide a live interface for your staff, customers, or otherwise from outside the standard Trackops user interface.  If you determine that you require data in large quantities, or in a more readily available fashion than the API provides, it is best practice to periodically cache/store your query results to a local store for future use.  

For example, if you routinely require access to thousands of records at a time in order to compile a report, it is best practice to periodically query (i.e. on a daily basis) and store the latest results in a local cache, database, or flat file storage so the information is readily available for your use case.

Official Client Libraries

For convenience, Trackops has created and maintains the following client libraries to speed up API integration:

Object References

To see specific request parameters available on the API query you are developing, please visit the reference page for the object of interest:

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request