Home

TrackAbout API Documentation

This is our in-depth documentation, for an overview of API endpoints please see our Interactive API Reference.

Getting Started

The TrackAbout API provides a REST interface for sending data to TrackAbout, retrieving data, and recording user activity (creating records). This documentation includes requirements for using the API, descriptions of API formats and patterns, and guides and examples for common API interactions.

New API clients will need a TrackAbout test environment, a user account, and an API key. Contact TrackAbout support if you have any questions about this. Please read this entire document thoroughly before starting implementation.

HTTP vs. HTTPS

All requests must be made using https. The TrackAbout API will not respond to requests made using an http URL.

User-Agent

All API clients should send a User-Agent HTTP header to identify the software and/or device making the request. TrackAbout may log the User Agent header and use it for metrics and support requests. This header will be required unless special arrangements are made with TrackAbout.

Ideally, the header value should include a list of product tokens that identify the client application, listed in order of importance. For example:

Client application name and version
Operating system name and version
Device name and version, if the application is running on a mobile device or other non-PC hardware

Each product token should be the the name of the software or hardware, followed optionally by a slash and the version or build number. Tokens are separated by spaces, and there should be no spaces within individual tokens. It's also possible to provide comments between parentheses if needed.

Here are some examples of well-formed User Agent strings:

MyMobileApp/1.2.3 iOS/6.1 iPhone/4
MyEnterpriseMiddleware/Build-1234 (For TrackAbout release AWS0123; 2013-07-23) ERPSystemX Solaris/11.1

For those interested, RFC 2616 provides detailed specifications for the recommended syntax of User Agent strings.

Security

As mentioned above, all requests must be made using HTTPS. Therefore all requests are safely encrypted using SSL.

Data Integrity

All requests made are safely wrapped in database transactions. Meaning if there is an unrecoverable error, for example if the connection was dropped, during the request and/or processing, the database will safely rollback any data changes to avoid inconsistent/invalid data.

REST Concepts

Request Methods

REST APIs use standard HTTP methods to describe the type of action to take against the resource identified in the request URI. As such, the TrackAbout API follows the standard semantics of these HTTP methods:

GET is for retrieving data without modifying the state of the system
POST is for creating new resources, or for other general operations that have significant side effects
PUT is for updating the state of an existing resource. The body of the request is intended to fully describe the intended state of the resource
PATCH allows for partially updating a resource. In a typical patch request, all of the fields in the request body are optional. Only the fields included in a specfic request are updated, and other properties of the resource remain unchanged. Where allowed, sending a field with an empty string or array value will clear the value of that property in TrackAbout

Idempotency

An idempotent request can be re-sent any number of times and have the same effect. For example, a GET request repeated with the same URL and parameters will retrieve the same data (assuming the underlying state of the data does not change), and a PUT or PATCH request repeated with the same URL and body will result in the identified resource having the same state.

POST requests are defined as being non-idempotent. A simple example is a request for creating a new resource; repeated POST requests will create multiple instances of resources with different unique IDs, or repeated requests may fail due to uniqueness requirements. In the TrackAbout API, some other requests are defined as POST because of significant side effects, such as creating records or modifying asset history.

Interactive Documentation

The TrackAbout API offers an interactive documentation page. Anonymous access is available, but to enable interactive features you will first need to log in to TrackAbout using your TrackAbout credentials.

The documentation describes each API operation, sorted by URI. For each operation, you can view:

The URI and method (GET, POST, etc.) of the operation
A description of the operation
The structure of the request body (if applicable) and response body (click the Model Schema links to view sample JSON)
Descriptions of URL parameters

Note that the base URL for every API operation is /api; ensure that all of the URLs you form in your web service client have this base path.

The documentation is interactive in that you can send test requests to most endpoints from within your web browser. If the request takes URL parameters or requires data posted in the request body, enter appropriate values into the text boxes for each parameter. For requests that require data in the request body (e.g. most POST requests), you can click the Model Schema link in the request body description to see a JSON sample, and you can click on the JSON sample itself to copy it to the text box as a template for the request body you will send. Once you’ve entered the necessary values, click the Send Request button to send the request and view the response headers and body.

Note that the interactive documentation automatically uses your TrackAbout web site session to authenticate your test requests. To construct requests programatically, you will need to add authentication headers as described below. Furthermore, the requests being sent are both validated and processed by the server. Sending non-GET requests will result in created and/or modified data.

Formats and Encoding

