Getting Started

Introduction

The API is intended for actual users of the Performance Edition of TimePerformance. It allows to integrate TimePerformance with other applications such as ERP, HR, CRM...

The API can be called from all kinds of technologies as it relies on very simple technologies. Calling the API is done by sending http requests and data are returned in simple textual formats. All API urls start with https://pma.timeperformance.com/api/v2/...

API is secured. Only authentified user can access it. (see Authentication section below)

For any question about the API or to suggest new services, please contact Time Performance Support.

Authentication

Credentials must be provided with every request with one of the following methods:

  • HTTP Basic Authentication
  • Additional parameters in the url: apiuser and apikey.

Note: API Credentials are different from crendentials used in the login form. They can be retrieved from the settings panel in the web application.

Data format

Type Format Examples
Boolean true , 1 , false , 0
Date YYYY-MM-DD 2014-12-31
Date and Time ISO 8601 2016-06-17T08:43:12.447+0000
Number 3 , 3.6 , -5468.123

Response format

The response format is determined by the extension in the URL: .json, .ics or .txt.

url extension Format Description
.json JSON JSON is the standard format for web applications to exchange structured data in plain text over http/s protocol.
.ics iCalendar iCalendar is the standard format to exchange data about calendar events (meeting..). More on Wikipedia
.txt Plain text This format is used to return an id or a comma separated list of ids as it is straightforward to parse.

Errors

Error are returned as a response code above 400 and a message in plain text in the response body.

Code Error Category Possibles causes
400 BAD REQUEST Missing required parameter, Invalid parameter value. Check returned message to get more details.
401 UNAUTHORIZED Access to the data (eg: project..) or functionnality denied to authentified user, Invalid action in regard to business rules. Check returned message to get more details.
404 NOT FOUND Entity (eg: project, user...) not found, Bad URL (API not defined)
500 INTERNAL SERVER ERROR Request failed due to unexpected conditions. Support Team is notified. Data stay safe as any transaction has been rolled back.

Sample code

An example of an API client in JAVA is published on GitHub: TimePerformance/apiclient

Project API /projects...

This API provides information related to a project.

:id in URL are placeholders for the actual id of the project.

List of Projects /projects.json

Returns the list of infos about all projects accessible by the authentified user.

Example: https://pma.timeperformance.com/api/v2/projects.json?archived=1

Parameter Type Description Required Default
archived boolean If set to true, archived projects will be included. no false

Response sample

[
	{
	  "id" : 1551,
	  "externalId" : "XX-6360",
	  "name" : "Demo Scrum",
	  "type" : "project",
	  "description" : "Ce projet est structuré selon la méthode Scrum avec des sprints de 2 semaines.\nLe projet consiste dans le développement d'un site web de réservation d'hotel en ligne.",
	  "priority" : 1,
	  "template" : false,
	  "special" : false,
	  "archived" : false,
	  "folder" : "",           // folder = section or category
	  "sponsor" : "CustomerX", // sponsor = client
	  "state" : "in_progress",
	  "stateText" : "En Cours"
	},
	...
]

Get project Id /projects/getIdFromName.txt

Returns a comma separated list of ids of projects matching the provided name.

Most project APIs requires project ids which are not displayed in the web interface. This API provides a simple way to retrieve the id from the project name. As project names are not unique in the application, the call may return a list of ids.

Example: https://pma.timeperformance.com/api/v2/projects/getIdFromName.txt

Parameter Type Description Required Default
name string Name of the project to search (case insensitive). yes

Response sample

-- one project --
32

-- several projects --
32,945

Project Progress Report /projects/:id/progressReport.json

Returns the progress report of the project.

The returned data are the same as what is displayed in the web application.

Example: https://pma.timeperformance.com/api/v2/projects/32/progressReport.json?formatting=1

Parameter Type Description Required Default
withDeliverables boolean Request progress data about the planned deliverables.
Note: This parameter has been introduced to turn off by default the new capability in order to not impact current codes of API clients. It may be removed in the future as it will become the default behaviour.
no false
formatting boolean Activates the formatting of cost, effort, percentage and dates values according to project settings and user's locale. For instance, $3200.50 if formatting is true, 3200.5 otherwise. no false

