Admin permissions and Team feature required.

The role object

Attribute Type Description
id integer Unique ID for the role.
name string The name of the role.
user_ids array of integers The IDs of the users assigned to this role.
created_at datetime Date and time the role was created.
updated_at datetime Date and time the role was last updated.

List all roles

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

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

GET /v2/roles
Parameter Type Description
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/roles" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
"roles": [
{
"id": 1782974,
"name": "Founder",
"user_ids": [8083365],
"created_at": "2017-06-26T22:34:41Z",
"updated_at": "2017-06-26T22:34:52Z"
},
{
"id": 1782959,
"name": "Developer",
"user_ids": [8083366],
"created_at": "2017-06-26T22:15:45Z",
"updated_at": "2017-06-26T22:32:52Z"
},
{
"id": 1782884,
"name": "Designer",
"user_ids": [8083367],
"created_at": "2017-06-26T20:41:00Z",
"updated_at": "2017-06-26T20:42:25Z"
}
],
"per_page": 100,
"total_pages": 1,
"total_entries": 3,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/roles?page=1&per_page=100",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/roles?page=1&per_page=100"
}
}

Retrieve a role

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

GET /v2/roles/{ROLE_ID}

Example Request:

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

Example Response:

{
"id": 1782974,
"name": "Founder",
"user_ids": [8083365],
"created_at": "2017-06-26T22:34:41Z",
"updated_at": "2017-06-26T22:34:52Z"
}

Create a role

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

POST /v2/roles
Parameter Type Required Description
name string required The name of the role.
user_ids array of integers optional The IDs of the users assigned to this role.

Example Request:

curl "https://api.harvestapp.com/v2/roles" \
  -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 '{"name":"Project Manager","user_ids":[8083365,8083366]}'

Example Response:

{
"id": 2,
"name": "Project Manager",
"user_ids": [8083365, 8083366],
"created_at": "2017-06-26T22:34:41Z",
"updated_at": "2017-06-26T22:34:52Z"
}

Update a role

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

PATCH /v2/roles/{ROLE_ID}
Parameter Type Required Description
name string required The name of the role.
user_ids array of integers optional The IDs of the users assigned to this role.

Example Request:

curl "https://api.harvestapp.com/v2/roles/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 '{"name":"PM","user_ids":[8083365,8083366,8083367]}'

Example Response:

{
"id": 2,
"name": "PM",
"user_ids": [8083365, 8083366, 8083367],
"created_at": "2017-01-25T19:20:46Z",
"updated_at": "2017-01-25T19:20:57Z"
}

Delete a role

Delete a role. Deleting a role will unlink it from any users it was assigned to. Returns a 200 OK response code if the call succeeded.

DELETE /v2/roles/{ROLE_ID}

Example Request:

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