The TrackAbout API only supports JSON for requests and responses at this time. All requests should either have the request header Accept: application/json, or have format=json as a query string parameter. When sending data in the request body for a POST or PUT request, send the data in JSON format and add the request header Content-type: application/json.

The Sample Requests at the end of this document show examples of correct usage of request headers.

UTF-8 Encoding

Every string passed to and from the TrackAbout API needs to be UTF-8 encoded.

Response Compression

The TrackAbout API supports compression for most responses. To request a compressed response, include the Accept-Encoding header. The API supports gzip and deflate encoding schemas. For example:

Accept-Encoding: gzip,deflate

Request Compression

The API also has limited support for compressed request body content in POST/PUT/PATCH requests. Only the gzip encoding schema is supported. Compress the entire content of the request body and include the header Content-Encoding: gzip in the request.

Basic Data Types

The following table describes each of the basic data types used by the API and how they are identified by the interactive documentation:

Data Type	JSON Format/Range
byte	0–255 (unsigned)
boolean	`1`/`0`/`true`/`false`
int	32-bit integers
long	64-bit integers
float	32-bit floating point
double	64-bit floating point
string	`"value"`
Date	`yyyy-mm-ddThh:mm:ssZ`
Array	`[value1, value2, ...]`

Date Format

The recommended format for date/time values is ISO 8601 combined date and time format. Unless otherwise specified, all date fields should include both a date and time value. Time values should be sent in UTC using the "Z" or "+00:00" time zone designator. Requests sent in without a timezone specified will be rejected with a 400 Bad Request.

Date-only fields will provide a format string to indicate how they should be strucutured. They will be interpreted with the headquarters' timezone.

Here is an example of an acceptable date value for TrackAbout API requests and responses:

2013-06-21T09:41:08Z

String Value Restrictions (Enumerated Values)

Some string values in the API represent enumerated types: they are restricted to a set of known values. The interactive documentation will list the allowed values when possible. For example, the orderType field in some of the Orders endpoints is documented like this:

orderType (string) = ['CustomerDelivery' or 'BranchTransfer']

The request JSON should look like this:

{ "orderType": "CustomerDelivery", ... }

If you send value that is not one of the accepted values, the request will fail with status code 400.

Validation

Most APIs perform basic validation before the request is processed and will return a 400 error code if any validation fails. The response body will contain information as to what field or fields failed and why. For an example, see the 400 status code in the status code section below.

When working with an API for the first time, you can browse the associated validation and required fields directly by going to the validation documentation. This avoids having to send a "dummy" request to the API and receive the validation errors.

Authentication

The TrackAbout API supports Basic Authentication and Token Authentication. Each request must include valid HTTP headers that identify the user with one of these authentication methods. Basic Authentication is appropriate for batch requests or other low volume activity from automated systems; for example, synchronizing order data with a client accounting system. Token Authentication is appropriate for high volume requests or applications in which a human user athenticates using TrackAbout credentials.

Basic Authentication

A special web services user account should be used for basic authentication. You will also need a TrackAbout API Key. Ask TrackAbout Support for help setting these up.

Each request must include two HTTP headers: X-API-Key and an Authorization header. Use the former header to provide the TrackAbout API Key with every request:

X-API-Key: 950384A9-12DB-43B8-A8BB-DC8095CE2A3A

The value of the Authorization header consists of a valid username and password, concatenated with a colon, like this:

user1:password1

This combination should then be base64 encoded, resulting in something like:

dXNlcjE6cGFzc3dvcmQx

An example of a request with the necessary Basic Authentication headers would thus be:

GET https://test.trackabout.com/api/locations HTTP/1.1
Host: test.trackabout.com
X-API-Key: 950384A9-12DB-43B8-A8BB-DC8095CE2A3A
Authorization: Basic dXNlcjE6cGFzc3dvcmQx
Accept: application/json

Token Authentication

With Token Authentication, the client sends a single request to the tokens API endpoint, which validates a human user's credentials and returns a unique token that can be used for identifying future API requests without resending the password. For Token Authentication, you will need a TrackAbout API Key. Ask TrackAbout Support for help setting this up.

To generate and retrieve a token:

POST https://test.trackabout.com/api/tokens/basic HTTP/1.1
Host: test.trackabout.com
Accept: application/json
Content-type: application/json

{
    "username": "user1",
    "password": "password1",
    "apiKey": "AC967D07-327D-410E-A579-C856CAC2A8EA",
    "applicationInstanceId": "12345ABCDE"
}

