Roles
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