Users

Admin permissions required, except when retrieving the currently authenticated user.

The user object

Attribute	Type	Description
`id`	integer	Unique ID for the user.
`first_name`	string	The first name of the user.
`last_name`	string	The last name of the user.
`email`	string	The email address of the user.
`telephone`	string	The telephone number for the user.
`timezone`	string	The user’s timezone.
`has_access_to_all_future_projects`	boolean	Whether the user should be automatically added to future projects.
`is_contractor`	boolean	Whether the user is a contractor or an employee.
`is_admin`	boolean	Whether the user has admin permissions.
`is_project_manager`	boolean	Whether the user has project manager permissions.
`can_see_rates`	boolean	Whether the user can see billable rates on projects. Only applicable to project managers.
`can_create_projects`	boolean	Whether the user can create projects. Only applicable to project managers.
`can_create_invoices`	boolean	Whether the user can create invoices. Only applicable to project managers.
`is_active`	boolean	Whether the user is active or archived.
`weekly_capacity`	integer	The number of hours per week this person is available to work in seconds, in half hour increments. For example, if a person’s capacity is 35 hours, the API will return 126000 seconds.
`default_hourly_rate`	decimal	The billable rate to use for this user when they are added to a project.
`cost_rate`	decimal	The cost rate to use for this user when calculating a project’s costs vs billable amount.
`roles`	array of strings	The role names assigned to this person.
`avatar_url`	string	The URL to the user’s avatar image.
`created_at`	datetime	Date and time the user was created.
`updated_at`	datetime	Date and time the user was last updated.

List all users

Returns a list of your users. The users are returned sorted by creation date, with the most recently created users appearing first.

The response contains an object with a users property that contains an array of up to per_page users. Each entry in the array is a separate user object. If no more users are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your users.

GET /v2/users

Parameter	Type	Description
`is_active`	boolean	Pass `true` to only return active users and `false` to return inactive users.
`updated_since`	datetime	Only return users that have been updated since the given date and time.
`page`	integer	The page number to use in pagination. For instance, if you make a list request and receive 100 records, your subsequent call can include `page=2` to retrieve the next page of the list. (Default: 1)
`per_page`	integer	The number of records to return per page. Can range between 1 and 100. (Default: 100)

Example Request:

curl "https://api.harvestapp.com/v2/users" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
  "users":[
    {
      "id":1782974,
      "first_name":"Jim",
      "last_name":"Allen",
      "email":"jimallen@example.com",
      "telephone":"",
      "timezone":"Mountain Time (US & Canada)",
      "has_access_to_all_future_projects":false,
      "is_contractor":false,
      "is_admin":false,
      "is_project_manager":false,
      "can_see_rates":false,
      "can_create_projects":false,
      "can_create_invoices":false,
      "is_active":true,
      "created_at":"2017-06-26T22:34:41Z",
      "updated_at":"2017-06-26T22:34:52Z",
      "weekly_capacity":126000,
      "default_hourly_rate":100.0,
      "cost_rate":50.0,
      "roles":["Developer"],
      "avatar_url":"https://cache.harvestapp.com/assets/profile_images/abraj_albait_towers.png?1498516481"
    },
    {
      "id":1782959,
      "first_name":"Kim",
      "last_name":"Allen",
      "email":"kimallen@example.com",
      "telephone":"",
      "timezone":"Eastern Time (US & Canada)",
      "has_access_to_all_future_projects":true,
      "is_contractor":false,
      "is_admin":false,
      "is_project_manager":true,
      "can_see_rates":false,
      "can_create_projects":false,
      "can_create_invoices":false,
      "is_active":true,
      "created_at":"2017-06-26T22:15:45Z",
      "updated_at":"2017-06-26T22:32:52Z",
      "weekly_capacity":126000,
      "default_hourly_rate":100.0,
      "cost_rate":50.0,
      "roles":["Designer"],
      "avatar_url":"https://cache.harvestapp.com/assets/profile_images/cornell_clock_tower.png?1498515345"
    },
    {
      "id":1782884,
      "first_name":"Bob",
      "last_name":"Powell",
      "email":"bobpowell@example.com",
      "telephone":"",
      "timezone":"Mountain Time (US & Canada)",
      "has_access_to_all_future_projects":false,
      "is_contractor":false,
      "is_admin":true,
      "is_project_manager":false,
      "can_see_rates":true,
      "can_create_projects":true,
      "can_create_invoices":true,
      "is_active":true,
      "created_at":"2017-06-26T20:41:00Z",
      "updated_at":"2017-06-26T20:42:25Z",
      "weekly_capacity":126000,
      "default_hourly_rate":100.0,
      "cost_rate":75.0,
      "roles":["Founder", "CEO"],
      "avatar_url":"https://cache.harvestapp.com/assets/profile_images/allen_bradley_clock_tower.png?1498509661"
    }
  ],
  "per_page":100,
  "total_pages":1,
  "total_entries":3,
  "next_page":null,
  "previous_page":null,
  "page":1,
  "links":{
    "first":"https://api.harvestapp.com/v2/users?page=1&per_page=100",
    "next":null,
    "previous":null,
    "last":"https://api.harvestapp.com/v2/users?page=1&per_page=100"
  }
}