The apiKey is provided by TrackAbout, and identifies your client application. The applicationInstanceId value is generated by the client and is meant to uniquely indentify a specific installation of the client application on a particular machine or device. For example, if this is a mobile app deployed to a rugged device or smartphone, the same API key would be used for all instances of the app, and the applicationInstanceId should be unique for each device it is installed on. If it's a console application running on a server, a single ID value is sufficient.

If the username and password identify a valid user, the response would look like this:

{
    "token": "VGhpcyBpcyBhIHNhbXBsZSB0b2tlbiBzdHJpbmcu",
    "expires": "2013-08-07T20:45:32.8892477Z"
}

The token value should be used in all subsequent requests to the API to identify this authenticated user, using the X-Token HTTP header. For example:

GET /api/locations HTTP/1.1
Accept: application/json
X-Token: VGhpcyBpcyBhIHNhbXBsZSB0b2tlbiBzdHJpbmcu

This token can be reused, as long as it's not expired, for the length of time that the given user is logged in. Tokens should not be reused over mulitple applicationInstanceIds. The X-API-Key header is not required when using token authentication because the API Key is embedded in the token value.

Impersonating a User

For requests that create records in TrackAbout, such as a load truck action, you can authenticate as one user (typically a shared web service user) and create the record using the identity of a different user (the human user actually performing the business activity). Specify the user to impersonate with the X-Impersonate-User header, in addition to supplying the primary credentials as described above. There are multiple ways to identify the user to impersonate, as determined by a second header X-Impersonation-Method.

To identify a user by TrackAbout username:

X-Impersonate-User: username1
X-Impersonation-Method: Username

To identify by Accounting User ID (an identifier that can be registered in TrackAbout to match a user’s identity as stored in an external system):

X-Impersonate-User: accountingSystemIDabc
X-Impersonation-Method: AccountingUserId

To use this feature, the API endpoint must support impersonation, and the user with which you are authenticating must have the correct permissions assigned in TrackAbout. If you receive a 403 Forbidden error response, the error message may indicate that the endpoint does not support impersonation or that your API user does not have permission to perform impersonation. Please contact TrackAbout Support to resolve permissions issues.

Standard Patterns

The TrackAbout API makes use of a few standard patterns you will find across multiple endpoints.

Response Envelope

Many requests will return a list of items. The list is wrapped in a response object with a total-rows field, as seen below. This is useful when you are working with paging functionality and the response is a subset of the total result set.

Sample response from truck endpoint. Notice that there are 50 total rows but only 3 are currently returned:

{
    "totalRows": 50,
    "rows": [{
            "tId": 456,
            "name": "Little Red Truck"
        }, {
            "tId": 123,
            "name": "New Truck 1"
        }, {
            "tId": 789,
            "name": "New Truck 2"
        }
    ]
}

TId and MId

Many resources in the TrackAbout Api can be identified with multiple IDs depending upon who "owns" the data. To avoid ambiguity in these cases, TId and MId are used. The TId ("TrackAbout ID") represents the ID that TrackAbout uses internally for the resource. The MId ("Master Id") represents the ID that the accounting or backend system uses for the resource. When identifying a resource in a request body, the resource will often be represented as an object with both types of identifiers. Only one is required, and if both are supplied, the TId is preferred. For example, the customer and originLocation resources are identified in two different ways in this POST request:

{
    "orderNumber": "ORDER123",
    "customer": { "tId": 85 },
    "originLocation": { "mId": "Location456" },
    ...
}

Reference Objects

When a response contains information about an object that has its own API endpoint, only minimal information will be returned about this referenced object. This is to keep performance high and to encourage making a second request for that object's data instead of returning everything in one large "data dump". The standard design of these reference objects is to return the tId, name, and mId for the object. This tId is provided to allow querying of the resource directly and the name and mId are provided for context.

Below is an example of the response from the assets endpoint for an individual asset. Notice how only the tId, name, and mId are returned for the referenced customer object.

{
    "rows": [
        {
            "customAssetProperties": [],
            "customer": {
                "tId": 12269,
                "name": "John Doe",
                "mId": "Doe"
            },
            "tId": 123,
            "tag": "456"
        }
    ],
    "totalRows": 1
}

Paging

Requests that have the potential for a large number of results support paging. Requests that support paging note this in their associated documentation on the docs page. There are 3 query string parameters that control the result set.

