Users
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