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