Retrieve the currently authenticated user

Retrieves the currently authenticated user. Returns a user object and a 200 OK response code.

GET /v2/users/me

Example Request:

curl "https://api.harvestapp.com/v2/users/me" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
  "id":1782884,
  "first_name":"Bob",
  "last_name":"Powell",
  "email":"bobpowell@example.com",
  "telephone":"",
  "timezone":"Mountain Time (US & Canada)",
  "has_access_to_all_future_projects":false,
  "is_contractor":false,
  "is_admin":true,
  "is_project_manager":false,
  "can_see_rates":true,
  "can_create_projects":true,
  "can_create_invoices":true,
  "is_active":true,
  "created_at":"2017-06-26T20:41:00Z",
  "updated_at":"2017-06-26T20:42:25Z",
  "weekly_capacity":126000,
  "default_hourly_rate":100.0,
  "cost_rate":75.0,
  "roles":["Founder", "CEO"],
  "avatar_url":"https://cache.harvestapp.com/assets/profile_images/allen_bradley_clock_tower.png?1498509661"
}

Retrieve a user

Retrieves the user with the given ID. Returns a user object and a 200 OK response code if a valid identifier was provided.

GET /v2/users/{USER_ID}

Example Request:

curl "https://api.harvestapp.com/v2/users/1782974" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
  "id":1782974,
  "first_name":"Jim",
  "last_name":"Allen",
  "email":"jimallen@example.com",
  "telephone":"",
  "timezone":"Mountain Time (US & Canada)",
  "has_access_to_all_future_projects":false,
  "is_contractor":false,
  "is_admin":false,
  "is_project_manager":false,
  "can_see_rates":false,
  "can_create_projects":false,
  "can_create_invoices":false,
  "is_active":true,
  "created_at":"2017-06-26T22:34:41Z",
  "updated_at":"2017-06-26T22:34:52Z",
  "weekly_capacity":126000,
  "default_hourly_rate":100.0,
  "cost_rate":50.0,
  "roles":["Developer"],
  "avatar_url":"https://cache.harvestapp.com/assets/profile_images/abraj_albait_towers.png?1498516481"
}

Create a user

Creates a new user object. Returns a user object and a 201 Created response code if the call succeeded.

POST /v2/users

Parameter	Type	Required	Description
`first_name`	string	required	The first name of the user.
`last_name`	string	required	The last name of the user.
`email`	string	required	The email address of the user.
`telephone`	string	optional	The telephone number for the user.
`timezone`	string	optional	The user’s timezone. Defaults to the company’s timezone. See a list of supported time zones.
`has_access_to_all_future_projects`	boolean	optional	Whether the user should be automatically added to future projects. Defaults to `false`.
`is_contractor`	boolean	optional	Whether the user is a contractor or an employee. Defaults to `false`.
`is_admin`	boolean	optional	Whether the user has admin permissions. Defaults to `false`.
`is_project_manager`	boolean	optional	Whether the user has project manager permissions. Defaults to `false`.
`can_see_rates`	boolean	optional	Whether the user can see billable rates on projects. Only applicable to project managers. Defaults to `false`.
`can_create_projects`	boolean	optional	Whether the user can create projects. Only applicable to project managers. Defaults to `false`.
`can_create_invoices`	boolean	optional	Whether the user can create invoices. Only applicable to project managers. Defaults to `false`.
`is_active`	boolean	optional	Whether the user is active or archived. Defaults to `true`.
`weekly_capacity`	integer	optional	The number of hours per week this person is available to work in seconds. Defaults to `126000` seconds (35 hours).
`default_hourly_rate`	decimal	optional	The billable rate to use for this user when they are added to a project. Defaults to `0`.
`cost_rate`	decimal	optional	The cost rate to use for this user when calculating a project’s costs vs billable amount. Defaults to `0`.
`roles`	array of strings	optional	The role names assigned to this person.

