API guidelines

Introduction

Our API provides a way to track time using HTTP post calls. Our widgets use this interface, but third-party developpers can also use this to write programs which interact with the TrackMyPeople engine. It can be used in any programming language with HTTP post & SSL support.

Authentication

We use http authentication over an ssl connection. You just have to provide your username and password.

API Functions

  • Syntax: https://secure.trackmypeople.com/api/function.$format/param1/value/param2/value
    $format should be one of the currently supported formats:
    • XML (default, so can be ommitted)
      Note: If you're passing parameters, the $format is obliged!
    • JSON
  • Note: the previous syntax is for GET-requests. Make sure that your urls are encoded if you use this syntax.
    It's also possible to use a POST-request. This has the advantage that you don't need to encode your parameters.
  • If a parameter is optional it's between brackets => [param]
  • All calls return a response with in the result tag either 1 if the action was successful or 0 if it failed (for example if user is already started when you call the start function)
  • Each XML response is surrounded by the root element 'api_response'.
  • The response might also contain an error tag, containing a more meaningfull error.
  • Each (create) action accepts optionally a version parameter (platform_version) which is used for statistics

We provide the following functions:

back to top  

Function : Trackers

This function lists all trackers the authenticated user can track for. These are all trackers where the user has a role which has the 'can track'-permission. The list is returned alphabetically and in tree form, iow preceeded by a number of arrows so you'd get an indented tree.

Response

View Live XML Example 
$tracker_name
$tracker_name
...
...
View Live JSON Example 
{
   $tracker_id: $tracker_name,
   $tracker_id: $tracker_name,
   ...
   ...
}

back to top  

Function : Status

This is a very usefull function. For example, using this you can determine what buttons to show (start or stop, etc...), whether a block is already opened when logging in through a widget, and so on...

Response

View Live XML Example 
1 (OR 0 = already started)
$day_total_all_trackers

   UNIX timestamp
   $tracker_day_total
   
      $last_blocks_tracker_id
      $last_blocks_tracker_name
      $last_blocks_tracker_abbreviation
      1 (OR 0)
   


   $default_tracker_id
   $default_tracker_name
   $default_tracker_abbreviation
   1 (OR 0)
View Live JSON Example 
{
   result: 1,
   daytotal: $day_total_all_trackers,
   last_block: {
      started_at: "UNIX timestamp",
      total: "$tracker_day_total",
      tracker: {
         Id: $last_blocks_tracker_id,
         Name: "$last_blocks_tracker_name",
         Abbreviation: "$last_blocks_tracker_abbreviation"
         Trackable: 1 OR 0
      }
   }
   default_tracker: {
      Id: $default_tracker_id
      Name: "$default_tracker_name"
      Abbreviation: "$default_tracker_abbreviation"
      Trackable: 1 OR 0
   }
}

back to top  

Function : Start

Starts a new block for the authenticated user. If no tracker_id is passed, the user's default tracker will be taken.

Parameters

[tracker_id]

Response

View Live XML Example 
1 (OR 0 = already started)
$day_total_all_trackers

   UNIX timestamp
   $tracker_day_total
   
      $last_blocks_tracker_id
      $last_blocks_tracker_name
      $last_blocks_tracker_abbreviation
      1 (OR 0)
View Live JSON Example 
{
   result: 1,
   daytotal: $day_total_all_trackers,
   last_block: {
      started_at: "UNIX timestamp",
      total: "$tracker_day_total",
      tracker: {
         Id: $last_blocks_tracker_id,
         Name: "$last_blocks_tracker_name",
         Abbreviation: "$last_blocks_tracker_abbreviation"
         Trackable: 1 OR 0
      }
   }
}

back to top  

Function : Switch

Stops current running time block and starts a new one for the given tracker_id. If no tracker_id is passed, the user's default tracker will be used.

Parameters

[tracker_id], [description]

Response

