Getting Started

Let's walk through core API concepts as we tackle some everyday use cases.


Doing anything with the API requires authentication. The API will return a 401 Unauthorized for Unauthenticated clients.

The API uses tokens to authenticate every request. See the Token section below for more information.


Applications that need to read or write information using the API are required to use Tokens.

Tokens provide two big features:

  • Revokable access: users can revoke authorization to third party apps at any time

  • Limited access: users can review the specific access that a token will provide before authorizing a third party app

The API requires two tokens to be passed with every call:

  • Ocp-Apim-Subscription-Key: Subscription key which provides access to this API. Found in your Profile.

  • TT-Api-Key: TruTac Api Token. See documentation for futher details.

The Ocp-Apim-Subscription-Key is provided upon request, whereas the TT-Api-Key can be created via the TruControl portal.

Hello World

Most applications will be wrapped in the language of your choice, but it's important to familiarize yourself with the underlying API HTTP methods first.

There's no easier way to get started than through cURL.

Let's test our setup. Open up a command prompt and enter the following command:

# POST /drivers/v1/api/drivers-search
curl POST ""
-H "TT-Api-Key: {TruTac Api Key}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"
--data-ascii "{}"

Which should return something like the following:

"id": "123456-7890-1234-567890",
"username": "harry.fellowes",
"lastName": "FELLOWES",
"firstName": "HARRY",

There's quite a lot going on in this one little call, so let's break it down. Firstly this is a POST call to the drivers-search API. The -H flag indicates we're adding a request header, you'll notice that we are adding two request headers, that's because every call to the API requires both a subscription key and an authentication key, see the Token section above for more information.

Ordinarily we would also submit some additional parameters in the request body. Here we are leaving the parameters blank by submitting --data-ascii "{}"

In this case the response is a list of Drivers.

Now that we've got the hang of making authenticated calls, let's move along to the APIs.

Drivers API

All of the APIs have been designed to be as simple to use as possible. In the case of the Drivers API we can use a POST command to fetch a list of Drivers in the same way that we did earlier:

curl POST ""
-H "TT-Api-Key: {TruTac Api Key}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"
--data-ascii "{}"

As the Discovering the APIs section will indicate, some of the methods take additional parameters. In the case of the Drivers API there are a range of optional parameters that allow the API to return more OR less data

By default the Drivers API excludes any records that are marked as No Longer Working For us. Using the includeDriversNoLongerWorkingForUs parameter allows us to request that the API includes these records.

curl POST ""
-H "TT-Api-Key: {TruTac Api Key}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"
--data-ascii "{includeDriversNoLongerWorkingForUs: true}"

Note the quoted URL above. Depending on your shell setup, cURL sometimes requires a quoted URL or else it ignores the query string.

Woot! Now you know the basics of the API!

  • Authentication

  • Fetching Drivers

Keep learning with the next API guide Basics of Authentication!