Response sample

{
  "title" : "Rapport d'avancement du projet Demo",
  // a row per phase/stage
  "rows" : [ {
    "element" : {
      "id" : 281,
      "externalId" : "XX-6368",
      "name" : "Etude",
      "type" : "phase",
      "path" : "Etude",
      "closed" : true,
      "state" : "closed",
      "depth" : 1,
      "stateText" : "Terminé"
    },
    "depth" : 1,
    "progress" : "100 %",
    "budgetedCost" : "58 640 €",
    "actualCost" : "79 680 €",
    "plannedEffort" : "131,0 jh",
    "actualEffort" : "168,0 jh",
    "rtd" : "0,0 jh",
    "plannedStart": "5/03/2014",
    "actualStart": "12/03/2014",
    "plannedEnd" : "03/10/2014",
    "actualEnd" : "01/10/2014",
    "costPercentage" : "136 %",
    "costRAG" : "KO",
    "effortPercentage" : "128 %",
    "effortRAG" : "KO",
    "scheduleVar" : "2 j.",
    "costVar" : "-21 040 €",
    "scheduleRAG" : "OK",
    "earnedValue" : "58 640 €",
    "estimateAtComp" : "79 680 €"
  },... 
  // a row per deliverable
  {
    "element" : {
      "id" : 193,
      "externalId" : "XX-6301",
      "name" : "Plan Projet",
      "type" : "goal",
      "path" : "Management » Plan Projet",
      "closed" : true,
      "state" : "closed",
      "depth" : 2,
      "stateText" : "Terminé"
    },
    "progress" : "100 %",
    "budgetedCost" : "4 160 €",
    "actualCost" : "13 675 €",
    "plannedEffort" : "8,0 jh",
    "actualEffort" : "27,5 jh",
    "rtd" : "0,0 jh",
    "plannedStart" : "15/08/2016",
    "actualStart" : "15/08/2016",
    "plannedEnd" : "16/09/2016",
    "actualEnd" : "19/09/2016",
    "costPercentage" : "329 %",
    "costRAG" : "KO",
    "effortPercentage" : "344 %",
    "effortRAG" : "KO",
    "scheduleVar" : "",
    "costVar" : "",
    "scheduleRAG" : "NONE",
    "earnedValue" : "",
    "bcws" : "",
    "bcwp" : "",
    "sv" : "",
    "cpi" : "",
    "spi" : "",
    "cpiToComplete" : "N.S.",
    "scheduleVarAtComp" : "",
    "estimateAtComp" : "" 
  },
  ... ],
  // total for the project
  "total" : {
    "element" : {
      "id" : 280,
      "externalId" : "XX-6568",
      "name" : "Demo",
      "type" : "project",
      "path" : "",
      "closed" : false,
      "state" : "open",
      "depth" : 0,
      "stateText" : "En cours"
    },
    "depth" : 0,
    "progress" : "51 %",
    "budgetedCost" : "184 840 €",
    "actualCost" : "111 160 €",
    "expenseBudget" : "4 000 €",
    "expenseCost" : "4 000 €",
    "incurredExpense" : "4 000 €",
    "plannedEffort" : "419,0 jh",
    "actualEffort" : "228,0 jh",
    "rtd" : "203,3 jh",
    "plannedStart": "5/03/2014",
    "actualStart": "12/03/2014",
    "plannedEnd" : "30/12/2014",
    "actualEnd" : "",
    "costPercentage" : "60 %",
    "costRAG" : "WARN",
    "effortPercentage" : "54 %",
    "effortRAG" : "WARN",
    "scheduleVar" : "-4 j.",
    "costVar" : "-17 506 €",
    "scheduleRAG" : "WARN",
    "earnedValue" : "93 654 €",
    "estimateAtComp" : "219 391 €"
  },
  "type" : "SIMPLE",
  "costsOn" : true,
  "costUnit" : {
    "name" : "Euro",
    "type" : "COST",
    "symbol" : "€",
    "fractionDigit" : 0
  },
  "effortUnit" : {
    "name" : "jour homme",
    "type" : "EFFORT",
    "symbol" : "jh",
    "fractionDigit" : 1
  }
}