If you want to add a new administrator, set is_admin to true. If you want to add a PM, set is_admin to false, is_project_manager to true, and then set any of the optional permissions to true that you’d like. If you want to add a regular user, set both is_admin and is_project_manager to false.

Example Request:

curl "https://api.harvestapp.com/v2/users" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"george@example.com","first_name":"George","last_name":"Frank","is_project_manager":true}'

Example Response:

{
  "id": 3,
  "first_name": "George",
  "last_name": "Frank",
  "email": "george@example.com",
  "telephone": "",
  "timezone": "Eastern Time (US & Canada)",
  "has_access_to_all_future_projects": false,
  "is_contractor": false,
  "is_admin": false,
  "is_project_manager": true,
  "can_see_rates": false,
  "can_create_projects": false,
  "can_create_invoices": false,
  "is_active": true,
  "weekly_capacity":126000,
  "default_hourly_rate": 0,
  "cost_rate": 0,
  "roles": ["Project Manager"],
  "avatar_url": "https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/assets/profile_images/big_ben.png?1485372046",
  "created_at": "2017-01-25T19:20:46Z",
  "updated_at": "2017-01-25T19:20:57Z"
}

Update a user

Updates the specific user by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a user object and a 200 OK response code if the call succeeded.

PATCH /v2/users/{USER_ID}

Parameter	Type	Description
`first_name`	string	The first name of the user. Can’t be updated if the user is inactive.
`last_name`	string	The last name of the user. Can’t be updated if the user is inactive.
`email`	string	The email address of the user. Can’t be updated if the user is inactive.
`telephone`	string	The telephone number for the user.
`timezone`	string	The user’s timezone. Defaults to the company’s timezone. See a list of supported time zones.
`has_access_to_all_future_projects`	boolean	Whether the user should be automatically added to future projects.
`is_contractor`	boolean	Whether the user is a contractor or an employee.
`is_admin`	boolean	Whether the user has admin permissions.
`is_project_manager`	boolean	Whether the user has project manager permissions.
`can_see_rates`	boolean	Whether the user can see billable rates on projects. Only applicable to project managers.
`can_create_projects`	boolean	Whether the user can create projects. Only applicable to project managers.
`can_create_invoices`	boolean	Whether the user can create invoices. Only applicable to project managers.
`is_active`	boolean	Whether the user is active or archived.
`weekly_capacity`	integer	The number of hours per week this person is available to work in seconds.
`default_hourly_rate`	decimal	The billable rate to use for this user when they are added to a project.
`cost_rate`	decimal	The cost rate to use for this user when calculating a project’s costs vs billable amount.
`roles`	array of strings	The role names assigned to this person.

Example Request:

curl "https://api.harvestapp.com/v2/users/2" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"telephone":"888-555-1212"}'

Example Response:

{
  "id": 2,
  "first_name": "Project",
  "last_name": "Manager",
  "email": "pm@example.com",
  "telephone": "888-555-1212",
  "timezone": "Eastern Time (US & Canada)",
  "has_access_to_all_future_projects": true,
  "is_contractor": false,
  "is_admin": false,
  "is_project_manager": true,
  "can_see_rates": true,
  "can_create_projects": true,
  "can_create_invoices": true,
  "is_active": true,
  "weekly_capacity":126000,
  "default_hourly_rate": 120,
  "cost_rate": 50,
  "roles": ["Project Manager"],
  "avatar_url": "https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/assets/profile_images/big_ben.png?1485372046",
  "created_at": "2017-01-25T19:20:46Z",
  "updated_at": "2017-01-25T19:20:57Z"
}

Delete a user

Delete a user. Deleting a user is only possible if they have no time entries or expenses associated with them. Returns a 200 OK response code if the call succeeded.

DELETE /v2/users/{USER_ID}

Example Request:

curl "https://api.harvestapp.com/v2/users/2" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X DELETE

The user object

List all users

Retrieve the currently authenticated user

Retrieve a user

Create a user

Update a user

Delete a user

Still have questions? We’re happy to help!