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 do 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.
For questions or assistance related to the developer API, please contact support at support@trackops.com and we will be able to assist you with implementation specifics.
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 an 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).
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"
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 (e.g. 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.
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:
- Cases
- Case Contacts
- Case Flags
- Case Regions
- Case Reviews
- Case Services
- Case Statuses
- Case Status Changes
- Case Status History
- Case Types
- Case Updates
- Case Update Notifications
- Clients
- Client Locations
- Client Contacts
- Client Contact Notes
- Client Locations
- Client Notes
- Expense Entries
- Events
- Event Checkins
- Files
- Item Codes
- Invoices
- Invoice Payments
- Payment Slips (Expenses)
- Referral Sources
- Staff
- Staff Notes
- Subjects
- Subject Types
- Tasks
- Tracking Categories