Project Roadmap /projects/:id/roadmap.json

Returns the roadmap of the project as a hierarchical tree (project → phases → stages → deliverables → tasks)

Example: https://pma.timeperformance.com/api/v2/projects/32/roadmap.json?tasks=1&formatting=1

Parameter Type Description Required Default
tasks boolean Includes tasks for each deliverable. no false
formatting boolean Activates the formatting of cost, effort, percentage and dates values according to project settings and user's locale. For instance, $3200.50 if formatting is true, 3200.5 otherwise. no false

Response sample

{
"id" : 190,
"externalId" : "PROJ-190",
"name" : "Demo",
"type" : "project",
"description" : "...",
"path" : "",
"closed" : false,
"state" : "open",
"depth" : 0,
"stateText" : "En cours",
"children" : [ {
	"id" : 220,
	"externalId" : "XX-6240",
	"name" : "Etude",
	"type" : "phase",
	"description" : "",
	"path" : "Etude",
	"closed" : true,
	"state" : "closed",
	"depth" : 1,
	"stateText" : "Terminé",
	"children" : [ {
		"id" : 221,
		"externalId" : "XX-6239",
		"name" : "Analyse",
		"type" : "iteration",
		"description" : "",
		"path" : "Etude » Analyse",
		"closed" : true,
		"state" : "closed",
		"depth" : 2,
		"stateText" : "Terminé",
		"children" : [ {
			"id" : 193,
			"externalId" : "XX-6301",
			"name" : "Plan Projet",
			"type" : "goal",
			"description" : "...",
			"path" : "Management » Plan Projet",
			"closed" : true,
			"state" : "closed",
			"depth" : 2,
			"stateText" : "Terminé",
			// Metrics are available on entities with type project, phase, iteration or goal
			"metrics" : {
				"effort" : {
					"label" : "Taille/Charge",
					"value" : "8 jh"
				},
				"cost" : {
					"label" : "Budget",
					"value" : "4 160 €"
				},
				"missingEstimates" : false,
				"empty" : false
			},
			// Effort estimates by profile available on entities with type project, phase, iteration or goal
			"effortByProfile" : [ {
				"val" : 8.0,
				"str" : "8 jh",
				"unit" : "jh",
				"profile" : {
					"id" : 22,
					"name" : "Chef de projet",
					...
				}
			} ],
			"tasks" : [ {
				"id" : 379,
				"name" : "Comité pilotage",
				"type" : "task",
				"description" : "",
				"performer" : {
					"id" : 32,
					"key" : "u32",
					"login" : "axel",
					"name" : "Axel Martin",
					...
				},
				"state" : "completed",
				"closed" : true,
				"rtdAlert" : false,
				"effort" : "12h",
				"dueDateAlert" : 0
			},
			... ]
	 },
...
					

Project Summary /projects/:id/summary.json

Returns the full description of the project with all extra details as provided in the project summary page.

Extra details include: the team, observers, businessCase, related projects info...

Example: https://pma.timeperformance.com/api/v2/projects/32/summary.json

Response sample

{
  "id" : 190,
  "externalId" : "PRJ-01234",
  "name" : "Demo",
  "type" : "project",
  "description" : "Cet exemple montre l'utilisation de TimePerformance pour un projet suivant un cycle en cascade. fdsf",
  "priority" : 1,
  "template" : false,
  "special" : false,
  "archived" : false,
  "folder" : "categ",
  "sponsor" : "Marketing Dpt",
  "state" : "in_progress",
  "stateText" : "In Progress",
  // Project health appraisal
  "appraisal" : {
    "rating" : 3, // 1 (= in danger) to 5 (= doing great).
    "comments" : "...",
    "lastUpdate" : "2016-06-17T08:43:12.447+0000"
  },
  "stakeholders" : "popo csdqdsfs",
  "businessCase" : "...",
  "outOfScope" : "...",
  "communicationPlan" : "...",
  "relatedProjects" : "...",
  "observers" : [ {
    "id" : 30,
    "login" : "alice",
    "name" : "Alice Jung",
    "firstname" : "Alice",
    "lastname" : "Jung",
    "active" : true,
    "virtual" : false,
    "access" : true,
    "email" : "alice@acme.test",
    "externalId" : "USR-30"
  } ],
  "projectManagers" : [ {
    "id" : 28,
    "login" : "pierre",
    "name" : "Pierre Durand",
    "firstname" : "Pierre",
    "lastname" : "Durand",
    "active" : true,
    "virtual" : false,
    "access" : true,
    "email" : "pierre@acme.test",
    "externalId" : "USR-28"
  } ],
  "teamMembers" : [ {
    "id" : 30,
    "login" : "alice",
    "name" : "Alice Jung",
    "firstname" : "Alice",
    "lastname" : "Jung",
    "active" : true,
    "virtual" : false,
    "access" : true,
    "email" : "alice@acme.test",
    "externalId" : "USR-30"
  }... ]
}

Project Tasks /projects/:id/tasks.json

Returns the tasks that are part of the project.

Example: https://pma.timeperformance.com/api/v2/projects/12/tasks.json?notClosed=1

Parameter Type Description Required Default
notClosed boolean If true, the list will only contain tasks that are not completed or cancelled. no false
periodStart Date periodStart and periodEnd paremeters allows to filter out tasks based on actual work during the period. Note that actual efforts of tasks are computed over the defined period.
The period may be defined with only one parameter as from periodStart or until periodEnd.
no
periodEnd Date See above no

Response sample

[ 

// first task
{
  "id" : 241,
  "type" : "task",
  
  "name" : "Tester l'impression",
  "description" : "",
  
  "performer" : {
    "id" : 36,
    "login" : "philippe",
    "name" : "Philippe Martin",
    "firstname" : "Philippe",
    "lastname" : "Martin",
    "active" : true,
    "email" : "philippe@acme.test"
  },
  
  "project" : {
    "id" : 190,
    "externalId" : "XX-6358",
    "name" : "Demo",
    "type" : "project"
  },
  
  // if phase level is activated
  "phase" : {
    "id" : 223,
    "externalId" : "XX-6370",
    "name" : "Lot 1",
    "type" : "phase"
  },
  
  // iteration = stage
  "iteration" : {
    "id" : 224,
    "externalId" : "XX-6371",
    "name" : "Réalisation lot 1",
    "type" : "iteration"
  },
  
  // goal = deliverable
  "goal" : {
    "id" : 205,
    "externalId" : "XX-6441",
    "name" : "Module 1",
    "type" : "goal"
  },
  
  // taskType = task template from the method (optional)
  "taskType" : {
    "id" : 83,
    "externalId" : "XX-6421",
    "name" : "Design the Solution",
    "type" : "taskdefinition"
  },
  
  // taskCategory = category in the method (optional)
  "taskCategory" : {
    "id" : 80,
    "externalId" : "TC-45",
    "name" : "Development",
    "type" : "taskcategory"
  },
  
  "state" : "ready",
  "closed" : false,
  "dueDate": "2015-02-23",
  "start" : "2015-02-19", // actual start
  "end" : "2015-02-23", // actual end
  "effort" : "13.7", // actual work in hours
  "stateText" : "A faire",
  
  // if there is a checklist for the task
  "steps" : [ {
	    "name" : "Write Code",
	    "done" : true
	  }, {
	    "name" : "Write Test",
	    "done" : false
	  }]

},

... (next tasks)

]

Project Team /projects/:id/team.json

Returns the list of project team members with profiles and cost rates.

Example: https://pma.timeperformance.com/api/v2/projects/32/team.json

Response sample

[ {
  "user" : {
    "id" : 37,
    "externalId" : "USR-37",
    "name" : "Alice Jung",
    "type" : "user",
    "login" : "alice",
    "firstname" : "Alice",
    "lastname" : "Jung",
    "active" : true,
    "virtual" : false,
    "access" : true,
    "email" : "alice-test@timeperformance.com",
    "extern" : false,
    "obsName" : "IT",
    "obsPath" : "ACME » IT",
    "profileName" : "Analyst"
  },
  // user's profile for the project can be different from user's general profile
  "profile" : {
    "id" : 20,
    "externalId" : "XX-6463",
    "name" : "Developper",
    "type" : "resourceprofile"
  },
  "cost" : {
    "val" : 460.0,
    "str" : "460 $",
    "unit" : "$"
  },
  "rate" : {
    "val" : "HOURLY",
    "str" : "per hour"
  },
  // rights can be PROJECT_MANAGER, MEMBER or null (= no access to the project)
  "rights" : {
    "val" : "MEMBER",
    "str" : "Team member"
  }
},
... ]

Project Workload Plan /projects/:id/workloadplan.json

Returns planned workloads for each resource profile.

The returned data are a set of data series, one series per profile. Each series contains weekly values expressed in FTE unit (full-time employee).

Example: https://pma.timeperformance.com/api/v2/projects/32/workloadplan.json

Parameter Type Description Required Default
no parameters

Response sample

[ 
    {
        // ressource profile 
        "profile" : {
            "id" : 16,
            "externalId" : "XX-6596",
            "name" : "Analyste",
            "type" : "resourceprofile"
          },
          
        "workloadWeeklySeries" : [ {
            "date" : "2015-12-28",  // first day of the week
            "value" : 1.2           // value smoothed over the week
          }, {
            "date" : "2016-01-04",
            "value" : 1.2
          }, {
            "date" : "2016-01-11",
            "value" : 1.2
          } ... ]
    }, ...
]

User API /users...

This API provides information related to a user. The provided information currently are: Time Tracking Report and Assignement Schedule.

:id in URL are placeholders for the actual id of the user.

Get user Id /users/getIdFromLogin.txt

Returns user id from his/her username.

API generally require user id which are not displayed in the web interface. This API provides a simple way to retrieve the id from the username.

Example: https://pma.timeperformance.com/api/v2/users/getIdFromLogin.txt?login=peter

Parameter Type Description Required Default
login string Username of the user to search. yes

Response sample

165

List of Users /users.json

Returns the list of users.

Example: https://pma.timeperformance.com/api/v2/users.json

Response sample

[
	{
  		"id" : 22,
		"login" : "pierre",
		"name" : "Pierre Durand",
		"firstname" : "Pierre",
		"lastname" : "Durand",
		"active" : true,
		"email" : "pierre@acme.com",
		"obsName" : "R&D",       // Department's name
		"obsPath" : "IT » R&D",  // Department's hierarchical name
		"virtual" : false,
		"profileName" : "Project Manager"
	},
	...
]

Assignment Schedule /users/:id/schedule.ics

Returns user assignement schedule in iCal Format.

Example: https://pma.timeperformance.com/api/v2/users/165/schedule.ics

Parameter Type Description Required Default
month integer Define duration in months that must be covered by the returned schedule. By default, the returned schedule covers the last 12 months and the next 12 months (2 years).
Month parameter must be between 0 and 24 (included).
no 12

Response sample

BEGIN:VCALENDAR
PRODID:-//TimePerformance//PMA//EN
VERSION:2.0
CALSCALE:GREGORIAN
BEGIN:VEVENT
DTSTAMP:20141105T093810Z
DTSTART:20140811T060000Z
DTEND:20140811T100000Z
SUMMARY:Demo
TZID:Europe/Paris
UID:BK-4471@timeperformance.com
ATTENDEE;ROLE=REQ-PARTICIPANT;CN=Pierre Durand:mailto:peter@acme.com
END:VEVENT
BEGIN:VEVENT
DTSTAMP:20141105T093810Z
DTSTART:20140811T110000Z
DTEND:20140811T150000Z
SUMMARY:Demo
TZID:Europe/Paris
UID:BK-4472@timeperformance.com
ATTENDEE;ROLE=REQ-PARTICIPANT;CN=Pierre Durand:mailto:peter@acme.com
END:VEVENT
...

My Assignment Schedule /users/myschedule.ics

Shortcut for the previous API in the simple case where the requested schedule concerns the authentified user.

The typical usage is for importing one's assignment schedule in the tool used to manage one's calendar (Microsoft Outlook, Google calendar, Zimbra...).

Example with parameter based authentication (typical usage for importing the assignment schedule in another tool):
https://pma.timeperformance.com/api/v2/users/myschedule.ics?apiuser=peter@acme&apikey=Erf45...DFG

Note: the full link to one's assignment schedule can be copied from My Assignment page in the web application.

Tasks /users/:id/tasks.json

Returns a filtered list of tasks assigned to the person.

Access is restricted to the person or a manager of the person.

Example: https://pma.timeperformance.com/api/v2/users/32/tasks.json?periodStart=2015-01-01&periodEnd=2015-01-31

Parameter Type Description Required Default
notClosed boolean If true, the list will only contain tasks that are not completed or cancelled. no false
periodStart Date periodStart and periodEnd paremeters allows to filter out tasks based on actual work during the period. Note that actual efforts of tasks are computed over the defined period.
The period may be defined with only one parameter as from periodStart or until periodEnd.
no
periodEnd Date See above no

Response sample

[ 

// first task
{
  "id" : 241,
  "type" : "task",
  
  "name" : "Tester l'impression",
  "description" : "",
  
  "performer" : {
    "id" : 36,
    "login" : "philippe",
    "name" : "Philippe Martin",
    "firstname" : "Philippe",
    "lastname" : "Martin",
    "active" : true,
    "email" : "philippe@acme.test"
  },
  
  "project" : {
    "id" : 190,
    "externalId" : "XX-6358",
    "name" : "Demo",
    "type" : "project"
  },
  
  // if phase level is activated
  "phase" : {
    "id" : 223,
    "externalId" : "XX-6370",
    "name" : "Lot 1",
    "type" : "phase"
  },
  
  // iteration = stage
  "iteration" : {
    "id" : 224,
    "externalId" : "XX-6371",
    "name" : "Réalisation lot 1",
    "type" : "iteration"
  },
  
  // goal = deliverable
  "goal" : {
    "id" : 205,
    "externalId" : "XX-6441",
    "name" : "Module 1",
    "type" : "goal"
  },
  
  // taskType = task template from the method (optional)
  "taskType" : {
    "id" : 83,
    "externalId" : "XX-6421",
    "name" : "Design the Solution",
    "type" : "taskdefinition"
  },
  
  // taskCategory = category in the method (optional)
  "taskCategory" : {
    "id" : 80,
    "externalId" : "TC-45",
    "name" : "Development",
    "type" : "taskcategory"
  },
  
  "state" : "ready",
  "closed" : false,
  "dueDate": "2015-02-23",
  "start" : "2015-02-19", // actual start
  "end" : "2015-02-23", // actual end
  "effort" : "13.7", // actual work in hours
  "stateText" : "A faire",
  
  // if there is a checklist for the task
  "steps" : [ {
	    "name" : "Write Code",
	    "done" : true
	  }, {
	    "name" : "Write Test",
	    "done" : false
	  }]

},

... (next tasks)

]

Time Report /users/:id/timeReport.json

Returns time spent on projects or activities day by day.

Data found in time reports are the same as those provided in user's monthly activity report, except that covered time period is free.

The typical usage is for importing time entered in TimePerformance into an ERP or HR system. For such usage, time report may be equalized. For instance, it can be requested that the total number of worked hours per day is always 8 hours, 4 hours (half day) or 0 hour.

Example: https://pma.timeperformance.com/api/v2/users/192/timeReport.json?firstDay=2015-01-01&lastDay=2015-03-31

Parameter Type Description Required Default
firstDay Date First day of the time period yes
lastDay Date Last day of the time period yes
hoursPerDay float If provided, time report will be equalized so that the number of worked hours per day is constant. no
halfDayThreshold float Used in conjonction with parameter hoursPerDay.
Set the numbers of worked hours under which time spent for a day will be equalized to half a work day, so to speak half of hoursPerDay.
no 1/2 hoursPerDay

Response sample

{
  "user" : {
    "id" : 192,
    "login" : "peter",
    "name" : "Peter Black",
    "firstname" : "Peter",
    "lastname" : "Black",
    "active" : true,
    "email" : "peter@acme.com"
  },
  "firstDay" : "2014-10-26",
  "lastDay" : "2014-11-01",
  "timeByProjects" : [ {
    "activity" : {
      "id" : 249,
      "externalId" : "XX-6358",
      "name" : "Demo",
      "type" : "project"
    },
    "entries" : [ {
      "day" : "2014-10-27",
      "hours" : 4.0
    }, {
      "day" : "2014-10-28",
      "hours" : 8.0
    }, {
      "day" : "2014-10-29",
      "hours" : 8.0
    } ]
  }, {
    "activity" : {
      "id" : 1172,
      "externalId" : "XX-777",
      "name" : "Web Site",
      "type" : "project"
    },
    "entries" : [ {
      "day" : "2014-10-26",
      "hours" : 7.2833333
    }, {
      "day" : "2014-10-27",
      "hours" : 3.25
    } ]
  } ],
  
  "timeByNonProjectActivities" : [ {
    "activity" : {
      "id" : 7,
      "externalId" : "XX-6534",
      "name" : "Congés",
      "type" : "npactivity"
    },
    "entries" : [ {
      "day" : "2014-10-30",
      "hours" : 7.5
    } ]
  }... 
  ],
  
  "total" : [ {
    "day" : "2014-10-26",
    "hours" : 7.2833333
  }, {
    "day" : "2014-10-27",
    "hours" : 7.25
  }, {
    "day" : "2014-10-28",
    "hours" : 8.0
  }, {
    "day" : "2014-10-29",
    "hours" : 8.0
  }, {
    "day" : "2014-10-30",
    "hours" : 7.5
  }, {
    "day" : "2014-10-31",
    "hours" : 7.5
  } ]
}

Timesheet /users/:id/timesheet.json

Returns time spent on project tasks or activities day by day.

Timesheet API is the most detailed time report. It provides times at task level, whereas the time report above provides times at project level.

As for time report, it may be equalized. For instance, it can be requested that the total number of worked hours per day is always 8 hours, 4 hours (half day) or 0 hour.

Example: https://pma.timeperformance.com/api/v2/users/192/timesheet.json?firstDay=2015-01-01&lastDay=2015-03-31

Parameter Type Description Required Default
firstDay Date First day of the time period yes
lastDay Date Last day of the time period yes
hoursPerDay float If provided, time report will be equalized so that the number of worked hours per day is constant. no
halfDayThreshold float Used in conjonction with parameter hoursPerDay.
Set the numbers of worked hours under which time spent for a day will be equalized to half a work day, so to speak half of hoursPerDay.
no 1/2 hoursPerDay

Response sample

{
  "user" : {
    "id" : 30,
    "login" : "alice",
    "name" : "Alice Jung",
    "firstname" : "Alice",
    "lastname" : "Jung",
    "active" : true,
    "email" : "alice@acme.test"
  },
  "firstDay" : "2016-02-01",
  "lastDay" : "2016-02-29",
  "timeByProjects" : [ {
    "project" : {
      "id" : 190,
      "externalId" : "XX-6358",
      "name" : "Demo",
      "type" : "project"
    },
    "timeByTasks" : [ {
      "activity" : {
        "id" : 411,
        "name" : "Estimer la charge",
        "type" : "task",
        "description" : "",
        "performer" : {
          "id" : 30,
          "login" : "alice",
          "name" : "Alice Jung",
          "firstname" : "Alice",
          "lastname" : "Jung",
          "active" : true,
          "email" : "alice@acme.test"
        },
        "state" : "completed",
        "closed" : true,
        "project" : {
          "id" : 190,
          "externalId" : "XX-6358",
          "name" : "Demo",
          "type" : "project"
        },
        "phase" : {
          "id" : 220,
          "externalId" : "XX-6368",
          "name" : "Etude",
          "type" : "phase"
        },
        "iteration" : {
          "id" : 221,
          "externalId" : "XX-6367",
          "name" : "Analyse",
          "type" : "iteration"
        },
        "goal" : {
          "id" : 193,
          "externalId" : "XX-6432",
          "name" : "Plan Projet",
          "type" : "goal"
        },
        "start" : "2015-12-28",
        "end" : "2016-02-01",
        "stateText" : "Terminée"
      },
      "entries" : [ {
        "day" : "2016-02-01",
        "hours" : 1.75
      } ... ]
    } ... ]
  } ],
  "timeByNonProjectActivities" : [ {
    "activity" : {
      "id" : 7,
      "externalId" : "XX-6534",
      "name" : "Congés",
      "type" : "npactivity"
    },
    "entries" : [ {
      "day" : "2016-02-26",
      "hours" : 7.0
    } ]
  } ],
  "total" : [ {
    "day" : "2016-02-01",
    "hours" : 7.0
  }, {
    "day" : "2016-02-02",
    "hours" : 7.0
  }, {
    "day" : "2016-02-03",
    "hours" : 7.0
  }... ]
}

To-do List /users/:id/todolist.json

Returns the to-do list of the person.

The to-do list is the list of tasks assigned to the person and related to open deliverables.

Access is restricted to the person or a manager. Project managers can also access to team members' to-do lists for their projects (project parameter required).

Example: https://pma.timeperformance.com/api/v2/users/32/todolist.json

Parameter Type Description Required Default
project integer Id of a project. If set, the returned list only contains tasks related to the project. no

Response sample

[ 

// first task
{
  "id" : 241,
  "type" : "task",
  
  "name" : "Tester l'impression",
  "description" : "",
  
  "performer" : {
    "id" : 36,
    "login" : "philippe",
    "name" : "Philippe Martin",
    "firstname" : "Philippe",
    "lastname" : "Martin",
    "active" : true,
    "email" : "philippe@acme.test"
  },
  
  "project" : {
    "id" : 190,
    "externalId" : "XX-6358",
    "name" : "Demo",
    "type" : "project"
  },
  
  // if phase level is activated
  "phase" : {
    "id" : 223,
    "externalId" : "XX-6370",
    "name" : "Lot 1",
    "type" : "phase"
  },
  
  // iteration = stage
  "iteration" : {
    "id" : 224,
    "externalId" : "XX-6371",
    "name" : "Réalisation lot 1",
    "type" : "iteration"
  },
  
  // goal = deliverable
  "goal" : {
    "id" : 205,
    "externalId" : "XX-6441",
    "name" : "Module 1",
    "type" : "goal"
  },
  
  // taskType = task template from the method (optional)
  "taskType" : {
    "id" : 83,
    "externalId" : "XX-6421",
    "name" : "Design the Solution",
    "type" : "taskdefinition"
  },
  
  // taskCategory = category in the method (optional)
  "taskCategory" : {
    "id" : 80,
    "externalId" : "TC-45",
    "name" : "Development",
    "type" : "taskcategory"
  },
  
  "state" : "ready",
  "closed" : false,
  "dueDate": "2015-02-23",
  "start" : "2015-02-19", // actual start
  "end" : "2015-02-23", // actual end
  "effort" : "13.7", // actual work in hours
  "stateText" : "A faire",
  
  // if there is a checklist for the task
  "steps" : [ {
	    "name" : "Write Code",
	    "done" : true
	  }, {
	    "name" : "Write Test",
	    "done" : false
	  }]

},

... (next tasks)

]