Paging determines whether or not paging is enabled. This must be set to true to use the other options. The default setting is true because non-paged results can take a much longer time to run and can create very large responses.
Page determines the specific page of data that the request would like. Page 1 indicates the first page.
PageSize determines the number of rows to return per page. The default is 50. Note that requesting larger page sizes can negatively impact the performance and greatly increase the response size.

Record-Saving APIs

A variety of POST endpoints are designed for creating records (in other words, saving actions) in TrackAbout. These APIs have a number of common elements:

Dates: the userEntryEndDate is the effective date of the record, typically the date/time at which the user finished the action. userEntryStartDate is the start date of the record, the date/time at which the user began
Assets: most record saving APIs require one or more assets or hard goods. Unique assets typically have fields for tag and serialNumber, usually only one is required. An asset's timeEntered is the date/time at which the asset was scanned or recorded for the action. Assets may have additional fields as relevant to the specific type of record
Dynamic Forms: to utilize TrackAbout's Dynamic Forms feature, use the dynamicFormEntries field. Each element in the array represents the value of a single form field entered by the user. Consult TrackAbout support for assistance with this feature.

Custom Properties

Custom Properties are name-value pairs describing additional client-specific information for a resource. In some GET requests, custom properties can be requested by listing the TIds of the custom properties in a query string parameter. The response will include a list of the names, TIds, and values for each requested custom property that is defined for the given resource.

To determine the list of custom property types available, there are various API endpoints with paths ending in names such as customPropertyTypes. These GET requests return the names and TIds of the custom properties that are applicable for a specific type of resource. For example, this request:

GET /api/assets/customPropertyTypes

Will return a list of custom properties available for the given client that are applicable to asset-related APIs:

{
  "totalRows": 2,
  "rows": [
    {
      "tId": 3,
      "name": "Manufacture Date"
    },
    {
      "tId": 10,
      "name": "Valve Type"
    }
  ]
}

These TIds can be used in the query string of appropriate API endpoints; for example:

GET /api/assets/tagged/12345?customAssetPropertyTypes=3,10

The response will include a list of the properties that are defined for the given asset:

"customAssetProperties": [
  {
    "propertyTypeTId": 3,
    "name": "Manufacture Date",
    "value": "12-2011"
  },
  ...
]

Some requests also accept a similarly structured list of custom property TIds and values in the request body, in order to update these values for a given resource; for example:

POST /api/customers/batch

Allows custom properties to be sent in the request as follows:

{
  "items": [
    {
      "mId": "CUSTOMER1",
      "name": "CUSTOMER1 Name",
      "customProperties": [
        { "tId": 4, "value": "custom value" },
        { "tId": 7, "value": "123" }
      ]
    }
  ]
}

Batch Requests

Some API endpoints have a POST /api/some/path/batch request variation that supports batch processing. Batch requests are useful for creating or updating a large number of entities in TrackAbout, such as for synchronizing data from an accounting system. Batch endpoints use a common pattern for request and response body structure, and typically have some shared processing steps, response semantics, and HTTP status codes.

Request Body

A batch request body is simply a wrapper around a corresponding PUT or POST request for a single entity. For example, the PUT request to create or update a single pending order looks like this:

PUT /api/orders/pending/ORDER1
{
    "orderType": "CustomerDelivery",
    "customer": { "mId": "CUSTOMER1" }, ...
}

The batch request for pending orders uses the same structure, repeated in a list:

POST /api/orders/pending/batch
{
    "items": [
        {
            "orderNumber": "ORDER1",
            "orderType": "CustomerDelivery",
            "customer": { "mId": "CUSTOMER1" }, ...
        },
        {
            "orderNumber": "ORDER2", ...
        }, ...
    ]
}

Note that the verb for a batch request is always POST, even though in this case the single-entity request uses PUT.

Batch Request Processing

Batch API endpoints are typically designed to allow continuing processing if some items in the batch fail validation or cause business logic violations. Each item in the batch request is validated separately, and any items that fail validation are not further processed, and the validation failure is reported in the response. However, there are some checks that will cause the entire request to fail with a 4xx status code: insufficient permissions, empty request, request with too many items, invalid JSON syntax, etc.

Batch requests are processed synchronously; the server will not return a response until all items are processed.

Response Body

All batch API endpoints have the same response structure:

200 OK
{
    "items": [
        {
            "status": "Success",
            "identity": "ORDER1"
        },
        {
            "status": "Failed",
            "identity": "ORDER2",
            "errorCode": "ValidationFailure",
            "errorMessage": "Customer is required"
        }
    ]
}

