API Overview
General Purpose of the Safe API
Tracker clients will generally use the API for the following tasks.
- POST or GET system User Accounts (User Admin)
- POST or GET Case information
- POST or GET Person information
- GET new Items information
- GET updated items information
- GET chain of custody information for items
We do not support injecting item information via the API. Items must always be created via the Item entry or Data Import areas. The reason for this is that Chain of Custody is only able to be properly recorded when a user is logged in. We only register 'API User' when data is injected via the API in any form.
Requirements for each API request
Each request made to the SAFE webAPI will require the following
- Valid URL (from list of available URLs below)
- User Token
- Valid OrgID # (See instructions below for getting this)
- Valid Office ID # (See instructions below for getting this)
Getting a valid User Token
- Go to Settings -> Users
- Select a user in which to create a static token for, and select ‘Edit’ (Or you may want to create a new user for this process)
- At the bottom of the edit screen will be the token create section:
- Press ‘Generate’ to create the token.
If you created a token for the currently logged in user, then you must logout before using the token.
Setting a Static License
In most cases, you are going to want to peg a license to the user that was created in the previous step. This will ensure that a license is available when the interface makes a call to the SAFE webAPI. If not license is available, then the API will respond with a message that no licenses are available.- Go to Settings > License Allocation
- In the column ‘Reserved for Individual Users’ find the user you created for the API and then select the ‘No’ value to set a license.
What is your Org / Office ID
From within the SAFE interface, go to Settings > Offices to see your Org and Office ID.How often should you POST or GET data
Making an API call to the database more than once a minute may cause your account to be disabled. It is highly recommended that you make (or schedule) your call every 10 minutes or so. Please contact Tracker support if you need to POST or GET more often. What we are trying to avoid here is pulling data from the API on a constant basis when not needed. If you are posting data and it happens quickly that is not a problem.
Testing the Tracker API
- Use Postman in Chrome (or any similar tool). The following example is using Postman:
- Header Fields
- Accept application/json – required field
- Content-Type application/x-www-form-urlencoded – required field
- Authorization – This field requires the word ‘Bearer’ followed by a single space and then the static token that was created.
- OrganizationId – the organization ID to use
- OfficeId – the office ID to use
- StaticToken – tells the API that the bearer token is static
- Once these fields are in place, select ‘Send’ and verify that an item was returned (if one exists).
make sure you have a valid item in the system before you try to select one from the webAPI or you will get no results and it might look like something is wrong.
POST or GET Data from API
Retrieving Item Data (Including Item Updates)
This API endpoint allows for polling of all items (and updates) in the system in sequential order. Every item, or update, will be applied an ascending ID number. Program your system to poll for ID 1 and continue until you do not get a response. Once there is no response you will store the last ID that was good and start at that number for your next pool. With this you are always keeping up with new items and updates to those items.
API URL = https://securelb.trackerproducts.com/api/items/seqOrgItemHistoryId/X
Where X = SeqOrgItemHistoryID of item
Type GET
Important Objects Returned
- SeqOrgItemHistoryID: This is the ascending ID for each item and update. Start with1.
- historyType ["Create" or "Update"] Create being a new entry and Update being a update to the item.
Retrieving Specific Case Data
API URL = https://securelb.trackerproducts.com/api/cases/getByNumber?value=X
Where X = Case number entered into the system by the user.
Retrieving People in a Case
Where X = the "PrimaryCaseID"
FYI - The API for Retrieving Specific Case Data will be need to also be used so that you can get the PrimaryCaseID to enter into this URL.
Type GET
Retrieving Chain of Custody
API URL = https://securelb.trackerproducts.com/api/items/X/coc
Where X = the "id" value of the item which is provided in the SeqUpdateOrgID
Important: Do NOT use any nested ID's, use the root level ID.
Type GET
Case Data Post
This API controller is used for posting new Case records to the system. API URL = https://securelb.trackerproducts.com/api/cases
See example page for all necessary info to submit to this endpoint.
Type POST
Person Data Post
This API controller is use for posting new Person, Address and Entry to Case. API URL - https://securelb.trackerproducts.com/api/people
See example page for all necessary info to submit to this endpoint.
Type POST
Retrieving People in a Case
API URL = https://securelb.trackerproducts.com/api/cases/X/peopleList/
Where X = the "PrimaryCaseID"
FYI - The API for Retrieving Specific Case Data will be need to also be used so that you can get the PrimaryCaseID to enter into this URL.
Type GET