The Tickspot API and command-line cUrl

Sometimes you want to pull some basic data without writing a bunch of code and that’s where command-line cUrl is super handy.

Let’s try it out!

Currently at VIA, we use Tickspot for time-tracking. Since we do most of our billing hourly, accurate time-keeping is pretty important to our process and Tickspot is a good solution (Note: they didn’t give us anything for writing this post).

As a bonus, they have a nice API which enables us to build things on top of Tickspot (like a custom reporting engine or an estimation tool).

Accessing the Tickspot API from command-line goes like this:

Authenticate

curl -u "email@domain.com:password" \
-H "User-Agent: TickTesting (email@domain.com)" \
https://www.tickspot.com/api/v2/roles.json

Let’s break the above down a little bit.

-u "email@domain.com:password" authenticates you with the API using *Basic Authentication*. You should use your Tickspot email address and password.

-H "User-Agent: TickTesting (email@domain.com)" adds an HTML header with the *User Agent* for your request. This header is required with every request and should always be in the form NameofApp (tick-user-email-address).

The above call will return a JSON array containing all Tickspot subscriptions for the specified user and an *Authorization Token* for future requests.

[
{
"subscription_id": 12345,
"company": "My Company",
"api_token": "nDRE9v2SwkEE6PLfyJhmk3BrnDRE9v2S"
}
]

In most situations, you’ll only get back a single company but be aware that it’s possible to get multiple results back.

Call an API endpoint

To call the other API endpoints, you need the *subscription_id* and the *api_token* from above.

For example, to get the list of projects for the company:

curl -H "Authorization: Token token=nDRE9v2SwkEE6PLfyJhmk3BrnDRE9v2S" \
-H "User-Agent TickTesting (email@domain.com)" \
https://www.tickspot.com/12345/api/v2/projects.json

Notice that we send two separate HTML headers. One with the same *User Agent* stuff we had in the authentication request, plus an additional header containing the *api_token* value.

The API endpoint url also contains the *subscription_id* for the company we’re querying.

Pagination

Most endpoints only return the first 100 results. You can request more data by appending a page= (page=2, page=3, etc) query string parameter to the endpoint url. The API will return an empty response when there is no more data to retrieve.

That’s it, now take a look at some of the other endpoints

It’s that simple.

There are lots of other endpoints for retrieving and adding data and they all work the same way.

Happy coding!