The items list in the response will have one element for each item in the request. The status property indicates whether the item was successfully processed, and the other properties help to identify the item and any errors encountered.

Note that the status code for this response is 200 OK, even though there are some validation errors: this means that the batch request as a whole was understood and the server was able to attempt processing every item. Non-200 responses only occur when the entire request is rejected, as described further above, or when there is an unexpected runtime error.

Status Codes and Errors

Each response from the TrackAbout API will include a standard numeric HTTP status code that describes the overall result of the operation. The response body may include more details about the result of the operation or any errors encountered. Status codes in the 200–299 range indicate success, 400–499 indicate a problem with the content or meaning of the request that the client provided, and 500–599 indicate a problem with the server.

200 - OK

This is the generic status code for a successfully processed request.

201 - Created

The resource was successfully created as requested. The response may contain information about the newly-created resource. This is only returned for POST requests.

204 - No Content

The request was successfully processed, and the response body is empty. This may be returned for some PUT or PATCH or DELETE requests where there is no additional information to return.

400 - Bad Request

There is either a problem with the formatting of the json or it may not have passed basic validation rules. For example, when sending the following request:

POST https://test.trackabout.com/api/trucks/123/assets/loadedAt/987 HTTP/1.1
...

{
    "userEntryStartDate": "2013-04-23T18:58:17Z",
    "userEntryEndDate": "2013-04-23T19:05:16Z",
    "assets": {
        "tagged": [
            {
                "timeEntered": "2013-04-23T18:59:03Z"
            }
        ]
    }
}

The response returned may be similar to the following. Notice how it is indicating two errors with the request.

The first asset did not have a tag or serial number associated with it
The location tId specified in the url (987) does not exist in the system.

HTTP/1.1 400 ValidationFailure
...

{
    "responseStatus": {
        "errorCode": "AssetMustBeIdentified",
        "message": "Either the tag or serial number must be specified for each asset.",
        "errors": [
            {
                "errorCode": "AssetMustBeIdentified",
                "fieldName": "Assets.Tagged[0].Tag",
                "message": "Either the tag or serial number must be specified for each asset."
            },
            {
                "errorCode": "InvalidLocation",
                "fieldName": "LocationTId",
                "message": "This field must identify a valid location"
            }
        ]
    }
}

401 - Unauthorized

The credentials supplied for the request are either incorrect or invalid or missing. Refer to the authentication section above for instructions on setting this up.

403 - Forbidden

You do not have the appropriate permissions to perform the attempted operation, or the types of credentials provided are not supported for that operation. The response may contain the permissions that you require. Contact support for configuring permissions.

404 - Not Found

The API endpoint does not exist, or a resource identified in the URL does not exist, or the URL is malformed. If the URL contains a parameterized value, make sure that you are correctly setting the value.

406 - Not Acceptable

The resource you are requesting is not available in any formats you supplied in the Accept request header. The response contains information on accepted formats.

422 - Unprocessable Entity

The request is well formed, but was unable to be completed or validated due to business logic constraints, missing data, etc. For example, a value provided in the request body (such as a barcode or lot number) does not match a pattern required by business rules configured for the client, or a resource identified in the request body (such as for a location or customer) does not exist in the TrackAbout system.

500 - Internal Server Error

There was an unexpected problem processing your request. Please contact TrackAbout Support if the problem persists.

Sample Requests

Note: Depending on what client you’re using to form HTTP requests, you may need to put two carriage returns after the headers in a GET request to signify an empty request body.

Get a List of Trucks

In this example, the TIds and names of all “truck” locations are returned in the response.

Request:

GET https://test.trackabout.com/api/trucks HTTP/1.1
Host: test.trackabout.com
X-API-Key: 950384A9-12DB-43B8-A8BB-DC8095CE2A3A
Authorization: Basic dXNlcjE6cGFzc3dvcmQx
Accept: application/json
Connection: close

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Apr 2013 18:53:32 GMT
Connection: close
Content-Length: 127

{
    "totalRows": 3,
    "rows": [{
            "tId": 456,
            "name": "Little Red Truck"
        }, {
            "tId": 123,
            "name": "New Truck 1"
        }, {
            "tId": 789,
            "name": "New Truck 2"
        }
    ]
}

Perform a Load Truck

In this example, a Load Truck record is created with 2 tagged assets and 1 not scanned asset, for truck TId 123 and branch location TId 72. The response contains a confirmation message and record ID.