Authentication

All API requests must contain some mechanism for identifying the user and ensuring they are authorized to make the request. The TeamPulse API uses the Username and Password to authenticate the user.

Errors

Sadly, sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code that indicates the nature of the failure (below), with a response body in JSON format containing additional information.

200

Success. If data was requested, it will be available in the data field at the top level of the response body.

201

Success (for object creation). Its information is available in the datafield at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response.

400

Invalid request. This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

404

Not found. Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.

500

Server error. There was a problem on our end.

 

In the event of an error, the response body will contain a list of erorrs.

HTTP/1.1 400 Bad Request
 
{"te.note":"The field note must be a string with a maximum length of 128."}
 

Users

A user object represents an account in TeamPulse that can be given access to various projects.
Like other objects in the system, users are referred to by numerical IDs. 

Users only have a small set of fields:

name  smokey
The user's username.
displayName  Smokey The Bear
The user's name.

Showing a single user

GET /users/user-id
GET /users/me
This method returns the full user record for a single user.


Request

http://[teampulse]/api/users/1

Response

HTTP/1.1 200 OK
{"id":1,"name":"smokey","displayName":"Smokey The Bear"}

Showing all users

GET /users
This method returns the user records, described above, for all users in all projects that you may access.

Request
http://[teampulse]/api/users

Response

HTTP/1.1 200 OK
 
[{
 "id": 1,
 "name": "smokey",
 "displayName": "Smokey The Bear"
},
{
 "id": 2,
 "name": "yogi",
 "displayName": "Yogi The Bear"
},
...
]

Showing all users in a single project

GET /projects/project-id/users
This method returns the user records, described above, for all users in the specified project.


Request

http://[teampulse]/api/projects/1/users

Response

HTTP/1.1 200 OK
 
[{
 "id": 1,
 "name": "smokey",
 "displayName": "Smokey The Bear"
},
{
 "id": 2,
 "name": "yogi",
 "displayName": "Yogi The Bear"
},
...
]

Projects

A project is the basic organizational unit in TeamPulse. Almost everything belongs to a project - work items, tasks, etc.

Project expose the following fields:

name  Project 1
Name of the project.

Showing available projects

GET /projects

Request

http://[teampulse]/api/projects

Response

HTTP/1.1 200 OK
 
[{
 "id": 1,
 "name": "Project 1"
},
{
 "id": 2,
 "name": "Project 2"
},
...
]

Tasks

A task is the the item against user can log time. Tasks can have a work item and project. Tasks that doesn't have work item are general tasks in a project. Tasks that doesn't have work item or project are general tasks out of the projects. They are used to track time against Holiday or Sick Leaves for example.

Tasks have a rich set of metadata associated with them, some of which is exposed via the API. Here are the accessible fields on a task:

Showing a specific task

GET /tasks/task-id

Request

http://[teampulse]/api/tasks/1

Response

HTTP/1.1 200 OK
 
{
    "id": 1,
    "name": "Task 1",
    "project": {
        "id": 1,
        "name": "Project 1"
    },
    "workItem": {
        "id": 1,
        "name": "Issue #1",
        "type": "Issue",
        "estimate": 4.0
    },
    "workCompleted": 3.0,
    "estimate": {
        "optimistic": 3.0,
        "probable": 4.0,
        "pessimistic": 5.0,
        "pert": 4.0
    }
}

Querying for tasks

GET /tasks
GET /projects/project-id/tasks

Request

http://[teampulse]/api/tasks

Response

HTTP/1.1 200 OK
 
[{
    "id": 75090,
    "name": "Vacation",
    "project": { "id": -1, "name": "" },
    "estimate": {   }
},
{
    "id": 75094,
    "name": "Meetings",
    "project": { "id": 2, "name": "Project 2" },
    "workCompleted": 2.0,
    "estimate": {   }
},
{
    "id": 4341,
    "name": "Task 1",
    "project": { "id": 2, "name": "Project 2" },
    "workItem": {
        "id": 505,
        "name": "Story 5",
        "type": "Story",
        "estimate": 4.0
    },
    "workCompleted": 3.0,
    "estimate": {
        "optimistic": 5.0,
        "probable": 10.0,
        "pessimistic": 15.0,
        "pert": 10.0
    }
}
...
]

TimeEntries

A TimeEntry is the time spend in hours on specific date for specific task and user.

Creating a new TimeEntry

POST /timeentries

Request

function getData() {
    var te = {
        date: '2011-06-06',
        hours: 1,
        task: { id: 1 },
        user: { id: 6 },
        type: 'Billable'
    };
    return JSON.stringify(te);
}
 
$.ajax({
    cache: false,
    type: 'POST',
    contentType: 'application/json; charset=utf-8',
    data: getData(),
    error: function (xhr, status, err) {
        if (xhr.status == 400) {
           // error in the app
        }
        else {
            // server error
        }
    },
    success: function (data, status, xhr) {
        window.setTimeout(function () {
            alert(data);
        }, 10);
    }
});

