People API Calls

Add a new user

POST /people.json

Creates a new user account

Request

{
  "person": {
    "first-name": "Demo 2",
    "last-name": "User",
    "email-address": "d2@demo1company.com",
    "user-type": "account",
    "user-name": "demo2",
    "password": "d3m02",
    "company-id": "2",
    "title": "",
    "phone-number-mobile": "",
    "phone-number-office": "",
    "phone-number-office-ext": "",
    "phone-number-fax": "",
    "phone-number-home": "",
    "im-handle": "",
    "im-service": "",
    "dateFormat": "dd/mm/yyyy",
    "sendWelcomeEmail": "no",
    "welcomeEmailMessage": "",
    "receiveDailyReports": "no",
    "autoGiveProjectAccess": "yes",
    "openID": "",
    "privateNotes": "",
    "userLanguage": "EN",
    "administrator": "yes",
    "canAddProjects": "yes",
    "timezoneId" : "15",
    "notifyOnTaskComplete":"no",
    "userReceiveNotifyWarnings":"no",
    "notify-on-added-as-follower":"yes",
    "notify-on-status-update":"yes"
  }
}

See Timezone ID Table in Data Reference

Response

Returns HTTP status code 201 (Created) on success.

The URL to get the user details is returned in Location header and the new user Id is returned in variable id.


Edit user

PUT /people/{id}.json

Updates a user account

Request

{
  "person": {
    "first-name": "Demo 2",
    "last-name": "User",
    "email-address": "d2@demo1company.com",
    "user-name": "demo2",
    "password": "d3m02",
    "company-id": "2",
    "title": "",
    "phone-number-mobile": "",
    "phone-number-office": "",
    "phone-number-office-ext": "",
    "phone-number-fax": "",
    "phone-number-home": "",
    "im-handle": "",
    "im-service": "",
    "dateFormat": "dd/mm/yyyy",
    "sendWelcomeEmail": "no",
    "welcomeEmailMessage": "",
    "receiveDailyReports": "no",
    "autoGiveProjectAccess": "yes",
    "openID": "",
    "privateNotes": "",
    "userLanguage": "EN",
    "administrator": "no",
    "canAddProjects": "yes",
    "timezoneId" : "15",
    "notifyOnTaskComplete":"no",
    "userReceiveNotifyWarnings":"no",
    "notify-on-added-as-follower":"yes",
    "notify-on-status-update":"yes"
  }
}

See Timezone ID Table in Data Reference

Response

Returns HTTP status code 200 on success.


Delete user

DELETE /people/{id}.json

Deletes the given user account. 

Response

Returns HTTP status code 200 on success.


Get Current User Details

GET /me.json

Returns the details for the account you're currently logged in with

Response

{
    "person": {
        "administrator": true,
        "pid": "",
        "site-owner": false,
        "twitter": "",
        "phone-number-home": "",
        "last-name": "User",
        "email-address": "me@demo1company.com",
        "profile": "",
        "userUUID": "",
        "user-name": "test",
        "id": "999",
        "company-name": "Demo 1 Company",
        "last-changed-on": "2014-03-31T10:23:46Z",
        "phone-number-office": "",
        "deleted": false,
        "privateNotes": "",
        "phone-number-mobile": "",
        "first-name": "Demo",
        "user-type": "account",
        "permissions": {
            "can-manage-people": true,
            "can-add-projects": true
        },
        "im-service": "",
        "address": {
            "zipcode": "",
            "countrycode": "",
            "state": "",
            "line1": "",
            "country": "",
            "line2": "",
            "city": ""
        },
        "im-handle": "",
        "created-at": "2013-10-21T18:01:39Z",
        "phone-number-office-ext": "",
        "company-id": "999",
        "has-access-to-new-projects": false,
        "phone-number-fax": "",
        "avatar-url": "https://s3.amazonaws.com/TWFiles/2/users/999.avatar",
        "in-owner-company": "1",
        "last-login": "2014-04-01T11:32:12Z",
        "email-alt-1": "",
        "email-alt-2": "",
        "email-alt-3": "",
        "companyId": "999",
        "title": ""
    },
    "STATUS": "OK"
}

See People in Data Reference


Current User Summary Stats

GET /stats.json

Returns summary details for the user including Tasks today/late/upcoming, Permissions, Events, Milestones, Projects

Additional Optional Parameters

  • getPermissions : boolean: Return Permissons information in the response
  • onlymyprojects : integer: Summary of the users Projects only or all Projects
  • onlyMyEvents: boolean: Summary of the users Events only or all Events
  • eventsInNext: integer: Number of days to look ahead for Events