View Live XML Example 
1 (OR 0 = user was not started)
$day_total_all_trackers

   UNIX timestamp
   $tracker_day_total
   
      $last_blocks_tracker_id
      $last_blocks_tracker_name
      $last_blocks_tracker_abbreviation
      1 (OR 0)
View Live JSON Example 
{
   result: 1,
   daytotal: $day_total_all_trackers,
   last_block: {
      started_at: "UNIX timestamp",
      total: "$tracker_day_total",
      tracker: {
         Id: $last_blocks_tracker_id,
         Name: "$last_blocks_tracker_name",
         Abbreviation: "$last_blocks_tracker_abbreviation"
         Trackable: 1 OR 0
      }
   }
}

back to top  

Function : Stop

Stops the current running block for the authenticated user.

Parameters

[description]

Response

View Live XML Example 
1 (OR 0 = already stopped)
View Live JSON Example 
 {
    result: 1
 }

back to top  

Function : Total

Returns total time for today's blocks (started today).
Note: this total is also returned when starting or switching, and when calling the status action.

Response

View Live XML Example 
integer
View Live JSON Example 
 {
    total: "integer"
 }

back to top  

Function : AddTime

This function can be used to add time for the authenticated user.

A little explanation about the parameters:

  • start
    • is obliged
    • can be in any format accepted by php's strtotime
    • should be in the authenticated user's timezone, iow our server does the conversion to GMT
  • stop
    • can be ommitted, meaning 'now'
    • can be in any format accepted by php's strtotime
    • should be in the authenticated user's timezone, iow our server does the conversion to GMT
  • tracker_id: optional, if not provided the authenticated user's default tracker is taken
  • description: optional

All validation is done by the server so you could get an error message included in the error tag, for example because start is after stop.
A special error is thrown when the new block would cause an overlap. In this case an url tag is also returned in the reponse containing the edit-url for the overlapped block.

Parameters

start, [stop], [tracker_id], [description]

Response

View Live XML Example 
1

   $added_blocks_id
   $authenticated_users_profile_id
   $added_blocks_tracker_id
   $added_blocks_description
   $added_block_time_in (in Y-m-d H:i:s format)
   $added_block_time_out (in Y-m-d H:i:s format)
   $added_block_total
View Live JSON Example 
{
   result: 1 
   added_block: 
   {
      Id: $added_blocks_id
      ProfileId: $authenticated_users_profile_id
      TrackerId: $added_blocks_tracker_id
      Description: $added_blocks_description
      TimeIn: "$added_block_time_in" (in Y-m-d H:i:s format)
      TimeOut: "$added_block_time_out" (in Y-m-d H:i:s format)
      Total: $added_blocks_total
      Free: false
   }
}

back to top  

Function : AddFreeTime

This function can be used to add free time blocks for the authenticated user.

