No status

Overview

Basic API Information

To use the API you must first authenticate yourself. You will not be able to edit information you do not control when logged in to the standard web application.

The API is in early beta. It is recommended that you upgrade to the latest verison when it comes out.

Current Version

v0
12/28/2015

Guarantee

We make no guarantee about the stability of v0. Your applications may break at any time in the future. Use at your own risk. If you find any errors please contact us at support@mytractiontools.com

Making a Request

Generating a Token

To interact with the API you'll need to request a token. This is done with a post request to the server. Tokens are only valid for 2 weeks. After which, new one must be generated.

The post request requires three paramemters.

  1. grant_type which is always "password"
  2. userName which is your login email
  3. password which is your login password

The post request is delivered to https://traction.tools/Token. The following is a curl.

curl -i -X POST -d "grant_type=password" -d "userName=YOUR_USERNAME_HERE" -d "password=YOUR_PASSWORD_HERE" 'https://traction.tools/Token'

This will return json that looks similar to the following:

{
  "access_token":"qriivcbIB143adasdVuweqweasdVidi-wqfayefGFa63IiaJasdf325salo10asdf0vaxcve0awRUPph-KDSgqweascvoxzxf-OadsfIadoasdfoc-asdfic_qeisicpapdladsKdiadsioqwekl78VjptVop7aretuasdfkNQIOWNFO123459zxcvasdf6r9shB6BYpyowiGJLMHi3yB3Es5aAYQ2pGstqAJ58XNshdXlW4WhHsbxJ2ggO3hnX4yMKbv4ieEBuZNN7zA8n4KG676RyqfRx_MLUjdYCnslOqEGUf8Ole5a8krPX5EWLcs3qwDB6EH6Icc7Bk48hHdDMeuAn3s5kvGsBK14Fel7p228W9_bdXKhG9ylVZF7mjmcunTa7UijA2nX7pp60tcOVa4jkdZlyui6sqAejGHv-avB2L0n8fVpjHi8nVWlReG",
  "token_type":"bearer",
  "expires_in":1209599,
  "userName":"user@organization.com",
  ".issued":"Mon, 28 Dec 2015 07:05:37 GMT",
  ".expires":"Mon, 11 Jan 2016 07:05:37 GMT"
}

The access_token will be used in all future requests. Notice the token_type. It indicates that this access_token is a Bearer token.

Formating a Request

Once you have your Bearer token. You must add it to the header of all future requests.

Example: GET a listing scorecard items
curl -i -X GET -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" 'https://traction.tools/api/v0/scorecard/items/'

Scorecard

List of scorecard measurables

GET /api/v0/measurables/mine/

GET /api/v0/measurables/organization/

GET /api/v0/measurables/owner/USER_ID

This function gets a list of scorecard measurable.

mineGet your scorecard measurables
organizationGet scorecard measurables for your organization
USER_IDGet scorecard measurables for the specified user
curl -i -X GET -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" 'https://traction.tools/api/v0/measurables/mine'
[{Id:5,Title:"A measurable",GoalDirection:"GreaterThan",Goal:1,UnitType:"None",AccountableUser:{Id:123,Name:"John Doe",Username:"john.doe@organization.com"},AdminUser:{Id:345,Name:"Han Solo",Username:"han.solo@organization.com"}},{Id:7,Title:"Anothermeasurable",GoalDirection:"GreaterThan",Goal:10,UnitType:"Dollars",AccountableUser:{Id:123,Name:"JohnDoe",Username:"john.doe@organization.com"},AdminUser:{Id:123,Name:"JohnDoe",Username:"john.doe@organization.com"}},{...}]

Get a scorecard measurable

GET /api/v0/measurables/MEASURABLE_ID

This function gets a specific scorecard measurable.

MEASURABLE_IDThe scorecard measurable id
curl -i -X GET -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" 'https://traction.tools/api/v0/measurables/5'
{Id:5,Title:"A measurable",GoalDirection:"GreaterThan",Goal:1,UnitType:"None",AccountableUser:{Id:123,Name:"John Doe",Username:"john.doe@organization.com"},AdminUser:{Id:345,Name:"Han Solo",Username:"han.solo@organization.com"}}

List scores

GET /api/v0/measurables/MEASURABLE_ID/scores

Gets scores for a specific scorecard measurable.

MEASURABLE_IDThe scorecard measurable id
curl -i -X GET -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" 'https://traction.tools/api/v0/measurables/5/scores'
[{"Id": 31,"MeasurableId": 5,"ForWeekNumber": 2352,"Value": 1},{"Id": 32,"MeasurableId": 5,"ForWeekNumber": 2353,"Value": 1},{...}]

Edit a score

PUT /api/v0/scores/MEASURABLE_ID/FOR_WEEK

PUT /api/v0/scores/SCORE_ID/

This function sets a particular score. You must specify Content-Type: application/json

SCORE_IDScore id
MEASURABLE_IDThe scorecard measurable id
FOR_WEEKWeek id
bodyThe new value as a decimal
curl -i -X PUT -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" -H "Content-Type:application/json" -d '15.50' 'https://traction.tools/api/v0/scores/5/2352'

Current Week

GET /api/v0/week/current

This function gets the current week id.

curl -i -X GET -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" 'https://traction.tools/api/v0/week/current'
{StartDate: "2015-12-27T06:00:00Z",EndDate: "2016-01-03T06:00:00Z",ForWeek: 2401}

Users

List users at organization

GET /api/v0/users/organization/

Gets a list of all the organization's users.

curl -i -X GET -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" 'https://traction.tools/api/v0/users/organization/'
[{Id:123,Name:"John Doe",Username:"john.doe@organization.com"},{Id:345,Name:"Han Solo",Username:"han.solo@organization.com"},{...}]

List users you manage

GET /api/v0/users/managing/

Gets a list of all the users you manage.

curl -i -X GET -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" 'https://traction.tools/api/v0/users/managing/'
[{Id:123,Name:"John Doe",Username:"john.doe@organization.com"},{Id:345,Name:"Han Solo",Username:"han.solo@organization.com"},{...}]

Get a user

GET /api/v0/users/USER_ID/

Get information about a user.

curl -i -X GET -H "Authorization:Bearer YOUR_BEARER_TOKEN_HERE" 'https://traction.tools/api/v0/users/123/'
{Id:123,Name:"John Doe",Username:"john.doe@organization.com"}