Response

{
	"STATUS": "OK",
	"stats": {
		"tasks": {
			"today": "0",
			"late": "0",
			"upcoming": "0"
		},
		"permissions": {
			"canLogTime": true,
			"canAddMilestones": true,
			"canAddTasks": true,
			"canAddMessages": true
		},
		"events": {
			"count": "0",
			"hasEvents": false
		},
		"milestones": {
			"today": "0",
			"late": "1",
			"complete": "20",
			"upcoming": "0",
			"active": "1"
		},
		"projects": {
			"starred": "0",
			"late": "0",
			"count": "10",
			"archived": "90",
			"upcoming": "0",
			"completed": "2",
			"current": "5"
		}
	}
}


Get people

GET /people.json

All people visible to the user will be returned, including the user themselves

By default 200 records are returned at a time.

You can pass page and pageSize to change this: eg. GET /people.json?page=2&pageSize=50

The following headers are returned:

  • X-Records - The total number of people
  • X-Pages - The total number of pages
  • X-Page - The page you requested

Additional Optional Parameters

  • emailaddress : string: Pass this parameter to check if a user exists by email address
  • fullprofile : boolean: Pass this parameter to return private notes for users
  • returnProjectIds: boolean: Pass this parameter to return the ProjectIds the user is a member of

Response

{
    "people": [
        {
            "administrator": true,
            "address-city": "",
            "pid": "",
            "site-owner": true,
            "twitter": "",
            "phone-number-home": "",
            "last-name": "User'",
            "email-address": "d@demo1company.com",
            "userUUID": "7d1bedcb-687d-102d-985d-8cebf3022cd9",
            "user-name": "demo",
            "company-name": "Demo 1 Company",
            "id": "999",
            "last-changed-on": "2014-03-25T17:15:53Z",
            "phone-number-office": "",
            "deleted": false,
            "address-state": "",
            "address-country": "",
            "privateNotes": "",
            "phone-number-mobile": "",
            "first-name": "'Demo 1",
            "user-type": "account",
            "permissions": {
                "can-manage-people": true,
                "can-add-projects": true
            },
            "im-service": "",
            "im-handle": "",
            "address-line-2": "",
            "address-line-1": "",
            "created-at": "2008-04-29T15:02:21Z",
            "phone-number-office-ext": "",
            "company-id": "999",
            "has-access-to-new-projects": false,
            "address-zip": "",
            "phone-number-fax": "",
            "avatar-url": "http://demo1company.teamwork.com/images/demo.jpg",
            "in-owner-company": true,
            "last-login": "2014-03-25T17:15:42Z",
            "email-alt-1": "",
            "email-alt-2": "",
            "companyId": "999",
            "email-alt-3": "",
            "title": ""
        }
    ]
}

See People in Data Reference


Get all People (within a Project)

GET /projects/{project_id}/people.json

Retrieves all of the people in a given project

Response

{
    "people": [
        {
            "administrator": true,
            "address-city": "",
            "pid": "",
            "site-owner": false,
            "twitter": "",
            "phone-number-home": "",
            "last-name": "User",
            "email-address": "d@demo1company.com",
            "userUUID": "",
            "user-name": "test",
            "company-name": "Demo 1 Company",
            "id": "999",
            "last-changed-on": "2014-04-01T11:13:12Z",
            "phone-number-office": "",
            "deleted": false,
            "address-state": "",
            "address-country": "",
            "privateNotes": "",
            "phone-number-mobile": "",
            "first-name": "Demo",
            "user-type": "account",
            "permissions": {
                "add-tasks": "1",
                "view-time": "1",
                "add-messages": "1",
                "view-messages-and-files": "1",
                "view-estimated-time": "1",
                "view-tasks-and-milestones": "1",
                "add-links": "1",
                "view-notebooks": "1",
                "view-invoices": "1",
                "edit-all-tasks": "1",
                "set-privacy": "1",
                "add-milestones": "1",
                "add-time": "1",
                "view-all-time-logs": "1",
                "add-taskLists": "1",
                "project-administrator": "1",
                "can-be-assigned-to-tasks-and-milestones": "1",
                "view-links": "1",
                "add-files": "1",
                "can-receive-email": "1",
                "add-notebooks": "1",
                "add-people-to-project": "1",
                "view-risk-register": "0"
            },
            "im-service": "",
            "im-handle": "",
            "address-line-2": "",
            "address-line-1": "",
            "created-at": "2013-10-21T18:01:39Z",
            "phone-number-office-ext": "",
            "company-id": "999",
            "has-access-to-new-projects": false,
            "address-zip": "",
            "phone-number-fax": "",
            "avatar-url": "http://demo1company.teamwork.com/images/avatar.jpg",
            "in-owner-company": true,
            "last-login": "2014-04-01T11:32:12Z",
            "email-alt-1": "",
            "email-alt-2": "",
            "companyId": "2",
            "email-alt-3": "",
            "title": ""
        }
    ]
}

