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.
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.

Required permissions

You must be an Administrator in order to interact with the /v2/users endpoint, except when retrieving the currently authenticated user. Insufficient permissions will result in a 403 Forbidden status code.

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 Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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":3230547,
      "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":"2020-05-01T22:34:41Z",
      "updated_at":"2020-05-01T22: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":"2020-05-01T22:15:45Z",
      "updated_at":"2020-05-01T22: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":"2020-05-01T20:41:00Z",
      "updated_at":"2020-05-01T20: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 Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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":"2020-05-01T20:41:00Z",
  "updated_at":"2020-05-01T20: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 Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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

Example Response:

{
  "id":3230547,
  "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":"2020-05-01T22:34:41Z",
  "updated_at":"2020-05-01T22: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 and sends an invitation email to the address specified in the email parameter. 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.
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 Project Manager, 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 Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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": "Gary",
  "last_name": "Brookes",
  "email": "gary@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": "2020-01-25T19:20:46Z",
  "updated_at": "2020-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.
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 Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


curl "https://api.harvestapp.com/v2/users/3237198" \
  -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 '{"roles":["Project Manager"]}'

Example Response:

{
  "id": 3237198,
  "first_name": "Project",
  "last_name": "Manager",
  "email": "pm@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": 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": "2018-01-01T19:20:46Z",
  "updated_at": "2019-01-25T19:20:57Z"
}

Archive a user

Archives a specific user by setting the value of is_active to false. To make a user active again, simply set is_active to true again. Returns the updated user object and a 200 OK response code if the call succeeded.

PATCH /v2/users/{USER_ID}

Example Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


curl "https://api.harvestapp.com/v2/users/3226125" \
  -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 '{"is_active":false}'

Example Response:

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

Make a user an Admin

Grants a specific user Admin permissions. Returns the updated user object and a 200 OK response code if the call succeeded.

PATCH /v2/users/{USER_ID}

Example Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


curl "https://api.harvestapp.com/v2/users/3226125" \
  -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 '{"is_admin":true}'

Example Response:

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

Make a user a Project Manager

Grants a specific user Project Manager permissions. Returns the updated user object and a 200 OK response code if the call succeeded.

Setting is_project_manager to true will make someone a Project Manager, but there are a few optional permissions that you can grant.

Attribute Type Description
can_see_rates boolean Whether the Project Manager can see billable rates on projects.
can_create_projects boolean Whether the Project Manager can create projects.
can_create_invoices boolean Whether the Project Manager can create invoices. 
PATCH /v2/users/{USER_ID}

Example Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


curl "https://api.harvestapp.com/v2/users/3226125" \
  -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 '{"is_project_manager":true, "can_see_rates":false, "can_create_projects":true, "can_create_invoices":false}'

Example Response:

{
  "id": 3226125,
  "first_name": "Rachel",
  "last_name": "Halliday",
  "email": "rachel@example.com",
  "telephone": "",
  "timezone": "Eastern Time (US & Canada)",
  "has_access_to_all_future_projects": true,
  "is_contractor": false,
  "is_admin": true,
  "is_project_manager": false,
  "can_see_rates": true,
  "can_create_projects": false,
  "can_create_invoices": false,
  "is_active": true,
  "weekly_capacity":126000,
  "default_hourly_rate": 120,
  "cost_rate": 50,
  "roles": ["Developer"],
  "avatar_url": "https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/assets/profile_images/big_ben.png?1485372046",
  "created_at": "2018-01-01T19:20:46Z",
  "updated_at": "2019-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 Requests:

Postman Collection

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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