Response

HTTP/1.1 201 Created
 
{
    "id": 19492,
    "date": "2012-06-03",
    "hours": 2.0,
    "type": "Billable",
    "user": {
        "id": 14
    },
    "task": {
        "id": 8831,
        "workCompleted": 5.0
    },
    "note": "",
    "iversion": 0
}

 

Showing a specific TimeEntry

GET /timeentries/timeentry-id

Request

http://[teampulse]/api/timeentries/3099

Response


HTTP/1.1 200 OK
 
{
    "id": 3099,
    "date": "2012-05-16",
    "hours": 10.0,
    "type": "Non-Billable",
    "user": {
        "id": 1,
        "name": "smokey",
        "displayName": "Smokey The Bear"
    },
    "task": {
        "id": 10331,
        "name": "Task 1",
        "project": {
            "id": 4,
            "name": "4_Planning"
        },
        "workItem": {
            "id": 1938,
            "name": "Risk #438",
            "type": "Risk",
            "estimate": 9.0
        },
        "workCompleted": 3.0,
        "estimate": {
            "optimistic": 3.0,
            "probable": 4.0,
            "pessimistic": 5.0,
            "pert": 4.0
        }
    },
    "note": "Note for task id: 10331",
    "iversion": 1
}

Updating an existing TimeEntry

PUT /timeentries/timeentry-id

Request

function getData() {
     var te = {
         date: '2012-06-05',
         hours: 2,
         task: { id: 7244 },
         user: { id: 14 },
         type: 'Billable',
         iversion: 1
     };
     return JSON.stringify(te);
 }
   
 $.ajax({
     url: 'http://[teampulse]/api/timeentries/2174',
     cache: false,
     type: 'PUT',
     contentType: 'application/json; charset=utf-8',
     data: getData(),
     error: function (xhr, status, err) {
         if (xhr.status == 400) {
            // error in the app
         }
         else {
             // server error
         }
     },
     success: function (data, status, xhr) {
         window.setTimeout(function () {
             alert(data);
         }, 10);
     }
 });

Response

HTTP/1.1 200 OK
 
{
    "id": 2174,
    "date": "2012-06-05",
    "hours": 2.0,
    "type": "Billable",
    "user": {
        "id": 14
    },
    "task": {
        "id": 7244,
        "workCompleted": 0.0
    },
    "note": "Note for task id: 7244",
    "iversion": 2
}

Querying for TimeEntries

GET /timeentries
 GET /timeentries?startDate=date&endDate=date

Request

http://[teampulse]/api/timeentries?startDate=2012-05-27&endDate=2012-06-02

Response

HTTP/1.1 200 OK
 
[{
    "id": 972,
    "date": "2012-05-30",
    "hours": 3.0,
    "type": "Non Billable",
    "user": {
        "id": 20,
        "name": "smokey",
        "displayName": "Smokey The Bear"
    },
    "task": {
        "id": 3099,
        "name": "Task 1",
        "project": {
            "id": 2,
            "name": "Project 2"
        },
        "workItem": {
            "id": 515,
            "name": "Bug #15",
            "type": "Bug",
            "estimate": 10.0
        },
        "workCompleted": 3.0,
        "estimate": {
            "optimistic": 3.0,
            "probable": 4.0,
            "pessimistic": 5.0,
            "pert": 4.0
        }
    },
    "note": "Note for task id: 3099",
    "iversion": 1
},{
    "id": 4545,
    "date": "2012-05-30",
    "hours": 4.0,
    "type": "",
    "user": {
        "id": 21,
        "name": "smokey",
        "displayName": "Smokey The Bear"
    },
    "task": {
        "id": 75090,
        "name": "Vacation",
        "project": {
            "id": -1,
            "name": ""
        },
        "estimate": {
             
        }
    },
    "note": "Note for Vacation",
    "iversion": 1
},
{
    "id": 6499,
    "date": "2012-05-30",
    "hours": 4.0,
    "type": "Billable",
    "user": {
        "id": 2,
        "name": "yogi",
        "displayName": "Yogi The Bear"
    },
    "task": {
        "id": 75094,
        "name": "Meetings",
        "project": {
            "id": 2,
            "name": "Project 2"
        },
        "workCompleted": 2.0,
        "estimate": {
             
        }
    },
    "note": "Note for Meetings in project id: 2",
    "iversion": 1
}
...
]

TimeEntryTypes

Querying for TimeEntryTypes

GET /projects/project-id/timeentrytypes

Request

http://[teampulse]/api/projects/2/timeentrytypes

Response

HTTP/1.1 200 OK
 