See People in Data Reference


Get People (within a Company)

GET /companies/{company_id}/people.json

Retreives the details for all the people from the submitted company (excluding those you don't have permission to see)

Response

{
    "people": [
        {
            "administrator": true,
            "address-city": "",
            "pid": "",
            "site-owner": true,
            "twitter": "",
            "phone-number-home": "",
            "last-name": "User'",
            "email-address": "d2@demo1company.com",
            "userUUID": "7d1bedcb-687d-102d-985d-8cebf3022cd9",
            "user-name": "demo2",
            "company-name": "Demo 1 Company",
            "id": "999",
            "last-changed-on": "2014-03-25T17:15:53Z",
            "phone-number-office": "",
            "deleted": false,
            "address-state": "",
            "address-country": "",
            "privateNotes": "",
            "phone-number-mobile": "",
            "first-name": "'Demo 2",
            "user-type": "account",
            "permissions": {
                "can-manage-people": true,
                "can-add-projects": true
            },
            "im-service": "",
            "im-handle": "",
            "address-line-2": "",
            "address-line-1": "",
            "created-at": "2008-04-29T15:02:21Z",
            "phone-number-office-ext": "",
            "company-id": "999",
            "has-access-to-new-projects": false,
            "address-zip": "",
            "phone-number-fax": "",
            "avatar-url": "http://demo1company.teamwork.com/images/avatar.jpg",
            "in-owner-company": true,
            "last-login": "2014-03-25T17:15:42Z",
            "email-alt-1": "",
            "email-alt-2": "",
            "companyId": "999",
            "email-alt-3": "",
            "title": ""
        }
    ]
}

See People in Data Reference


Retrieve a Specific Person

GET /people/{person_id}.json

Retrieves the user details for the ID submitted

Response

{
    "person": {
        "administrator": true,
        "pid": "",
        "site-owner": false,
        "twitter": "",
        "phone-number-home": "",
        "last-name": "User",
        "email-address": "d@demo1company.com",
        "profile": "",
        "userUUID": "",
        "user-name": "demo",
        "id": "999",
        "company-name": "Demo 1 Company",
        "last-changed-on": "2014-04-01T11:13:12Z",
        "phone-number-office": "",
        "deleted": false,
        "privateNotes": "",
        "phone-number-mobile": "",
        "first-name": "Demo",
        "user-type": "account",
        "permissions": {
            "can-manage-people": true,
            "can-add-projects": true
        },
        "im-service": "",
        "address": {
            "zipcode": "",
            "countrycode": "",
            "state": "",
            "line1": "",
            "country": "",
            "line2": "",
            "city": ""
        },
        "im-handle": "",
        "created-at": "2013-10-21T18:01:39Z",
        "phone-number-office-ext": "",
        "company-id": "999",
        "has-access-to-new-projects": false,
        "phone-number-fax": "",
        "avatar-url": "http://demo1company.teamwork.com/images/avatar.jpg",
        "in-owner-company": "1",
        "last-login": "2014-04-01T11:32:12Z",
        "email-alt-1": "",
        "email-alt-2": "",
        "email-alt-3": "",
        "companyId": "999",
        "title": ""
    },
    "STATUS": "OK"
}

See People in Data Reference


Retrieve a API Keys for all people on account

GET /people/APIKeys.json

Retrieves the API keys for all people on your Teamwork account.

Note: This can only be called by the user authenticated as the Site Administrator

Response

{
    "people": [
        {
            "userAPIKey": "apikey",
            "first-name": "'Demo",
            "company-name": "Demo 1 Company",
            "id": "999",
            "in-owner-company": true,
            "last-name": "User'",
            "companyId": "999",
            "email-address": "d@demo1company.com",
            "company-id": "999"
        }
    ],
    "STATUS": "OK"
}


Unassign a user from all Tasks

PUT /people/{person_id}.json

This will remove the user from any Tasks they have been assigned to.

Request

{  
   "person":{  
      "unassignFromAll":"1"
   }
}

Response

{
  "STATUS": "OK"
}