A little explanation about the parameters:

  • hours
    • the amount of hours for the new block
    • can be in decimal format (1.75) or in hour-format (1:45)
  • date
    • can be ommited, meaning today (in user's timezone, so if called by an American at 2009-07-15 00:00GMT results in time being added for the 14th, while for a European it would mean the 15th)
    • should be in 'Y-m-d'-format
  • tracker_id: optional, if not provided the authenticated user's default tracker is taken
  • description: optional

Parameters

hours, [date], [tracker_id], [description]

Response

View Live XML Example 
1

   $added_blocks_id
   $authenticated_users_profile_id
   $added_blocks_tracker_id
   $added_blocks_description
   $added_block_time_in (in Y-m-d H:i:s format)
   $added_block_time_out (in Y-m-d H:i:s format)
   $added_block_total
   1
View Live JSON Example 
{
   result: 1 
   added_block: 
   {
      Id: $added_blocks_id
      ProfileId: $authenticated_users_profile_id
      TrackerId: $added_blocks_tracker_id
      Description: $added_blocks_description
      TimeIn: "$added_block_time_in" (in Y-m-d H:i:s format)
      TimeOut: "$added_block_time_out" (in Y-m-d H:i:s format)
      Total: $added_blocks_total
      Free: true
   }
}

back to top  

Function : Reportees

This function lists all profiles you can see reporting for, which means: all profiles that are related to a tracker where you have the canSeeReporting permission.

Response

View Live XML Example 

   $id
   $title
   $first_name
   $last_name
   $email
   $phone
   $gsm
   $timezone
   $culture
   $default_tracker_id


   $id
   $title
   $first_name
   $last_name
   $email
   $phone
   $gsm
   $timezone
   $culture
   $default_tracker_id

...
...
View Live JSON Example 
{
   reportee_$profileid: {
      Id: $id
      Title: "$title"
      Namefirst: "$first_name"
      Namefamily: "$last_name"
      Email: "$email"
      Phone: "$phone"
      Gsm: "$gsm"
      Timezone: "$timezone"
      Culture: "$culture"
      DefaultTrackerId: $default_tracker_id
   }   
   reportee_$profileid: {
      Id: $id
      Title: "$title"
      Namefirst: "$first_name"
      Namefamily: "$last_name"
      Email: "$email"
      Phone: "$phone"
      Gsm: "$gsm"
      Timezone: "$timezone"
      Culture: "$culture"
      DefaultTrackerId: $default_tracker_id
   }
   ...
   ...
}

back to top  

Function : Report

This function gives you reporting capabilities. It'll return a list of blocks matching your given criteria.

There are a few parameters, none are required:

  • profile_id
    • one or more profile_ids separated by commas
    • Note: you can determine which profile_ids you can report for by calling api/reportees
  • tracker_id
    • one or more tracker_ids separated by commas
    • Note: you can determine which profile_ids you can report for by calling api/trackers/filter/reportable
  • start
    • returns only blocks started after or equal to given start
    • has to be in a format accepted by php's strtotime
  • stop
    • returns only blocks started before given stop
    • has to be in a format accepted by php's strtotime
    • can also be a unit: day, week or month, which combined with start means you'll get the blocks for the day, week or month which includes the start date
  • timezone
    • used to interpret/convert given start & stop
    • defaults to authenticated user's timezone
    • should be a valid timezone used by php's date_time
  • free
    • 0: filters out non-free blocks
    • 1: filters out free blocks
    • default: no filter
  • include_open
    • 1: includes blocks that are not stopped yet
    • default: only closed blocks are returned

Parameters

[profile_id], [tracker_id], [start], [stop], [timezone], [free], [include_open]

Response

View Live XML Example 

   $blocks_id
   $blocks_profile_id
   $blocks_tracker_id
   $blocks_description
   $blocks_time_in
   $blocks_time_out
   $blocks_total
   1


   $blocks_id
   $blocks_profile_id
   $blocks_tracker_id
   $blocks_description
   $blocks_time_in
   $blocks_time_out
   $blocks_total
   

...
...
View Live JSON Example 
{
   block_$blockid: {
      Id: $blocks_id
      ProfileId: $blocks_profile_id
      TrackerId: $blocks_tracker_id
      Description: "$blocks_description"
      TimeIn: "$blocks_time_in"
      TimeOut: "$blocks_time_out"
      Total: $blocks_total
      Free: true
   }
   block_$blockid: {
      Id: $blocks_id
      ProfileId: $blocks_profile_id
      TrackerId: $blocks_tracker_id
      Description: $blocks_description
      TimeIn: "$blocks_time_in"
      TimeOut: "$blocks_time_out"
      Total: $blocks_total
      Free: false
   }
   ...
   ...
}

back to top  

Function : CheckVersion

This function checks if there's a new widget version for your platform.
The version parameter should be "platform"+"_"+"version", e.g. Windows_Y-1.1.1

Parameters

version

Response

View Live XML Example 
1
OR
0

$update_url

OR
0
invalid version passed: $version
View Live JSON Example 
{"result":1} //most-recent version
OR
{"result":0,"url":"$update_url"}
OR
{"result":0,"error":"invalid version passed: $version"}