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. |
telephone |
string | The user’s telephone number. |
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_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 or Manager with assigned teammates in order to interact with the /v2/users
endpoint, except when retrieving the currently authenticated user. Managers cannot edit emails, roles, or permissions, nor can they archive, restore, or delete assigned temmates. Managers with permission to see billable rates will have access to their teammates’ default hourly rates. 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_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_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_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_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_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_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. |
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"}'
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_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_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_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_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"
}
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