[{
    "id": 3,
    "timeEntryType": {
        "id": 1,
        "name": "Billable",
        "iversion": 0
    },
    "project": {
        "id": 2
    },
    "sequenceNumber": 1,
    "iversion": 1
},
{
    "id": 4,
    "timeEntryType": {
        "id": 2,
        "name": "Non Billable",
        "iversion": 0
    },
    "project": {
        "id": 2
    },
    "sequenceNumber": 2,
    "iversion": 1
}]

 

Activities

An activity represents an entry in the stream for any users with matching notification rules. Many activities are generated by changes to work items within TeamPulse, but it is also possible to post shared messages with custom content.

 

Querying for Activities

GET /activities
GET /activities?isFlagged=[true|false]

Request

http://[teampulse]/api/activities

Response

HTTP/1.1 200 OK
 
[{
  "id": 41632,
  "project": {
    "id": 1
  },
  "author": {
    "name": "jsmith",
    "displayName": "John Smith"
  },
  "workItem": {
    "id": 34,
    "type": "Feedback",
    "isVisibleInPortal": true
  },
  "content": "I agree with you Jane. I think this is a great idea.",
  "iconUrl": "http://tp:9898/UserMenu/GetCachedThumbnailedUserImage?name=jsmith",
  "hyperlink": "http://tp:9898/#/Project/1/GettingStarted$FeedbackId=34",
  "modifiedAt": "2012-07-05T21:03:09.443Z",
  "canComment": true,
  "commentType": 1
  "isFlagged": false,
  "system": "TeamPulse",
  "systemEvent": "WorkItemChanged"
},{
  "id": 41624,
  "author": {
    "name": "jsmith",
    "displayName": "John Smith"
  },
  "content": "John Smith shared:<br/>Going for lunch, anyone want to come?",
  "iconUrl": "http://tp:9898/UserMenu/GetCachedThumbnailedUserImage?name=jsmith",
  "modifiedAt": "2012-07-05T21:02:33.867Z",
  "canComment": true,
  "isFlagged": false,
  "system": "TeamPulse",
  "systemEvent": "PersonalMessage"
}
...
]

 

 

Querying for the count of unread items

GET /activities/unread

Request

Response

HTTP/1.1 200 OK
 
{
    "flagged": 1,
    "unflagged": 1,
    "total": 2
}

 

Marking items as seen

Used to indicate that activities have been viewed up to a certain point. The onlyFlagged parameter allows for indicating that only flagged items should be marked as seen.

PUT /activities/seenupto/activity-id
PUT /activities/seenupto/activity-id?onlyFlagged=[true|false]

Request

$.ajax({
            url: 'http://[teampulse]/api/activities/seenupto/3',
            cache: false,
            type: 'PUT',
            contentType: 'application/json; charset=utf-8',
            error: function (xhr, status, err) {
                if (xhr.status == 400) {
                    // error in the app
                }
                else {
                    // server error
                }
            },
            success: function (data, status, xhr) {
                window.setTimeout(function () {
                    alert(data);
                }, 10);
            }
        });

Response

HTTP/1.1 200 OK 
 
{
    "flagged": 0,
    "unflagged": 0,
    "total": 0
}

Getting a list of user names for mention suggestions

GET /activities/users
GET /users

Both return the same results, see getting a list of users above.

 

Creating a new Shared message activity

POST /activities/share

Request

function getData() {
    var share = {
        message: 'hello world'
    };
    return JSON.stringify(share);
}
 
$.ajax({
    url: 'http://[teampulse]/api/activities/share',
    cache: false,
    type: 'POST',
    contentType: 'application/json; charset=utf-8',
    data: getData(),
    error: function (xhr, status, err) {
        if (xhr.status == 400) {
           // error in the app
        }
        else {
            // server error
        }
    },
    success: function (data, status, xhr) {
        window.setTimeout(function () {
            alert(data);
        }, 10);
    }
});

Response

HTTP/1.1 201 Created
 
{
    "message": "Paul Smith shared: hello world"
}

 

Comments

Stories, bugs, issues, risks, and feedback can all be commented on. Feedback items can also have comments that are visible to the project portal.

 

Creating a new comment on a work item

POST /comments

Request 

function getData() {
    var comment = {
        description: 'hello world',
        type: 'PortalComment',
        project: { id: 1 },
        workItem: { id: 1, type: 'Feedback' }
    };
    return JSON.stringify(comment);
}
  
$.ajax({
    url: 'http://[teampulse]/api/comments',
    cache: false,
    type: 'POST',
    contentType: 'application/json; charset=utf-8',
    data: getData(),
    error: function (xhr, status, err) {
        if (xhr.status == 400) {
           // error in the app
        }
        else {
            // server error
        }
    },
    success: function (data, status, xhr) {
        window.setTimeout(function () {
            alert(data);
        }, 10);
    }
});

Response

HTTP/1.1 201 Created
 
{
    "id": 15,
    "project": {
        "id": 1
    },
    "workItem": {
        "id": 1,
        "type": "Feedback"
    },
    "description": "I really like this one",
    "type": "PortalComment",
    "iversion": 0
}