Introduction
The Betterworks REST API enables users to securely connect Betterworks to other business-critical applications in a way that’s both straightforward and automatic.
All API responses return JSON, including errors. To allow for testing, you can make API keys in the Betterworks Preview Environment. The Preview Environment is refreshed at the end of every month, so a new key will need to be generated each month. Production keys are live until deactivated via the Betterworks admin portal.
This documentation refers to Betterworks work units as “goals” and “milestones.” These units are interchangeable with “Objectives” and “Key Results” respectively, so if your organization uses OKRs, remember that every “goal” is an “Objective” and every “milestone” is a “Key Result.”
Authentication
# With shell, you can just pass the correct header with each request
curl --header "Authorization: APIToken <Your API Token>"
https://app.betterworks.com/api/v1/users/:identifier/`
Each call to the API is authenticated by including your secret API token in the request. API tokens are managed through the Betterworks Admin portal. Please contact your Betterworks Admin to obtain a token. Each token carries the permissions of the user assigned to the token. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
URI Structure and Versioning
All Betterworks APIs require specifying an API version in the request URL.
Ex. GET https://app.betterworks.com/api/<Version>/user/
or GET https://preview.betterworks.com/api/<Version>/user/ if developing against the preview
environment.
Newer versions of the API will include new features and improvements and you should consider upgrading to the latest version whenever possible.
The most current API version is V1 (GET https://app.betterworks.com/api/v1/user/). New
versions of the API will be communicated to your Betterworks admin and via our Support page.
Permissions
Permissions for API keys will always match the permissions allowed to the user in which the API key is assigned. For example, if a user owns a private goal, that goal will be visible to requests made using any key attached to the user (and will not be visible for API keys attached to users that do not have permission to view).
In addition, some APIs require additional administrative privileges in order to function.
Pagination
The API response will be of the form:
{
"results": [
],
"more" : "true",
"nextUrl": "<nextpageurl>"
}
All Betterworks APIs support pagination. The Supplying page will select which page of content you
get, and size will dictate the number of entities returned per page.
Ex. /api/v1/departments/?page=1&size=15
If more is true, you can get the next page of results by querying the nextURL
Delta Filters
Many Betterworks API endpoints support delta filters, allowing the client to specify a range of dates in ISO format YYYY-MM-DD that filter results based on the item’s modified_on field. Delta filters support delta_start and delta_end operators which can be combined to filter on a range of dates or applied individually.
In the example below the API will return all users modified on or after January 1st 2019.
GET https://app.betterworks.com/api/v1/users?delta_start=2019-01-01
In the example below the API will return all users modified on or before January 1st 2019.
GET https://app.betterworks.com/api/v1/users?delta_end=2019-01-01
In the example below the API will return all users modified between January 1st 2019 and January 31st 2019.
GET https://app.betterworks.com/api/v1/users?delta_start=2019-01-01&delta_end=2019-01-31
Delta filters support extended ISO formats including time of day YYYY-MM-DDTHH:MM:SS and timezone information YYYY-MM-DDTHH:MM:SS.SSSZ. If no timezone information is provided, the date is assumed to be in UTC. If no time is provided for delta_start then the beginning of the day is assumed 00:00:00. If no time is provided for delta_end then the end of the day is assumed 23:59:59.
More details about ISO format can be found here: W3 Date and Time Formats.
Admin Groups
In the Betterworks system, groups can be any collection of users, and are typically a cohort of users by say physical location, or seniority. Groups are only created by Super Admins in the platform and are primarily used when scheduling conversation cycles.
Get Admin Group
Example Response:
{
"id":327,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"name":"<Admin Group Name>",
"is_active":true,
"template_usage":true,
"last_edited":1601361643.726711,
"last_edited_by":{
"id":308,
"uuid": "12ebee06-2595-4471-976a-01321f3de805",
"name":"<First Name> <Last Name>"
},
"member_count":544,
"attributes":[
{
"operation":"exclude",
"property":"custom-01",
"value":[
{
"id":197,
"uuid":"f9f8f8f8-f8f8-f8f8-f8f8-f8f8f8f8f8f8",
"name":"<First Name> <Last Name>"
}
]
}
],
"additional_members":[
{
"id":28,
"uuid":"e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"name":"<First Name> <Last Name>"
},
{
"id":34,
"uuid":"ac190e12-1d78-4bf3-b3fc-f26ce21471af",
"name":"<First Name> <Last Name>"
}
],
"created_on": "2022-01-18T18:43:01.859716Z",
"modified_on": "2022-01-18T18:43:01.859791Z"
}
Get admin group details
HTTP Request
GET /api/v1/groups/:id/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | The admin group ID |
Returns
Admin group object
List Admin Groups
Example Response:
{
"more": false,
"num_pages": 2,
"page": 1,
"results": [
{
"id":327,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"name":"<Admin Group Name>",
"is_active":true,
"created_on": "2019-01-01T12:00:00.123456Z",
"modified_on": "2019-01-02T12:00:00.123456Z",
"template_usage":true,
"last_edited":1601361643.726711,
"last_edited_by":{
"id":308,
"uuid": "12ebee06-2595-4471-976a-01321f3de805",
"name":"<First Name> <Last Name>"
},
"member_count":544,
"attributes":[
{
"operation":"exclude",
"property":"custom-01",
"value":[
{
"id":197,
"uuid":"ac1a91-1d78-4bf3-b3fc-f26ce21471af",
"name":"<First Name> <Last Name>"
}
]
}
],
"additional_members":[
{
"id":28,
"uuid":"e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"name":"<First Name> <Last Name>"
},
{
"id":34,
"uuid":"ac190e12-1d78-4bf3-b3fc-f26ce21471af",
"name":"<First Name> <Last Name>"
}
],
"created_on": "2022-01-18T18:43:01.859716Z",
"modified_on": "2022-01-18T18:43:01.859791Z"
}
],
"nextUrl": "/api/v1/groups/?size=1&page=2"
}
Get list of admin groups
HTTP Request
GET /api/v1/groups/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| page | Optional | Integer | Page number of groups to return |
| size | Optional | Integer | Number of groups per page, default 20, max 100 |
| delta_start | Optional | ISO Date | Filter groups modified on or after |
| delta_end | Optional | ISO Date | Filter groups modified on or before |
Returns
List of admin group objects
Conversations
In the Betterworks system, Conversations can take two forms, anytime (adhoc) or scheduled.
Each Conversation follows a Conversation Template which dictates the attributes of the conversation. Each Conversation Template deployments represent a summary of conversations. These deployments represent the time frame for a given set of conversations, whether they be appointed or on demand. This range of time includes the start, end, review and notification dates for all stages and participant roles for a conversation taking place at that defined time.
List Conversation Templates
Example Response:
{
"results": [
{
"id": 47,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"type": "scheduled",
"name": "<Conversation Template Name>",
"description": "<Conversation Template Description>",
"enabled": false,
"require_marked_as_met": true,
"only_managers_can_initiate": false,
"allowed_employees": [
{
"id": 1234,
"name": "<First Name> <Last Name>",
"is_active": true,
"email": "<Email>"
}
],
"allowed_groups": [
2070
],
"is_goal_creation_enabled": true,
"hrq_enabled": true,
"hrq_is_concurrent": false,
"hrq_notification_on_start": false,
"hrq_notification_on_due": false,
"notification_on_start": true,
"notification_on_end": true,
"notification_midcycle_days": 3,
"notification_overdue_days": 5,
"super_admin_permission": "can_only_view",
"hr_admin_permission": "can_only_view",
"skip_level_managers_permission": "no_access",
"skip_level_managers_level": "none",
"matrix_manager_enabled": true,
"matrix_manager_can_see_responses": true,
"matrix_manager_can_see_direct_report_responses": true,
"deployments": [
{
"id": 25,
"uuid": "8c9e0068-ea7d-409f-87f2-fd67b9jl2638",
"name": "<Conversation Name>",
"description": "<Conversation Description>",
"cycles": [
{
"id": 40,
"uuid": "bff67539-249e-516d-84c3-c026da93372d",
"role": "manager",
"stage": "primary",
"start": "2020-11-26",
"end": "2021-03-06",
"lock_on_share": true,
"lock_date": "2021-02-28",
"review_end": "2021-01-31",
"submit_end": "2021-02-06",
"grace_period_end": "2021-02-10"
},
{
"id": 41,
"uuid": "c4c84b58-e38d-436c-920a-eee60d9af648",
"role": "employee",
"stage": "primary",
"start": "2020-11-26",
"end": "2021-03-06",
"lock_on_share": false,
"lock_date": null,
"review_end": "2021-01-31",
"submit_end": "2021-02-06",
"grace_period_end": "2021-02-10"
}
]
}
],
"participants": [
"employee",
"manager"
],
"hrq_participants": [
"employee",
"manager"
],
"created": 1606266306.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 67,
"uuid": "e83461a4-fa06-4014-80d3-e3e6cc3c1ccc"
},
"updated": 1606266306.0,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 67,
"uuid": "e83461a4-fa06-4014-80d3-e3e6cc3c1ccc"
},
"created_on": "2020-11-26T17:06:06.000Z",
"modified_on": "2020-11-26T17:06:06.000Z"
}
],
"more": true,
"nextUrl": "/api/v1/conversations/templates/?size=1&page=2"
}
This endpoint will retrieve a list of conversation templates with details within your organization.
HTTP Request
GET /api/v1/conversations/templates/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| type | Optional | Enum | Filters conversations by the type. Accepts scheduled or adhoc |
| enabled | Optional | Boolean | Filter conversations that are enabled or not |
Returns
Returns the list of conversation templates
Get Conversation Template
Example Response:
{
"id": 41,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"type": "scheduled",
"name": "<Conversation Template Name>",
"description": "<Conversation Template Description>",
"enabled": false,
"require_marked_as_met": true,
"only_managers_can_initiate": false,
"allowed_employees": [
{
"id": 1511,
"name": "<First Name> <Last Name>",
"is_active": true,
"email": "<Email>"
}
],
"allowed_groups": [
371
],
"is_goal_creation_enabled": true,
"hrq_enabled": true,
"hrq_is_concurrent": false,
"hrq_notification_on_start": false,
"hrq_notification_on_due": false,
"notification_on_start": true,
"notification_on_end": true,
"notification_midcycle_days": 2,
"notification_overdue_days": 2,
"super_admin_permission": "can_only_view",
"hr_admin_permission": "can_only_view",
"skip_level_managers_permission": "no_access",
"skip_level_managers_level": "none",
"matrix_manager_enabled": true,
"matrix_manager_can_see_responses": true,
"matrix_manager_can_see_direct_report_responses": true,
"deployments": [
{
"id": 25,
"uuid": "8c9e0068-ea7d-409f-87f2-fd67b9jl2638",
"name": "<Conversation Name>",
"description": "<Conversation Description>",
"cycles": [
{
"id": 40,
"uuid": "bff67539-249e-516d-84c3-c026da93372d",
"role": "manager",
"stage": "primary",
"start": "2020-11-26",
"end": "2021-03-06",
"lock_on_share": true,
"lock_date": "2021-02-28",
"review_end": "2021-01-31",
"submit_end": "2021-02-06",
"grace_period_end": "2021-02-10"
},
{
"id": 41,
"uuid": "c4c84b58-e38d-436c-920a-eee60d9af648",
"role": "employee",
"stage": "primary",
"start": "2020-11-26",
"end": "2021-03-06",
"lock_on_share": false,
"lock_date": null,
"review_end": "2021-01-31",
"submit_end": "2021-02-06",
"grace_period_end": "2021-02-10"
}
]
}
],
"participants": [
"employee",
"manager"
],
"hrq_participants": [
"employee",
"manager"
],
"created": 1606266306.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 67,
"uuid": "e83461a4-fa06-4014-80d3-e3e6cc3c1ccc"
},
"updated": 1606266306.0,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 67,
"uuid": "e83461a4-fa06-4014-80d3-e3e6cc3c1ccc"
},
"created_on": "2020-11-26T17:06:06.000Z",
"modified_on": "2020-11-26T17:06:06.000Z"
}
Returns details for a specific conversation template using template ID
HTTP Request
GET /api/v1/conversations/templates/:id/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | The conversation template ID |
Returns
Returns the conversation template details.
List Conversations
Example Response:
{
"results": [
{
"id": 1,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"type": "scheduled",
"name": "<Conversation Name>",
"description": "",
"deployment_id": 111,
"manager": {
"name": "<First Name> <Last Name>",
"id": 33,
"uuid": "e83461a4-fa06-4014-80d3-e3e6cc3c1ccc"
},
"employee": {
"name": "<First Name> <Last Name>",
"id": 40,
"uuid": "1aac7892-fd6f-4e89-88d6-2c7ae4657681"
},
"contributors": [
{
"user": {
"name": "<First Name> <Last Name>",
"id": 53,
"uuid": "c4c84b58-e38d-436c-920a-eee60d9af648"
},
"status": "shared",
"response": "<Response Text>"
},
{
"user": {
"name": "<First Name> <Last Name>",
"id": 54,
"uuid": "30304c36-c481-47ae-8966-d39229ed87e9"
},
"status": "answering",
"response": null
}
],
"start": "2021-04-26",
"end": "2021-04-28",
"marked_as_met": "not_met",
"manager_response": {
"id": 27,
"uuid": "c4c84b58-e38d-436c-920a-eee60d9af648",
"name": "<First Name> <Last Name>",
"description": "<Description Text>",
"shared_on": 1647848875.409886,
"submitted_on": 1650014212.357601,
"unlocked_until": 1660014212.357601,
"responses": [
{
"id": 12345,
"uuid": "2b3535c4-17e1-422b-9e13-93e373f23f72",
"type": "multiple_choice",
"question_id": 25196,
"question": "Q1",
"question_options": [
"Option 1",
"Option 2",
"Option 3",
"Option 4"
],
"answer": "<Answer Text>",
"lock_date": null,
"created": 1646926650.753365,
"updated": 1646926650.753365,
"created_on": "2022-03-10 15:37:30.756187+00:00",
"modified_on": "2022-03-10 15:37:30.756248+00:00"
}
],
"updated": 1619290862.0,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "e83461a4-fa06-4014-80d3-e3e6cc3c1ccc"
},
"created": 1619290862.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "e83461a4-fa06-4014-80d3-e3e6cc3c1ccc"
},
"created_on": "2022-03-10 15:37:30.704686+00:00",
"modified_on": "2022-03-10 15:37:30.704731+00:00"
},
"employee_response": {
"id": 276,
"uuid": "d3c85b43-7dd7-4f32-9b12-820688f77b9e",
"name": "<First Name> <Last Name>",
"description": "",
"shared_on": 1647848875.409886,
"submitted_on": 1640014212.357601,
"unlocked_until": 1650014212.357601,
"responses": [
{
"id": 13847334,
"uuid": "3c32dd12-dd42-4fdf-81cf-75e82d763d8e",
"type": "text",
"question": "<Question Text>",
"question_options": null,
"answer": "<Answer Text>",
"lock_date": null,
"created": 1619290863.0,
"updated": 1619290863.0,
"created_on": "2022-03-10 15:37:30.811117+00:00",
"modified_on": "2022-03-10 15:37:30.811170+00:00"
},
{
"id": 13847335,
"uuid": "33249065-e170-4cf7-92ba-441b7c62ab52",
"type": "rating",
"question": "<question>",
"question_options": [
1,
2,
3,
4
],
"answer": "<Answer Text>",
"lock_date": null,
"created": 1619290863.0,
"updated": 1619290863.0,
"created_on": "2022-03-10 15:37:30.811117+00:00",
"modified_on": "2022-03-10 15:37:30.811170+00:00"
}
],
"updated": 1619290862.0,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "bf27a23e-e69b-4b94-9d73-a8436714136c"
},
"created": 1619290862.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "bf27a23e-e69b-4b94-9d73-a8436714136c"
},
"created_on": "2022-03-10 15:37:30.785382+00:00",
"modified_on": "2022-03-10 15:37:30.785433+00:00"
},
"post_employee_response": {
"id": 31,
"uuid": "ba9c7a6f-2658-4c9b-8bfa-2b699f2249c5",
"name": "<First Name> <Last Name>",
"description": "",
"shared_on": 1647848875.409886,
"submitted_on": 1650014212.357601,
"unlocked_until": 1660014212.357601,
"responses": [
{
"id": 14,
"uuid": "3c32dd12-dd42-7z1f-81cf-75e82d763d8e",
"type": "text",
"question": "<Question Text>",
"question_options": null,
"answer": "<Answer Text>",
"lock_date": null,
"created": 1619290862.0,
"updated": 1619290862.0,
"created_on": "2022-03-10 15:37:30.785382+00:00",
"modified_on": "2022-03-10 15:37:30.785433+00:00"
}
],
"updated": 1619290862.0,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "fad590a1-e751-40ab-a9e4-94e809099b0e"
},
"created": 1619290862.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "fad590a1-e751-40ab-a9e4-94e809099b0e"
},
"created_on": "2022-03-10 15:37:30.785382+00:00",
"modified_on": "2022-03-10 15:37:30.785433+00:00"
},
"post_manager_response": {
"id": 3101916,
"uuid": "dccc2954-7c89-4391-bc96-15681d7828dc",
"name": "<First Name> <Last Name>",
"description": "",
"shared_on": 1629914212.357601,
"submitted_on": 1630014212.357601,
"unlocked_until": 1640014212.357601,
"responses": [
{
"id": 14724707,
"uuid": "6e13161d-88af-4094-b80d-cb223bf70436",
"type": "text",
"question": "<Question Text>",
"question_options": null,
"answer": "<Answer Text>",
"lock_date": null,
"created": 1619290862.0,
"updated": 1619290862.0,
"created_on": "2022-03-10 15:37:30.785382+00:00",
"modified_on": "2022-03-10 15:37:30.785433+00:00"
}
],
"updated": 1619290862.0,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 3,
"uuid": "1016f966-c64d-46f6-8fb9-c1145cf04306"
},
"created": 1619290862.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 1,
"uuid": "28cc30ed-e8c6-4052-837f-d2dedb220378"
},
"created_on": "2022-03-10 15:37:30.785382+00:00",
"modified_on": "2022-03-10 15:37:30.785433+00:00"
},
"employee_submit_end": "2021-04-01",
"manager_submit_end": "2021-04-02",
"grace_period_end": "2021-04-10",
"employee_review_end": "2021-04-11",
"manager_review_end": "2021-04-12",
"manager_status": "post_hr_not_started",
"employee_status": "not_started",
"employee_notes": "<Employee Notes Text>",
"employee_notes_updated": 1671290862.0,
"manager_notes": "<Manager Notes Text>",
"manager_notes_updated": 1699290862.0,
"post_manager_questionnaire_pending": true,
"post_employee_questionnaire_pending": true,
"created": 1619290862.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "bf27a23e-e69b-4b94-9d73-a8436714136c"
},
"created_on": "2022-03-29 09:02:29.622155+00:00",
"modified_on": "2022-03-29 09:02:29.707286+00:00"
}
],
"more": true,
"nextUrl": "/api/v1/conversations/?deployment_id=111&size=1&page=2"
}
This endpoint will retrieve the list of conversations relative to a deployment_id.
HTTP Request
GET /api/v1/conversations/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| deployment_id | Required | Integer or UUID | The deployment ID of the list of conversations |
| manager_id | Optional | Integer or UUID | Filter conversations with Manager ID |
| employee_id | Optional | Integer | Filter conversations with Employee ID |
| delta_start | Optional | ISO Date | Filter conversations modified on or after |
| delta_end | Optional | ISO Date | Filter conversations modified on or before |
- Delta filters will filter on the
modified_onproperty for the following parameters- manager_response
- employee_response
- post_manager_response
- post_employee_response
Returns
Returns list of conversations relative to a deployment_id.
Departments
List Departments
Example Response:
{
"more": true,
"nextUrl": "/api/v1/departments/?page=2&size=2",
"num_pages": 2,
"page": 1,
"results": [
{
"id": 42,
"uuid": "c5886095-2b1a-4ec5-b18e-5e84cfc5416e",
"is_active": true,
"name": "<Department Name>",
"parent": null,
"created_on": "2021-12-13T20:43:05.085133Z",
"modified_on": "2021-12-13T20:43:05.085290Z"
},
{
"id": 43,
"uuid": "6552c7de-6497-4474-a6fe-60e76df5b912",
"is_active": true,
"name": "<Department Name>",
"parent": {
"id": 42,
"uuid": "0183dff0-d2ae-4b7f-841e-538ede550f09",
"name": "<Department Name>"
},
"created_on": "2021-12-13T20:43:05.085133Z",
"modified_on": "2021-12-13T20:43:05.085290Z"
}
]
}
Get list of departments
HTTP Request
GET /api/v1/departments/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| page | Optional | Integer | Page number of departments to return |
| size | Optional | Integer | Number of departments per page, default 20, max 100 |
| include_deactivated | Optional | Boolean | Whether to include deactivated departments, default false |
Returns
List of departments and pagination details
Create Department
Example Request:
{
"name": "New Department",
"parent_id": 27
}
Example Response:
{
"id": 29,
"uuid": "c5886095-2b1a-4ec5-b18e-5e84cfc5416e",
"is_active": true,
"name": "<Department Name>",
"parent": {
"id": 27,
"uuid": "0183dff0-d2ae-4b7f-841e-538ede550f09",
"name": "<Department Name>"
},
"created_on": "2021-12-13T20:43:05.085133Z",
"modified_on": "2021-12-13T20:43:05.085290Z"
}
HTTP Request
POST /api/v1/departments/
Payload Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| name | Required | String | Name of department to create. |
| parent_id | Optional | Integer | ID of parent department |
Returns
The created department object
Update Department
Example Request:
{
"name": "A Department",
"parent_id": 1
}
Example Response:
{
"id": 3,
"uuid": "c5886095-2b1a-4ec5-b18e-5e84cfc5416e",
"is_active": true,
"name": "<Department Name>",
"parent": {
"id": 1,
"uuid": "0183dff0-d2ae-4b7f-841e-538ede550f09",
"name": "<Department Name>"
},
"created_on": "2021-12-13T20:43:05.085133Z",
"modified_on": "2021-12-13T20:43:05.085290Z"
}
Updates the name and parent of a department
HTTP Request
PUT /api/v1/departments/:id/
Payload Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| name | Required | String | Name of department to update. |
| parent_id | Optional | Integer | ID of parent department |
Returns
The updated department object
Deactivate Department
Example Response:
{
"id": 3,
"uuid": "c5886095-2b1a-4ec5-b18e-5e84cfc5416e",
"is_active": false,
"name": "<Deactivated Department Name>",
"parent": null,
"created_on": "2021-12-13T20:43:05.085133Z",
"modified_on": "2021-12-13T20:43:05.085290Z"
}
Deactivates a department. Note departments must be empty to be deactivated.
HTTP Request
POST /api/v1/departments/:id/deactivate/
Returns
The deactivated department object
Reactivate Department
Example Response:
{
"id": 3,
"uuid": "c5886095-2b1a-4ec5-b18e-5e84cfc5416e",
"is_active": true,
"name": "<Reactivated Department Name>",
"parent": null,
"created_on": "2021-12-13T20:43:05.085133Z",
"modified_on": "2021-12-13T20:43:05.085290Z"
}
Reactivates a department.
HTTP Request
POST /api/v1/departments/:id/reactivate/
Returns
The reactivated department object
Update Departments
Example Request:
{
"departments": [
{
"name": "Existing Department",
"parent": "New Parent Department"
},
{
"name": "New Department",
"parent": "Existing Department"
}
]
}
Example Response:
{
"created": 1,
"updated": 1
}
Create or update the parents of multiple departments.
HTTP Request
POST /api/v1/departments/bulk/
Payload Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| departments | Required | List of Department |
Departments to be updated. |
Department
| Parameter | Required | Type | Description |
|---|---|---|---|
| name | Required | String | Name of department to create. Note: Case sensitive identifier used for lookup. |
| parent | Optional | String | Name of parent department |
Returns
A count of departments created and updated.
Feedback
In the Betterworks system, Feedback is a meaningful appraisal of your efforts that reinforces your areas of strength and identifies areas for personal and professional growth and development. Feedbacks have an id which can be used to filter in the API. Feedbacks follow a Feedback Template, designated by a template_id, which dictates the feedback attributes. They are given within a cycle and can be anytime (adhoc) or scheduled. Users can either request feedback or give feedback.
List Feedback Templates
Example Response:
{
"results": [
{
"id": 96,
"uuid": "3a5c9865-ea2b-4726-ae78-9e613a089536",
"type": "scheduled",
"name": "<Feedback Name>",
"enabled": false,
"cycles": [
{
"id": 95,
"uuid": "e1de836e-7ed6-496d-967c-c574c02fa021",
"cycle_start": "2020-01-16",
"selection_end": "2020-01-18",
"feedback_start": "2020-01-19",
"cycle_end": "2020-01-21",
"grace_period_end": "2021-01-31",
"enable_anytime_nomination": true
}
],
"created": 1579043174.0,
"updated": 1591862820.0,
"created_on": "2020-01-14T23:06:14.732630Z",
"modified_on": "2021-07-15T06:21:58.681106Z",
"questions_locked": false,
"questions": [
{
"id": 41,
"uuid": "cd617ecd-9e56-4151-99c0-5d0b261d89de",
"template_id": 96,
"type": "text",
"text": "<Question Text>",
"options": null,
"hide_numbers": false,
"order": 0,
"mandatory": true
},
{
"id": 42,
"uuid": "afd0bfd5-217f-4a13-ab83-6443effe85af",
"template_id": 96,
"type": "multiple_choice",
"text": "<Question Text>",
"options": [
"Vanilla",
"Chocolate",
"Strawberry"
],
"hide_numbers": false,
"order": 1,
"mandatory": true
},
{
"id": 43,
"uuid": "6ed8d302-700d-48d2-90d1-5793fd1f117b",
"template_id": 96,
"type": "rating",
"text": "<Question Text>",
"options": [
1,
2,
3
],
"hide_numbers": false,
"order": 2,
"mandatory": true
}
],
"allowed_employees": [
{
"name": "<First Name> <Last Name>",
"id": 1,
"uuid": "ca3c10c3-7c3c-4d69-9f56-f2511d17bd1e"
},
{
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "c9895fac-69f9-41ee-832d-e9f1c18ef422"
}
],
"allowed_providers": [
{
"name": "<First Name> <Last Name>",
"id": 3,
"uuid": "245fdc59-bfe9-464e-9763-44cd71f324ca"
},
{
"name": "<First Name> <Last Name>",
"id": 4,
"uuid": "c9f9f8e1-f8c8-4f0e-b9c6-f8f8f8f8f8f8"
}
],
"notify_cycle_started": true,
"notify_feedback_reminder": false,
"notify_feedback_requested": true,
"employee_can_choose": true,
"employee_can_view": true,
"employee_see_identity": true,
"manager_can_choose": true,
"manager_can_view": true,
"manager_see_identity": true,
"skip_level_can_view": false,
"skip_level_see_identity": false,
"skip_level_managers_level": "none",
"default_provider_type": "classic_360",
"default_providers_limit": 6,
"default_providers_includes_manager": true,
"default_providers_includes_directs": true,
"default_providers_includes_peers": true,
"summary_visible_employee": true,
"summary_visible_manager": true,
"hold_feedback": false
}
],
"more": true,
"nextUrl": "/api/v1/feedback/templates/?size=1&page=2"
}
Get list of feedback templates
HTTP Request
GET /api/v1/feedback/templates/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| type | Optional | Enum | Type of feedback template. Accepts scheduled, adhoc_give, adhoc_request, adhoc_manager_request or adhoc_request_custom |
Returns
List of feedback template details
Get Feedback Template
Example Response:
{
"id": 96,
"uuid": "3a5c9865-ea2b-4726-ae78-9e613a089536",
"type": "scheduled",
"name": "<Feedback Name>",
"enabled": false,
"cycles": [
{
"id": 95,
"uuid": "e1de836e-7ed6-496d-967c-c574c02fa021",
"cycle_start": "2020-01-16",
"selection_end": "2020-01-18",
"feedback_start": "2020-01-19",
"cycle_end": "2020-01-21",
"grace_period_end": "2021-01-31",
"enable_anytime_nomination": true
}
],
"created": 1579043174.0,
"updated": 1591862820.0,
"created_on": "2020-01-14T23:06:14.732630Z",
"modified_on": "2021-07-15T06:21:58.681106Z",
"questions_locked": false,
"questions": [
{
"id": 41,
"uuid": "cd617ecd-9e56-4151-99c0-5d0b261d89de",
"template_id": 96,
"type": "text",
"text": "<Question Text>",
"options": null,
"hide_numbers": false,
"order": 0,
"mandatory": true
},
{
"id": 42,
"uuid": "afd0bfd5-217f-4a13-ab83-6443effe85af",
"template_id": 96,
"type": "multiple_choice",
"text": "<Question Text>",
"options": [
"Vanilla",
"Chocolate",
"Strawberry"
],
"hide_numbers": false,
"order": 1,
"mandatory": true
},
{
"id": 43,
"uuid": "6ed8d302-700d-48d2-90d1-5793fd1f117b",
"template_id": 96,
"type": "rating",
"text": "<Question Text>",
"options": [
1,
2,
3
],
"hide_numbers": false,
"order": 2,
"mandatory": true
}
],
"allowed_employees": [
{
"name": "<First Name> <Last Name>",
"id": 1,
"uuid": "ca3c10c3-7c3c-4d69-9f56-f2511d17bd1e"
},
{
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "c9895fac-69f9-41ee-832d-e9f1c18ef422"
}
],
"allowed_providers": [
{
"name": "<First Name> <Last Name>",
"id": 3,
"uuid": "245fdc59-bfe9-464e-9763-44cd71f324ca"
},
{
"name": "<First Name> <Last Name>",
"id": 4,
"uuid": "c9f9f8e1-f8c8-4f0e-b9c6-f8f8f8f8f8f8"
}
],
"notify_cycle_started": true,
"notify_feedback_reminder": false,
"notify_feedback_requested": true,
"employee_can_choose": true,
"employee_can_view": true,
"employee_see_identity": true,
"manager_can_choose": true,
"manager_can_view": true,
"manager_see_identity": true,
"skip_level_can_view": false,
"skip_level_see_identity": false,
"skip_level_managers_level": "none",
"default_provider_type": "classic_360",
"default_providers_limit": 6,
"default_providers_includes_manager": true,
"default_providers_includes_directs": true,
"default_providers_includes_peers": true,
"summary_visible_employee": true,
"summary_visible_manager": true,
"hold_feedback": false
}
Returns details for a specific feedback template using template id
HTTP Request
GET /api/v1/feedback/templates/:id
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | Feedback template ID |
Returns
Feedback template object
List Feedback
Example Response:
{
"results": [
{
"id": 83,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"name": "<Feedback Name>",
"cycle_id": 17,
"cycle": {
"id": 17,
"uuid": "069d22d0-edbe-4640-a310-bcd736541aff",
"cycle_start": "2021-04-17",
"selection_end": "2021-04-19",
"feedback_start": "2021-04-20",
"cycle_end": "2021-05-06",
"grace_period_end": "2021-05-31",
"enable_anytime_nomination": true
},
"for_user": {
"name": "<First Name> <Last Name>",
"id": 12,
"uuid": "9d77d732-0f99-4e12-bfe2-85f17916000a"
},
"requested_by": {
"name": "<First Name> <Last Name>",
"id": 13,
"uuid": "5aae0d03-18e7-4f26-a9c3-e70045982614"
},
"created": 1620121371.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 13,
"uuid": "9d77d732-0f99-4ej8-bfe2-85f17916000a"
},
"updated": 1620121381.0,
"responses": [
{
"id": 10,
"uuid": "ff831534-3c4e-4737-9c32-0d5b5f252005",
"question": "<Question Text>",
"question_id": 67,
"question_options": null,
"type": "text",
"feedback_id": 83,
"answer": "<Answer Text>",
"hide_numbers": false
},
{
"id": 11,
"uuid": "978b2fc9-b545-4c6e-9a4b-de96f96b8b8c",
"question": "<Question Text>",
"question_id": 70,
"question_options": [
1,
2,
3
],
"type": "scale",
"feedback_id": 83,
"answer": 3,
"hide_numbers": true
},
{
"id": 12,
"question": "<Question Text>",
"question_id": 71,
"question_options": [
1,
2,
3,
4
],
"type": "rating",
"feedback_id": 83,
"answer": 2,
"hide_numbers": false
},
{
"id": 13,
"question": "<Question Text>",
"question_id": 72,
"question_options": [
"A",
"B"
],
"type": "multiple_choice",
"feedback_id": 83,
"answer": [
"B"
],
"hide_numbers": false
}
],
"created_on": "2022-03-16T17:28:48.103015Z",
"modified_on": "2022-03-16T17:28:50.173265Z",
"employee_can_view": true,
"manager_can_view": true,
"employee_see_identity": true,
"manager_see_identity": true,
"hold_feedback": false,
"status": "submitted",
"template_name": "<Feedback Name>",
"template_type": "scheduled"
},
{
"id": 84,
"uuid": "5745bc82-1dbb-48f6-a8c0-d9ec66c116cf",
"name": "<Feedback Name>",
"cycle_id": 17,
"cycle": {
"id": 17,
"uuid": "fcf5e435-f3f9-478d-8970-3d10eb4e5a52",
"cycle_start": "2021-04-17",
"selection_end": "2021-04-19",
"feedback_start": "2021-04-20",
"cycle_end": "2021-05-06",
"grace_period_end": "2021-05-31",
"enable_anytime_nomination": true
},
"for_user": {
"name": "<First Name> <Last Name>",
"id": 12,
"uuid": "e9194faa-4497-4a8c-a744-31330fd49dde"
},
"requested_by": {
"name": "<First Name> <Last Name>",
"id": 16,
"uuid": "ff4cddb4-819c-4686-9925-851a0f97ff42"
},
"created": 1620121372.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 14,
"uuid": "48f581b7-3efc-4cba-bdd6-0e21964c2910"
},
"updated": 1620121381.0,
"responses": [
{
"id": 11,
"uuid": "ca532749-803e-4ef6-8bee-b34c976bbb72",
"question": "<Question Text>",
"question_id": 70,
"question_options": null,
"type": "text",
"feedback_id": 84,
"answer": "<Answer Text>",
"hide_numbers": false
}
],
"employee_can_view": true,
"manager_can_view": true,
"employee_see_identity": false,
"manager_see_identity": true,
"hold_feedback": false,
"status": "answering",
"template_name": "<Feedback Name>",
"template_type": "scheduled",
"created_on": "2019-01-01T12:00:00.123456Z",
"modified_on": "2019-01-02T12:00:00.123456Z"
}
],
"more": true,
"nextUrl": "/api/v1/feedback/?for_user_id=12&size=1&page=2"
}
Get feedback for a specific cycle_id and/or for_user_id. One of these fields is required to pull feedback data. If cycle_id, all feedback related to that cycle id will be populated. If for_user_id, all feedback related to that user id will be populated
HTTP Request
GET /api/v1/feedback/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| for_user_id | Optional | Integer or UUID | The ID of the user that received feedback |
| cycle_id | Optional | Integer or UUID | The feedback cycle ID |
| delta_start | Optional | ISO Date | Filter feedback modified on or after |
| delta_end | Optional | ISO Date | Filter feedback modified on or before |
Returns
List of feedback details
List Feedback Requests
Example Response:
{
"results": [
{
"id": 3877,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"cycle": {
"id": 2207,
"uuid": "7f98b0b2-e31d-425a-8966-332353cecde3",
"cycle_start": "2022-02-15",
"selection_end": "2022-02-17",
"feedback_start": "2022-02-18",
"cycle_end": "2022-02-28",
"grace_period_end": "2022-04-22",
"enable_anytime_nomination": true
},
"adhoc_cycle": {
"id": 1014,
"template_id": 2662,
"template_name": "<Template Name>",
"template_questions": [
"Question One",
"Question Two",
"Question Three"
],
"questions_locked": false
},
"from_user": {
"id": 184,
"uuid": "8b04af57-a65d-4fe3-8b94-078bad2e0030",
"first_name": "<First Name>",
"preferred_name": "<Preferred Name>",
"last_name": "<Last Name>",
"name": "<First Name> <Last Name>",
"email": "<Email>",
"is_active": true,
"deactivated_on": "2021-12-31T19:20:13.616730Z",
"deactivation_date": "2021-12-31",
"title": "<Title>",
"manager": {
"name": "<First Name> <Last Name>",
"id": 487,
"uuid": "623406e0-54f2-407f-84db-d41561cddb83"
},
"department": {
"name": "<Department Name>",
"id": 3,
"uuid": "5330cc44-b90d-4a05-ae3b-329128e2f6b6"
},
"phone": "<Phone Number>",
"about": "<About Text>",
"locale": "en",
"is_goalmaster": false,
"is_super_admin": false,
"is_admin": false,
"is_group_admin": false,
"employee_id": "23",
"created_on": "2021-11-10T21:28:48.951160Z",
"modified_on": "2022-01-14T03:00:02.095716Z",
"attributes": {
"on_leave": false
},
"custom_values": {
"custom_01": "<Custom Text>",
"custom_02": "<Custom Text>",
}
},
"for_user": {
"id": 519,
"uuid": "d44906e5-7dbc-46f5-b312-5f35937f8cd3",
"first_name": "<First Name>",
"preferred_name": "<Preferred Name>",
"last_name": "<Last Name>",
"name": "<First Name> <Last Name>",
"email": "<Email>",
"is_active": true,
"deactivated_on": null,
"deactivation_date": null,
"title": "<Title>",
"manager": {
"name": "<First Name> <Last Name>",
"id": 589
},
"department": {
"name": "<Department Name>",
"id": 3,
"uuid": "5330cc44-b90d-4a05-ae3b-329128e2f6b6"
},
"phone": "<Phone Number>",
"about": "<About Text>",
"locale": "en",
"is_goalmaster": false,
"is_super_admin": false,
"is_admin": false,
"is_group_admin": false,
"employee_id": "24",
"created_on": "2021-11-10T21:28:48.951160Z",
"modified_on": "2021-12-08T00:48:23.249611Z",
"attributes": {
"preferred_name": "<Preferred Name>",
"on_leave": false
},
"custom_values": {
"custom_03": "<Custom Text>",
"custom_04": "<Custom Text>",
}
},
"requested_by": {
"id": 387801,
"uuid": "54740921-7031-40d3-bji6-fb798ddf763d",
"first_name": "<First Name>",
"preferred_name": "<Preferred Name>",
"last_name": "<Last Name>",
"name": "<First Name> <Last Name>",
"email": "<Email>",
"is_active": false,
"deactivated_on": null,
"deactivation_date": null,
"title": "<Title>",
"manager": {
"name": "<First Name> <Last Name>",
"id": 129,
"uuid": "f4b989ab-3323-4ead-b2a5-95228ec1b721"
},
"department": {
"name": "<Department Name>",
"id": 4,
"uuid": "2c249239-bcba-4900-a164-fcc211942eb1"
},
"phone": "",
"about": "",
"locale": "en",
"is_goalmaster": false,
"is_super_admin": true,
"is_admin": false,
"is_group_admin": false,
"employee_id": "2341242",
"created_on": "2021-12-21T04:54:45.790728Z",
"modified_on": "2022-03-16T04:39:00.252944Z",
"attributes": {
"on_leave": false
},
"custom_values": {
"custom_05": "<Custom Text>",
"custom_06": "<Custom Text>",
}
},
"feedback_id": 1811,
"feedback_uuid": "5cf610b3-830c-41f4-8a4d-5f770fb489ca",
"question": "<Question Text>",
"declined": null,
"can_view_feedback": true,
"hold_feedback": false,
"created": 1633811615.591184,
"created_by": {
"id": 519,
"uuid": "286dc269-89fc-4b55-97f2-cfab29b0aad6",
"first_name": "<First Name>",
"preferred_name": "<Preferred Name>",
"last_name": "<Last Name>",
"name": "<First Name> <Last Name>",
"email": "<Email>",
"is_active": true,
"deactivated_on": null,
"deactivation_date": null,
"title": "<Title>",
"manager": {
"name": "<First Name> <Last Name>",
"id": 589,
"uuid": "e30afc69-1e50-4993-af1d-ddc1f1e3798e"
},
"department": {
"name": "<Department Name>",
"id": 4,
"uuid": "2c249239-bcba-4900-a164-fcc211942eb1"
},
"phone": "<Phone Number>",
"about": "<About Text>",
"locale": "en",
"is_goalmaster": false,
"is_super_admin": false,
"is_admin": false,
"is_group_admin": false,
"employee_id": "513",
"attributes": {
"on_leave": false
},
"custom_values": {
"custom_07": "<Custom Text>",
"custom_08": "<Custom Text>",
}
},
"status": 0,
"template_id": 7,
"template_uuid": "d02f4eb0-8a2c-4880-b76f-db6bbb8f607d",
"expired": null,
"created_on": "2019-01-01T12:00:00.123456Z",
"modified_on": "2019-01-02T12:00:00.123456Z",
"custom_note": "<Note Text>"
}
],
"more": true,
"nextUrl": "/api/v1/feedback/requests/?size=1&page=2"
}
Returns details for feedback requests
HTTP Request
GET /api/v1/feedback/requests/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| cycle | Optional | Integer or UUID | The cycle ID of the feedback cycle |
| from_user | Optional | Integer or UUID | The ID of the user that provided the feedback |
| for_user | Optional | Integer or UUID | The ID of the user that received the feedback |
| declined | Optional | Boolean | Filter feedback requests that are declined or not |
| questions | Optional | Boolean | Whether to include questions in feedback requests, default false |
| is_open | Optional | Boolean | Filter feedback requests that are currently active or not |
| is_adhoc | Optional | Boolean | Filter feedback requests that are anytime or not |
| delta_start | Optional | ISO Date | Filter feedback requests modified on or after |
| delta_end | Optional | ISO Date | Filter feedback requests modified on or before |
Returns
List of feedback requests
Goals
Goals and Milestones
In the Betterworks system, Goals may have any number of milestones (also called Key Results) or
other goals as children which will contribute to their parent’s progress. Goals and Milestones are
serialized nearly identically, with Milestones being identifiable by the is_key_result: true
attribute.
Throughout the API both Goals and Milestones can be referenced interchangeably by
goals/:goal_id in the URL, though the specific endpoints may handle them differently.
Get a Specific Goal
Example Response:
{
"description": "<Goal Description>",
"id": 115,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"name": "<Goal Name>",
"is_key_result": false,
"end": "2016-06-28",
"start": "2016-06-21",
"measurement": {
"progress": 1.0,
"initial": 0.0,
"target": 100.0,
"unit": "Percent",
"done": false,
"lower_limit": 1.0,
"lower_mid": 25.0,
"upper_limit": 110.0,
"upper_mid": 105.0,
"current": 78.0,
"updated": 1501239228.920303,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 25,
"uuid": "ca3c10c3-7c3c-4d69-9f56-f2511d17bd1e"
},
"type": "manualprogress",
"expected": 1.0,
"condition": "green",
"is_binary": false,
"is_numeric": true
},
"owner": {
"user": {
"name": "<First Name> <Last Name>",
"id": 25,
"uuid": "ca3c10c3-7c3c-4d69-9f56-f2511d17bd1e"
},
"group": {
"id": 218,
"uuid": "5eb928a2-34f8-4d1f-8ef1-f8a7b600e774",
"name": "<Group Name>",
"parent_id": 719,
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"is_team": false
},
"team": {
"id": 123,
"uuid": "a837d70f-cecb-4ea1-835b-1316c04e8317",
"name": "<Team Name>",
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"created_on": "2021-11-10T21:28:29.610217Z",
"modified_on": "2021-26-10T21:19:18.391311Z"
}
},
"parent": {
"name": "<Goal Name>",
"id": 34,
"uuid": "646d0cbd-f47c-4d14-a6d0-cb9c62b4c68c"
},
"children": [
{
"name": "<Goal Name>",
"id": 116,
"uuid": "6cabcd2d-57e1-492b-9d2a-9ff6cc001e04"
}
],
"updated": 1453420800.0,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 25,
"uuid": "ca3c10c3-7c3c-4d69-9f56-f2511d17bd1e"
},
"visibility": "public",
"integration": {
"type": "jira",
"last_sync": 1665604002.151043,
"identifier": "3833e446-ee67-4bd3-a79c-af060401ad66",
},
"stats": {
"comments": 1,
"cheers": 1,
"nudges": 1,
"views": 5,
"last_assessed": 1467091175.817682
},
"categories": [
{
"name": "<Category Name>",
"id": 1,
"uuid": "60e97d78-cc6a-4bb3-8067-9bbcef5ecd80"
}
],
"attribute_type": 1,
"attribute_scope": 1,
"created": 1453420800.0,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 25,
"uuid": "ca3c10c3-7c3c-4d69-9f56-f2511d17bd1e"
},
"last_checkedin": 1467115788.350479,
"last_checkedin_by": {
"name": "<First Name> <Last Name>",
"id": 4,
"uuid": "16534a8a-d12f-47a8-94bf-7307728bee12"
},
"created_on": "2021-07-19T16:02:11.394597Z",
"modified_on": "2021-11-28T10:53:48.920303Z"
}
This endpoint will retrieve the full details about a specific goal within your organization.
HTTP Request
GET /api/v1/goals/:id/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | The goal ID |
Returns
The Goal object with the specified ID.
Update a Specific Goal
Example Request:
{
"description": "<Updated Goal Description>",
"key_results": [
{
"name": "<Updated Key Result Name>",
"id": 2,
}
]
}
Example Response:
{
"description": "<Updated Goal Description>",
"id": 1,
"uuid": "cfd64af5-ec10-40c3-b8c2-0f1f7518af6a",
"name": "<Goal Name>",
"is_key_result": false,
"start": "2022-09-21",
"end": "2022-12-21",
"measurement": {
"progress": 0.2,
"initial": null,
"target": null,
"unit": "",
"done": false,
"lower_limit": null,
"lower_mid": null,
"upper_limit": null,
"upper_mid": null,
"current": null,
"updated": 1664306544.276585,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "38e75a89-7fd7-48db-aead-b08560c30e9a"
},
"type": "avgofprogress",
"expected": 0.09,
"condition": "green",
"is_binary": true,
"is_numeric": false
},
"owner": {
"user": {
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "38e75a89-7fd7-48db-aead-b08560c30e9a"
},
"group": null,
"team": null
},
"parent": null,
"children": [
{
"name": "<Key Result Name>",
"id": 3,
"uuid": "75ebe19a-ce6e-499e-8124-908bb2ef0f4a",
"modified_on": "2022-09-21T16:42:30.752327Z"
},
{
"name": "<Updated Key Result Name>",
"id": 2,
"uuid": "78db7f7e-c07d-4b74-b3b2-0d92aa812095",
"modified_on": "2022-09-29T18:55:02.550704Z"
}
],
"updated": 1664477702.414093,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "38e75a89-7fd7-48db-aead-b08560c30e9a"
},
"visibility": "private",
"integration": null,
"stats": {
"comments": 0,
"cheers": 0,
"nudges": 0,
"views": 1,
"last_assessed": null
},
"categories": [],
"attribute_type": null,
"attribute_scope": null,
"created": 1663778550.364967,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "38e75a89-7fd7-48db-aead-b08560c30e9a"
},
"last_checkedin": 1664306544.276585,
"last_checkedin_by": {
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "38e75a89-7fd7-48db-aead-b08560c30e9a"
},
"created_on": "2022-09-21T16:42:30.389180Z",
"modified_on": "2022-09-29T18:55:02.533659Z"
}
This endpoint will update a specific goal within your organization.
HTTP Request
PUT /api/v1/goals/:id/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | The goal ID OR the key result ID |
Payload Parameters
Goal Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| owner | Optional | Owner Object | Owner object (see below) |
| name | Optional | String | Goal name |
| parent | Optional | Integer or UUID | Parent goal ID |
| visibility | Optional | String | Visibility of the goal - must be one of [“public”, “private”] |
| description | Optional | String | Goal description |
| start | Optional | Date | Goal start date |
| end | Optional | Date | Goal end date |
| key_results | Optional | Array of Objects | Array of key result objects (see below) |
| unit | Optional | String | Measurement unit |
| target | Optional | Float | Target value |
| initial | Optional | Float | Initial value |
| lower_limit | Optional | Integer | Lower measurement limit |
| lower_mid | Optional | Integer | Lower measurement mid |
| upper_limit | Optional | Integer | Upper measurement limit |
| upper_mid | Optional | Integer | Upper measurement mid |
| type | Optional | String | Measurement type - must be one of [“avgofprogress”, “sumofcurrent”, “sumofrange”, “manualprogress”] |
| auto_target | Optional | Boolean | Auto target |
| attribute_scope | Optional | String | Attribute scope ID - must be one of [“business”, “personal”, “developmental”] |
| attribute_type | Optional | String | Attribute type ID - must be one of [“committed”, “aspirational”] |
Key Result Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | Key result ID |
| delete | Optional | Boolean | Delete key result |
| create | Optional | Boolean | Create key result |
| owner | Optional | Object | Owner object (see below) |
| name | Optional | String | Key result name |
| start | Optional | Date | Start date |
| end | Optional | Date | End date |
| unit | Optional | String | Measurement unit |
| target | Optional | Float | Target value |
| initial | Optional | Float | Initial value |
| lower_limit | Optional | Integer | Lower measurement limit |
| lower_mid | Optional | Integer | Lower measurement mid |
| upper_limit | Optional | Integer | Upper measurement limit |
| upper_mid | Optional | Integer | Upper measurement mid |
| type | Optional | String | Measurement type - must be one of [“binary”, “numeric”, “range”] |
| auto_target | Optional | Boolean | Auto target |
| attribute_scope | Optional | String | Attribute scope ID - must be one of [“business”, “personal”, “developmental”] |
| attribute_type | Optional | String | Attribute type ID - must be one of [“committed”, “aspirational”] |
Owner Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| user_id | Required | Integer or UUID | User ID |
Delete a Specific Goal
Example Request:
DELETE /api/v1/goals/123/
Example Response:
{}
This endpoint will delete a specific goal within your organization.
HTTP Request
DELETE /api/v1/goals/:id/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | The goal ID |
Returns
HTTP Status 204 No Content.
Create a New Goal
Example Request:
{
"name": "<Goal Name>",
"description": "<Goal Description>",
"parent": "646d0cbd-f47c-4d14-a6d0-cb9c62b4c68c",
"start": "08/01/2022",
"end": "12/31/2022",
"owner": {
"user_id": "8277ffa7-6e30-4989-8ac2-963160a45e43"
},
"categories": ["123", "456"],
"visibility": "public",
"creation_source": "manual",
"key_results": [
{
"id": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"name": "<Key Result Name>",
"owner": {
"user_id": "8277ffa7-6e30-4989-8ac2-963160a45e43"
},
"start": "08/01/2022",
"end": "10/31/2022",
"type": "numeric",
"target": 100.00,
"unit": "Percent",
"auto_target": false,
"attribute_scope": "business",
"attribute_type": "committed",
"unit": "Percent",
"initial": 0
}
],
"type": "manualprogress",
"target": 100.00,
"initial": 10,
"name": "Goal One",
"unit": "Percent",
"lower_limit": 0,
"lower_mid": 30,
"upper_mid": 70,
"upper_limit": 100,
"auto_target": false,
"attribute_scope": "business",
"attribute_type": "committed"
}
Example Response:
{
"id": 29,
"uuid": "c5886095-2b1a-4ec5-b18e-5e84cfc5416e",
"is_active": true,
"name": "<Department Name>",
"parent": {
"id": 27,
"uuid": "0183dff0-d2ae-4b7f-841e-538ede550f09",
"name": "<Department Name>"
},
"created_on": "2021-12-13T20:43:05.085133Z",
"modified_on": "2021-12-13T20:43:05.085290Z"
}
This endpoint will create a new goal within your organization.
HTTP Request
POST /api/v1/goals/
Payload Parameters
Goal Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| owner | Required | Owner Object | Owner object (see below) |
| name | Required | String | Goal name |
| description | Optional | String | Goal description |
| parent | Optional | Integer or UUID | Parent goal ID |
| start | Required | Date | Goal start date |
| end | Required | Date | Goal end date |
| categories | Required if “Require Goal Categories” is True |
Array of Integer or UUID | Array of category IDs |
| visibility | Required | String | Visibility of the goal - must be one of [“public”, “private”] |
| creation_source | Required | String | Source of the goal - must be one of [“manual”, “converted”, “default”] |
| key_results | Optional | Array of Objects | Array of key result objects (see below) |
| type | Required | String | Measurement type - must be one of [“avgofprogress”, “sumofcurrent”, “sumofrange”, “manualprogress”] |
| target | Optional | Float | Target value |
| initial | Optional | Float | Initial value |
| unit | Required if type is one of [“sumofcurrent”, “sumofrange”, “manualprogress”] | String | Measurement unit |
| lower_limit | Required if type is “sumofrange” |
Integer | Lower measurement limit |
| lower_mid | Required if type is “sumofrange” |
Integer | Lower measurement mid |
| upper_limit | Required if type is “sumofrange” |
Integer | Upper measurement limit |
| upper_mid | Required if type is “sumofrange” |
Integer | Upper measurement mid |
| auto_target | Optional | Boolean | Auto target |
| attribute_scope | Required if “Require Goal Scope” is True |
String | Attribute scope ID - must be one of [“business”, “personal”, “developmental”] |
| attribute_type | Required if “Required Goal Type” is True |
String | Attribute type ID - must be one of [“committed”, “aspirational”] |
Key Result Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Optional | Integer or UUID | Key result ID |
| owner | Required | Object | Owner object (see below) |
| name | Required | String | Key result name |
| start | Optional | Date | Start date |
| end | Optional | Date | End date |
| type | Required | String | Measurement type - must be one of [“binary”, “numeric”, “range”] |
| target | Required | Float | Target value |
| unit | Required if type is one of [“numeric”, “range”] |
String | Measurement unit |
| lower_limit | Required if type is “range” |
Integer | Lower measurement limit |
| lower_mid | Required if type is “range” |
Integer | Lower measurement mid |
| upper_limit | Required if type is “range” |
Integer | Upper measurement limit |
| upper_mid | Required if type is “range” |
Integer | Upper measurement mid |
| auto_target | Optional | Boolean | Auto target |
| attribute_scope | Required if “Require Key Result Scope” is True |
String | Attribute scope ID - must be one of [“business”, “personal”, “developmental”] |
| attribute_type | Required if “Require Key Result Type” is True |
String | Attribute type ID - must be one of [“committed”, “aspirational”] |
Owner Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| user_id | Required | Integer or UUID | User ID |
Returns
The goal object that was created.
Filter
Returns all goals and milestones matching the filter criteria.
HTTP Request
GET /api/v1/goals/filter/
Query Parameters
| Parameter | Type | Description | Modifiers |
|---|---|---|---|
| owner | Integer or UUID | Filter goals owned by the specified user ID | Direct, negate |
| aligned_to_goal | Integer or UUID | Filter for goals aligned to the specified goal ID | Direct, negate |
| aligned_to_owner | Integer or UUID | Filter all goals aligned to the person you choose | Direct, negate |
| team_only | Boolean | Filter goals to only those owned by users on your team, accepts yes or no (no will filter out any goals owned by your team) |
None |
| group | Integer or UUID | Filters goals in the specified group (department) by ID | Empty (filter for “no group” goals only |
| reports_to | Integer or UUID | Filters goals owned by users who report to the specified manager | Direct, negate |
| visibility | Boolean | Filter goals by visibility, accepts public or private |
None |
| permission | Enum | Filters goals that the current user can_edit or can_only_view |
None |
| following | Boolean | Filters goals that the current user is following, accepts yes or no (no will filter out any followed goals) |
None |
| category | Integer or UUID | Filter goals by the specified category ID | Empty (uncategorized goals), Intersect |
| assessment | Boolean | Filter goals that have been assessed, accepts yes or no |
None |
| risk | String | Filter by risk status, must be ontrack needsattention or atrisk |
None |
| integration | Enum | Filters for goals using specific integrations, currently accepts salesforce, jira, or tableau |
Empty (no integrations) |
| unit | String | Filters for goals with units in their milestones | Empty (no units) |
| top_company_goal | Boolean | Filters for top company goals, accepts yes or no (no will filter out any top company goals) |
None |
| goal_name | Goal | Filter by goal entities by matching names | None |
| date_range | Date_range | Filter for goals that are active during the specified date range, formatted as MM/DD/YYYY-MM/DD/YYYY |
Negate |
| updated_since | Date_range | Filter for key results that have been updated since the date, formatted as MM/DD/YYYY-MM/DD/YYYY |
Negate |
| viewed_by_owner_date | Date_range | Filter goals owned by the current user that they viewed within the specified date range, formatted as MM/DD/YYYY-MM/DD/YYYY |
None |
| delta_start | ISO Date | Filter goals modified on or after | None |
| delta_end | ISO Date | Filter goals modified on or before | None |
Returns
Returns a results list of up to size goals that matched the given filter criteria and the boolean flag more if these results are not the end of the list.
Search Goals
Example Request:
GET /api/v1/goals/search/?q=needle&size=2
Example Response:
{
"results": [
{
"description": "<Goal Description>",
"id": 153,
"uuid": "e98d4f17-99c5-418a-ac70-f1fe27c739f7",
"name": "<Goal Name>",
"is_key_result": false,
"end": "2016-02-21",
"start": "2016-01-21",
"measurement": {
"progress": 0.5,
"initial": 0.0,
"target": 100.0,
"unit": "Percent",
"done": false,
"lower_limit": 80,
"lower_mid": 40,
"upper_limit": 100,
"upper_mid": 50,
"current": 25.0,
"updated": 1474465620.044385,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "4d71e697-dbd0-48a2-99f6-84ca1a9764db"
},
"type": "avgofprogress",
"expected": 1.0,
"condition": "yellow",
"is_binary": true,
"is_numeric": false
},
"owner": {
"user": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "4d71e697-dbd0-48a2-99f6-84ca1a9764db"
},
"group": {
"id": 218,
"uuid": "5eb928a2-34f8-4d1f-8ef1-f8a7b600e774",
"name": "<Group Name>",
"parent_id": 719,
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"is_team": false
},
"team": {
"id": 123,
"uuid": "a837d70f-cecb-4ea1-835b-1316c04e8317",
"name": "<Team Name>",
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"created_on": "2021-11-10T21:28:29.610217Z",
"modified_on": "2021-26-10T21:19:18.391311Z"
},
},
"parent": {
"name": "<Goal Name>",
"id": 34,
"uuid": "646d0cbd-f47c-4d14-a6d0-cb9c62b4c68c"
},
"children": [
{
"name": "<Goal Name>",
"id": 154,
"uuid": "94431760-47fb-464d-9003-b985d7f14afb"
}
],
"updated": 1453420800.0,
"updated_by": {
"name": "<First Name> <Last Name>",
"id": 21,
"uuid": "4d71e697-dbd0-48a2-99f6-84ca1a9764db"
},
"visibility": "public",
"integration": {
"type": "sheets",
"last_sync": 1665604002.151043,
"identifier": "3833e446-ee67-4bd3-a79c-af060401ad66",
},
"stats": {
"cheers": 1,
"comments": 3,
"last_assessed": 1490781811.178752,
"nudges": 0,
"views": 7
},
"categories": [
{
"name": "<Category Name>",
"id": 123,
"uuid": "60e97d78-cc6a-4bb3-8067-9bbcef5ecd80"
}
],
"attribute_type": 2,
"attribute_scope": 3,
"created": 1474463786.123895,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "4d71e697-dbd0-48a2-99f6-84ca1a9764db"
},
"last_checkedin": 1474465620.044385,
"last_checkedin_by": {
"name": "<First Name> <Last Name>",
"id": 11,
"uuid": "4d71e697-dbd0-48a2-99f6-84ca1a9764db"
},
"created_on": "2019-01-01T12:00:00.123456Z",
"modified_on": "2020-01-02T12:00:00.123456Z"
}
],
"more": true,
"nextUrl": "/api/v1/goals/search/?q=needle&page=2&size=1"
}
Returns all goal matching the search criteria. Matches on goal name.
HTTP Request
GET /api/v1/goals/search/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| q | Required | String | Text string (minimum length of 3) to be compared against goal name. |
| visibility | Optional | Enum | Search for public or private goals. |
| goal_type | Optional | Enum | Search for goals whose type is avgofprogress, sumofcurrent or sumofrange. |
| not_due | Optional | Flag | Search for goals that have not yet ended. |
| current | Optional | Flag | Search for goals that are currently active. |
| current_stale | Optional | Flag | Search for goals that are current or expired within 7 days. |
| future | Optional | Flag | Search for goals that have yet to start. |
Returns
Returns a goal dictionary that contains an empty objects list if no users were found, or an objects list of up to size users and the boolean flag more if these results are not the end of the list.
Search Goal Categories
Example Request:
GET /api/v1/goals/categories/search/?size=1&page=1&q=category
Example Response:
{
"more": true,
"results": [
{
"id": 1,
"name": "Goal Category 1",
"updated": 1664310650.420348,
"updated_by_id": 2,
"created": 1664310650.420348,
"created_by_id": 2
}
],
"nextUrl": "/api/v1/goals/categories/search/?size=1&page=2&q=category"
}
Returns all goal categories matching the search criteria. Matches on category name.
HTTP Request
GET /api/v1/goals/categories/search/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| q | Optional | String | Text string to be compared against category name |
Returns
Returns a list of goal categories matching the search criteria. Returns an empty list if no categories were found.
Comments
Example Response:
{
"results": [
{
"id": 16470,
"uuid": "95b1b1da-769e-4820-bc07-d2d500d75112",
"created": 1637642408.871543,
"edited": 1639135101.131713,
"text": "<Comment Text>",
"author": {
"name": "<First Name> <Last Name>",
"id": 557,
"uuid": "245fdc59-bfe9-464e-9763-44cd71f324ca"
},
"goal": {
"name": "<Goal Name>",
"id": 151,
"uuid": "05394ead-c667-43c0-84b2-29c3b97dedfb"
},
"goal_owner": {
"user": {
"name": "<First Name> <Last Name>",
"id": 14,
"uuid": "918f07df-9428-4b13-a0aa-b5f457777f99"
},
"group": {
"id": 639,
"uuid": "476a21bb-1f8e-4bcf-a276-8b128baa45fc",
"name": "<Group Name>",
"parent_id": 117,
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": true,
"is_team": false
},
"team": {
"id": 577,
"uuid": "9d4ed2a0-cf74-4cdc-92ea-2466d7e364ac",
"name": "<Team Name>",
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"created_on": "2021-11-10T21:28:29.610217Z",
"modified_on": "2021-26-10T21:19:18.391311Z"
},
},
"is_key_result": true
},
{
"id": 13076,
"uuid": "05a04285-23c0-4d18-a45a-2c7df64e8c92",
"created": 1601032583.618398,
"edited": 1639135101.131713,
"text": "<Comment Text>",
"author": {
"name": "<First Name> <Last Name>",
"id": 661,
"uuid": "245fdc59-bfe9-464e-9763-44cd71f324ca"
},
"goal": {
"name": "<Goal Name>",
"id": 227,
"uuid": "3bce3d2a-8068-49e6-b96a-9b8dce4394ee"
},
"goal_owner": {
"user": {
"name": "<First Name> <Last Name>",
"id": 14,
"uuid": "918f07df-9428-4b13-a0aa-b5f457777f99"
},
"group": {
"id": 218,
"uuid": "0ad10986-a96e-480d-868b-26604886e8d6",
"name": "<Group Name>",
"parent_id": 719,
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"is_team": false
},
"team": {
"id": 306,
"uuid": "6046f513-093c-41fe-a03b-417dd039ab50",
"name": "<Team Name>",
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"created_on": "2021-11-10T21:28:29.610217Z",
"modified_on": "2021-26-10T21:19:18.391311Z"
},
},
"is_key_result": true
}
],
"more": false,
}
Returns all comments associated with a specific goal.
HTTP Request
GET /api/v1/goals/:id/comments
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | The goal ID |
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| type | Optional | Enum | Selecting private will limit query to only private comments, starred will return only starred comments. |
| latest_time | Optional | Timestamp | Limits comments to only those that occurred before the given time. |
| size | Optional | Integer | Maximum number of results to return (maximum and default value is 10). |
Returns
List of comment objects for the specified goal
Assessments
Example Response:
[
{
"id": 5,
"uuid": "d0b8b3bb-927d-4b20-b9fc-a7bfcc4a1413",
"created": 1647371191.628856,
"edited": 1659135101.131713,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 117,
"uuid": "f2f248c2-b486-452d-b78b-178faba3127a"
},
"goal_id": 12345,
"comment": "<Comment Text>",
"score": 0.75
}
{
"id": 6,
"uuid": "ee175165-b5b9-49ee-b293-9c632bb7ee8e",
"created": 1647371191.628856,
"edited": 1659135101.131713,
"created_by": {
"name": "<First Name> <Last Name>",
"id": 117,
"uuid": "9986837a-513d-4ad5-b3f9-a1beea3783cb"
},
"goal_id": 12345,
"comment": "<Comment Text>",
"score": 1.0
}
]
Returns all assessments and score associated with a specific goal or milestone ID.
HTTP Request
GET /api/v1/goals/:id/assessments/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer or UUID | The goal ID |
Returns
List of assessment objects for the specified goal
Check In
Example cURL:
curl -X POST --header "Authorization: APIToken <Your API Token>" -H
"Content-Type: application/json" --data '{"value":18.6, "target":30}'
https://app.betterworks.com/api/v1/goals/12834/checkin/
Example Response:
{
"categories": [
{
"name": "<Category Name>",
"id": 3,
"uuid": "e190931c-22da-4cc8-bce0-026a9c914b34"
}
],
"children": [
{
"name": "<Goal Name>",
"id": 215,
"uuid": "0434ff99-9382-4684-b9ce-0e80ce4eb1f9"
}
],
"created": 1453420800.0,
"created_by": {
"id": 3,
"name": "<First Name> <Last Name>"
},
"description": "<Goal Description>",
"end": "2016-02-21",
"id": 29,
"integration": {
"type": "udemy",
"last_sync": 1665604002.151043,
"identifier": "3833e446-ee67-4bd3-a79c-af060401ad66",
},
"is_key_result": true,
"last_checkedin": 1453507200.0,
"last_checkedin_by": {
"id": 3,
"name": "<First Name> <Last Name>"
},
"measurement": {
"condition": "green",
"current": 4.0,
"done": false,
"expected": 10.0,
"initial": 0.0,
"is_binary": false,
"is_numeric": true,
"lower_limit": 8.0,
"lower_mid": 4.0,
"upper_limit": 10.0,
"upper_mid": 5.0,
"progress": 0.4,
"target": 10.0,
"type": "numeric",
"unit": "u",
"updated": 1453507200.0,
"updated_by": {
"id": 3,
"name": "<First Name> <Last Name>"
},
},
"name": "<Goal Name>",
"owner": {
"group": {
"id": 218,
"uuid": "5eb928a2-34f8-4d1f-8ef1-f8a7b600e774",
"name": "<Group Name>",
"parent_id": 719,
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"is_team": false
},
"team": {
"id": 577,
"uuid": "9d4ed2a0-cf74-4cdc-92ea-2466d7e364ac",
"name": "<Team Name>",
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": false,
"created_on": "2021-11-10T21:28:29.610217Z",
"modified_on": "2021-26-10T21:19:18.391311Z"
},
"user": {
"id": 3,
"name": "<First Name> <Last Name>"
}
},
"parent": {
"id": 28,
"name": "<Goal Name>"
},
"start": "2016-01-21",
"stats": {
"cheers": 5,
"comments": 1,
"last_assessed": 1470611529.151352,
"nudges": 1,
"views": 5
},
"updated": 1453507200.0,
"updated_by": {
"id": 3,
"name": "<First Name> <Last Name>"
},
"visibility": "public"
}
Conduct a Check In on a goal. Update the current or the target value of a milestone.
HTTP Request
POST /api/v1/goals/:id/checkin/
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| id | Required | The ID of the goal or milestone |
POST Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| done | Required | Boolean | New completion state for the binary milestone |
| or | |||
| value | Required | Float | New current progress on the metric milestone |
| target | Optional | Float | New target value for the milestone (metric milestone only) |
Returns
Returns the parent goal updated with the new information. Returns a 400 Error if no value or
done is provided, or if any parameter is not the proper type with an error message describing
the issue.
Integrations
In the Betterworks system, Integrations are associated with Key Results.
Details regarding any integration with a key result can be easily accessed through the integrations/:integration_id endpoint. The integration_id can be obtained via the integration object returned by the goals/:id/ endpoint response under the identifier field.
Integrations Supported
- Jira
We will be adding support for additional integration types.
Get a specific Integration detail
Example Response:
{
"type": "jira",
"items": [
{
"key": "12345",
"summary": "test description",
"status": "To Do",
"is_resolved": false,
"resolution_status": null,
"url": "https://dummyorganization.atlassian.net/browse/12345"
},
{
"key": "23456",
"summary": "test 2 description",
"status": "In Progress",
"is_resolved": true,
"resolution_status": null,
"url": "https://dummyorganization.atlassian.net/browse/23456"
},
]
}
This endpoint will retrieve the full details about a specific integration for a Key result.
HTTP Request
GET /api/v1/integrations/:id/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | UUID | The integration Identifier |
Returns
The type of integration and list of integrated items.
Hashtags
Get a list of hashtags used in Recognitions.
List Hashtags
Example Response:
{
"results": [
{
"name": "apple",
"id": 2,
"created_on": "2021-11-30T21:39:35.337214Z",
"modified_on": "2021-11-30T21:39:35.916945Z"
},
{
"name": "banana",
"id": 1,
"created_on": "2022-01-25T06:34:42.581663Z",
"modified_on": "2022-01-25T06:34:42.581733Z"
}
],
"more": true,
"nextUrl": "/api/v1/hashtags/?size=2&page=2"
}
Returns a list of hashtags ordered by hashtag name.
HTTP Request
GET /api/v1/hashtags/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| page | Optional | Integer | Page to fetch |
| size | Optional | Integer | Number of hashtags per page |
| delta_start | Optional | ISO Date | Filters hashtags modified on or after |
| delta_end | Optional | ISO Date | Filters hashtags modified on or before |
Returns
List of hashtag objects
Recognitions
In the Betterworks system, Recognition is a thoughtful acknowledgement of another person’s efforts, achievements, and performance. Recognitions can be filtered on hashtags, start and end dates, or user/group IDs.
List Recognitions
Example Response:
{
"results": [
{
"id": 1,
"uuid": "da266b72-0958-4497-94f1-dfc3353211ef",
"author": {
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "dd63efb9-3e2d-4ca8-96a7-8b8741cac679"
},
"for_user": {
"name": "<First Name> <Last Name>",
"id": 3,
"uuid": "209024d3-4cce-4b4f-bc84-f252548e505c"
},
"for_group": {
"id": 567,
"uuid": "d4c01b9c-5db3-46b3-a502-49b6e30c39e1",
"name": "<Group Name>"
},
"mentioned_users": [
{
"name": "<First Name> <Last Name>",
"id": 4,
"uuid": "209024d3-4cce-4b4f-bc84-f252548e505c"
}
],
"hashtags": [
{
"name": "<Hashtag Name>",
"id": 123
}
],
"source": {
"comment": {
"id": 16449,
"uuid": "9a906c67-81a7-45a0-b755-3815d96e68ac",
"created": 1637215829.973811,
"edited": 1556701767.922609,
"text": "<Comment Text>",
"author": {
"name": "<First Name> <Last Name>",
"id": 655,
"uuid": "0ce3ecc2-f135-44e3-8cec-cc03fd2d2eb0"
},
"goal": {
"name": "<Goal Name>",
"id": 7476,
"uuid": "7466a63f-6ac4-44dc-8504-fb4e124cadb1"
},
"goal_owner": {
"user": {
"name": "<First Name> <Last Name>",
"id": 308,
"uuid": "17d19537-639d-4ebe-b2b0-0efa93aec6cc"
},
"group": {
"id": 1526,
"uuid": "3beb1bab-1493-420a-b5be-e1d14a11352f",
"name": "<Group Name>",
"parent_id": 12661,
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": true,
"is_team": true
},
"team": {
"id": 103,
"uuid": "d4c01b9c-5db3-46b3-a502-49b6e30c39e1",
"name": "<Team Name>",
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": true
}
},
"is_key_result": true
},
"shoutout": {
"id": 1,
"uuid": "86d70b94-ef3e-459e-8aba-21287385f3c4",
"for_user_id": 3,
"for_user_name": "<First Name> <Last Name>",
"author_id": 2,
"author_name": "<First Name> <Last Name>",
"text": "<Shoutout Text>",
"created": 1647247458.122404,
"edited": 1647957458.625401,
}
},
"created": 1647247458.122404,
"created_on": "2021-02-28T05:20:48.265430Z",
"modified_on": "2021-02-28T05:20:48.265469Z"
}
],
"more": true,
"nextUrl": "/api/v1/recognitions/?size=1&page=2"
}
Returns a list of recognition details.
When filtering on for_user object the for_group is null:
{
"for_user": {
"id": 3,
"uuid": "e32cb269-c910-4152-a813-af60500b5ef4",
"name": "<First Name> <Last Name>"
}
}
When filtering on for_group object the for_user is null:
{
"for_group": {
"id": 1,
"uuid": "cc233f9c-d1fd-4d1f-a06e-6b294aee3f10",
"name": "<Group Name>",
"parent_id": 154,
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": true,
"is_team": false
}
}
HTTP Request
GET /api/v1/recognitions/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| start_date | Optional | Date | Starting Date as YYYY-MM-DD. If provided end_date required |
| end_date | Optional | Date | Ending Date as YYYY-MM-DD. If provided start_date required |
| for_user_id | Optional | Integer | Filter on ID of a user |
| for_group_id | Optional | Integer | Filter on ID of a group |
| hashtag | Optional | String | A hashtag used in a recognition |
| delta_start | Optional | ISO Date | Filters recognitions modified on or after |
| delta_end | Optional | ISO Date | Filters recognitions modified on or before |
Returns
List of recognition objects
Reports
In the Betterworks system, Reports allow you to view activity, goals, conversations, feedbacks, and recognitions.
List Report Runs
Example Request:
GET /api/v1/report_runs/?report=conversation_answer&template=1234&created=2021-4-2
Example Response:
{
"results": [
{
"id": 1000,
"report": "conversation_answer",
"created": 1617389428.763803,
"created_by": {
"name": "User One",
"id": 22
},
"status": "succeeded",
"parameters": {
"template": 1234,
"date_range": {
"start": "2021-01-01",
"end": "2021-01-31"
}
},
"finished": 1617389431.097175,
"error": null,
"result": {
"created": 1617389431.096469,
"expires_on": 1617475831.09387,
"filename": "ConversationAnswersExample.xlsx",
"type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"url": "<url>"
}
},
{
"id": 1001,
"report": "conversation_answer",
"created": 1617389428.763803,
"created_by": {
"name": "User One",
"id": 22
},
"status": "succeeded",
"parameters": {
"template": 1234,
"date_range": {
"start": "2021-01-01",
"end": "2021-01-31"
}
},
"finished": 1617389431.097175,
"error": null,
"result": {
"created": 1617389431.096469,
"expires_on": 1617475831.09387,
"filename": "ConversationAnswersExample.xlsx",
"type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"url": "<url>"
}
}
],
"more": false,
"nextUrl": null
}
Get a paginated list of ReportRun objects.
HTTP Request
GET /api/v1/report_runs/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| report | Optional | String | Filter by type of report. Available option: all_goals, all_goals_and_milestones, conversation_answers, conversation_adoption, feedback_answers, feedback_adoption, recognition, user_activity NOTE: the conversation answers and feedback answers report are only available to users with super admin or HR admin role |
| template | Optional (conversation/feedback report only) | Integer | Filter by conversation/feedback template ID of the report |
| created | Optional | Date | Filter by created date in YYYY-MM-DD format |
| page | Optional | Integer | Page number of report runs to return |
| size | Optional | Integer | Number of report runs per page, default 15 |
Returns
List of ReportRun object and pagination details.
Get Report Run
Example Request:
GET /api/v1/report_runs/1000/
Example Response:
{
"id": 1000,
"report": "conversation_answer",
"created": 1617389428.763803,
"created_by": {
"name": "User One",
"id": 22
},
"status": "succeeded",
"parameters": {
"template": 1234,
"date_range": {
"start": "2021-01-01",
"end": "2021-01-31"
}
},
"finished": 1617389431.097175,
"error": null,
"result": {
"created": 1617389431.096469,
"expires_on": 1617475831.09387,
"filename": "ConversationAnswersExample.xlsx",
"type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"url": "<url>"
}
}
Returns details of an existing ReportRun object.
HTTP Request
GET /api/v1/report_runs/:id/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer | ID of report run |
Returns
The specified ReportRun object.
Create Report Run
Example Request:
POST /api/v1/report_runs/
{
"report": "conversation_answers",
"parameters": {
"template": 1234,
"date_range": {
"start": "2021-01-01",
"end": "2021-01-31"
}
}
}
Example Response:
{
"id": 1000,
"report": "conversation_answers",
"created": 1617646407.07028,
"created_by": {
"name": "User One",
"id": 22
},
"status": "pending",
"parameters": {
"template": 1234,
"date_range": {
"start": "2021-01-01",
"end": "2021-01-31"
}
},
"finished": null,
"error": null,
"result": null
}
Creates a new ReportRun object and triggers running the report.
HTTP Request
POST /api/v1/report_runs/
Payload Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| report | Required | String | Type of report. Available option: all_goals, all_goals_and_milestones, conversation_answers, conversation_adoption, feedback_answers, feedback_adoption, recognition, user_activity NOTE: the conversation answers and feedback answers report are only available to users with super admin or HR admin role |
| template | Required (conversation and feedback report only) | Integer | Conversation/feedback template ID of the report |
| start | Required | Date | Report start date in YYYY-MM-DD format |
| end | Required | Date | Report end date in YYYY-MM-DD format |
Returns
A ReportRun object.
Teams
In the Betterworks system, teams can be any collection of users, and are typically made up of people from different departments working on the same project. Also referred to as ‘dotted line’ managers or a matrix structure where a person reports to two managers: one for daily tasks on a project, and another manager responsible for their performance and development.
List Teams
Example Response:
{
"results": [
{
"id": 123,
"uuid": "b44c61c8-f0c7-45f6-b569-65f12952089c",
"name": "<Team Name>",
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": true,
"created_on": "2021-11-10T21:28:29.610217Z",
"modified_on": "2021-11-10T21:28:29.610217Z",
"members": [
{
"name": "<First Name> <Last Name>",
"id": 1,
"uuid": "4a92af5c-fb73-44c1-a834-f7f6857701ec"
},
{
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "5b4386e9-18b4-44a2-8172-0e934b7a3f48"
}
]
},
{
"id": 456,
"uuid": "281f534b-d5ca-4f5f-8d75-2dfacd9b3886",
"name": "<Team Name>",
"picture_uris": {
"small": "<URL>",
"medium": "<URL>"
},
"is_active": true,
"created_on": "2021-11-15T06:25:34.695089Z",
"modified_on": "2022-03-07T20:37:49.572230Z",
"members": [
{
"name": "<First Name> <Last Name>",
"id": 3,
"uuid": "0ffdddc3-ed9b-4c26-90e9-d0d7d331bf79"
},
{
"name": "<First Name> <Last Name>",
"id": 4,
"uuid": "25884fc5-ceef-41c5-bf60-02f89a4b3cc2"
}
]
},
],
"more": true,
"nextUrl": "/api/v1/teams/?type=myteams&size=2&page=2"
}
Get list of teams
HTTP Request
GET /api/v1/teams/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| type | Optional | String | The team association. Accepts ‘myteams’ (default) or 'allteams’ |
| delta_start | Optional | ISO Date | Filters teams modified on or after |
| delta_end | Optional | ISO Date | Filters teams modified on or before |
Returns
List of team objects
Get Team
Example Response:
{
"id": 123,
"uuid": "659a21e1-4cb7-4ef8-a94e-7d63a56de3a3",
"name": "<Team Name>",
"picture_uris": {
"small": "<URI>",
"medium": "<URI>"
},
"is_active": true,
"created_on": "2021-11-10T21:28:29.610217Z",
"modified_on": "2021-11-10T21:28:29.610217Z",
"members": [
{
"name": "<First Name> <Last Name>",
"id": 1,
"uuid": "cb96dbdc-c996-40ab-9648-2cef1f508998"
},
{
"name": "<First Name> <Last Name>",
"id": 2,
"uuid": "e36707ce-6054-4da7-ba03-ccbd4706653d"
}
]
}
Get team details
HTTP Request
GET /api/v1/teams/:id/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Required | Integer | The ID of the team to retrieve |
Returns
Team object
Users
List Users
Example Response:
{
"results": [
{
"id": 123,
"uuid": "82316b97-7b41-439d-9024-8331272c568c",
"first_name": "<First Name>",
"preferred_name": "<Preferred Name>",
"last_name": "<Last Name>",
"name": "<First Name> <Last Name>",
"email": "<Email Address>",
"is_active": true,
"deactivated_on": null,
"deactivation_date": null,
"title": "<Title>",
"manager": {
"name": "<First Name> <Last Name>",
"id": 12346,
"uuid": "e8acd60c-6770-4606-950a-b031243f32d7"
},
"department": {
"name": "<Department Name>",
"id": 177,
"uuid": "e0870840-4c8e-4a1b-b067-e151b4f146eb"
},
"phone": "<Phone Number>",
"about": "<About Text>",
"locale": "en",
"is_goalmaster": false,
"is_super_admin": true,
"is_admin": false,
"is_group_admin": false,
"employee_id": "<Employee ID>",
"created_on": "2019-01-01T12:00:00.123456Z",
"modified_on": "2019-01-02T12:00:00.123456Z",
"attributes": {
"location": "San Francisco, California",
"on_leave": false
},
"custom_values": {
"custom_property": "<Custom Property Text>"
}
},
{
"id": 456,
"uuid": "5abf75bc-376b-4331-897a-f691622bdc59",
"first_name": "<First Name>",
"preferred_name": "<Preferred Name>",
"last_name": "<Last Name>",
"name": "<First Name> <Last Name>",
"email": "<Email Address>",
"is_active": true,
"deactivated_on": null,
"deactivation_date": null,
"title": "<Title>",
"manager": {
"name": "<First Name> <Last Name>",
"id": 12346,
"uuid": "e8acd60c-6770-4606-950a-b031243f32d7"
},
"department": {
"name": "<Department Name>",
"id": 177,
"uuid": "e0870840-4c8e-4a1b-b067-e151b4f146eb"
},
"phone": "<Phone Number>",
"about": "<About Text>",
"locale": "en",
"is_goalmaster": false,
"is_super_admin": true,
"is_admin": false,
"is_group_admin": false,
"employee_id": "<Employee ID>",
"created_on": "2019-01-01T12:00:00.123456Z",
"modified_on": "2019-01-02T12:00:00.123456Z",
"attributes": {
"location": "San Francisco, California",
"on_leave": false
},
"custom_values": {
"custom_property": "<Custom Property Text>"
}
},
],
"more": true,
"nextUrl": "/api/v1/users/?size=2&page=2"
}
HTTP Requests
GET /api/v1/users/- All users with defaults (page=1, size=10)
GET /api/v1/users/?page=1&size=5- First page containing up to five items in results
GET /api/v1/users/?page=10- Tenth page with default size=10
GET /api/v1/users/?department=HR- Get all users belonging to the
HRdepartment
- Get all users belonging to the
GET /api/v1/users/?locale=it- Get users whose locale is set to
it
- Get users whose locale is set to
GET /api/v1/users/?employee_id=ABC123- Get users whose employee_id matches
ABC123
- Get users whose employee_id matches
GET /api/v1/users/?manager=123- Get users whose manager has the ID
123
- Get users whose manager has the ID
GET /api/v1/users/?deactivated=1- Get all deactivated users
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| page | Optional | Integer | Page of users to get from the API (default=1) |
| size | Optional | Integer | Size of pages to get from the API (default=10, maximum=20, minimum=1) |
| department | Optional | String | Name of the department to filter users by (default=null) |
| employee_id | Optional | String | The employee_id to filter users by (default=null) |
| manager | Optional | Integer or UUID | The id of the manager to filter users by (default=null) |
| deactivated | Optional | Integer | 0 for active users, 1 for deactivated users(default=null) |
| delta_start | Optional | ISO Date | Filters users modified on or after |
| delta_end | Optional | ISO Date | Filters users modified on or before |
| locale | Optional | String | Locale. Available options: cs, de, es, es_AR, en, en_GB, pt_BR, zh_Hans, zh_Hant, pl_PL, fr_FR,fr_CA, it, ja, nl, tr, hi, hr, hu, ko, ro, ru, sk, sv, th, vi |
Get User
Example Response:
{
"id": 123,
"uuid": "82316b97-7b41-439d-9024-8331272c568c",
"first_name": "<First Name>",
"preferred_name": "<Preferred Name>",
"last_name": "<Last Name>",
"name": "<First Name> <Last Name>",
"email": "<Email Address>",
"is_active": true,
"deactivated_on": null,
"deactivation_date": null,
"title": "<Title>",
"manager": {
"name": "<First Name> <Last Name>",
"id": 12346,
"uuid": "e8acd60c-6770-4606-950a-b031243f32d7"
},
"department": {
"name": "<Department Name>",
"id": 177,
"uuid": "e0870840-4c8e-4a1b-b067-e151b4f146eb"
},
"phone": "<Phone Number>",
"about": "<About Text>",
"locale": "en",
"is_goalmaster": false,
"is_super_admin": true,
"is_admin": false,
"is_group_admin": false,
"employee_id": "<Employee ID>",
"created_on": "2019-01-01T12:00:00.123456Z",
"modified_on": "2019-01-02T12:00:00.123456Z",
"attributes": {
"location": "San Francisco, California",
"on_leave": false
},
"custom_values": {
"custom_property": "<Custom Property Text>"
}
}
Returns details for a specific user using user ID or UUID.
HTTP Request
GET /api/v1/users/:identifier/
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| identifier | Required | Integer or UUID | The identifier of the user |
Returns
User object
Search
Example Response:
{
"results": [
{
"id": 123,
"uuid": "82316b97-7b41-439d-9024-8331272c568c",
"first_name": "<First Name>",
"preferred_name": "<Preferred Name>",
"last_name": "<Last Name>",
"name": "<First Name> <Last Name>",
"email": "<Email Address>",
"is_active": true,
"deactivated_on": null,
"deactivation_date": null,
"title": "<Title>",
"manager": {
"name": "<First Name> <Last Name>",
"id": 12346,
"uuid": "e8acd60c-6770-4606-950a-b031243f32d7"
},
"department": {
"name": "<Department Name>",
"id": 177,
"uuid": "e0870840-4c8e-4a1b-b067-e151b4f146eb"
},
"phone": "<Phone Number>",
"about": "<About Text>",
"locale": "en",
"is_goalmaster": false,
"is_super_admin": true,
"is_admin": false,
"is_group_admin": false,
"employee_id": "<Employee ID>",
"created_on": "2019-01-01T12:00:00.123456Z",
"modified_on": "2019-01-02T12:00:00.123456Z",
"attributes": {
"location": "San Francisco, California",
"on_leave": false
},
"custom_values": {
"custom_property": "<Custom Property Text>"
}
}
],
"more": false,
"nextUrl": null
}
Returns all users matching the search criteria. Matches on full name and username.
HTTP Request
GET /api/v1/users/search/
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| q | Required | String | Text string (minimum length of 3) to be compared against user’s First, Last, and Email name. |
| manager_id | Optional | Integer or UUID | Only search for users who report to this manager (includes him or herself) |
| can_view_goal_id | Optional | Integer | Append ‘can_view’ to each user in the response if that user has permission to view the specified goal. |
| deactivated | Optional | Boolean | Only search for deactivated users. |
Returns
Returns a users dictionary that contains an empty objects list if no users were found, or an
objects list of up to size users and the boolean flag more if these results are not the end
of the list.
Update Users
Example Request:
{
"dry_run": true,
"users": [
{
"email": "<Email Address>",
"first_name": "<First Name>",
"last_name": "<Last Name>",
"employee_id": "u1_1234",
"department_name": "Engineering",
"title": "Software Engineer",
"manager_id": "u0_0987",
"location": "San Francisco",
"preferred_name": "<Preferred Name>",
"matrix_manager": "<Email Address>",
"phone": "1234567890",
"custom_01": "extra data"
}
]
}
Example Response:
{
"deactivated_count": 0,
"reactivated_count": 0,
"updated_count": 0,
"dry_run": true,
"errors": [
{
"error_details": [
{"description": "betterworks.com is an invalid domain"}
],
"index": 0,
"processed": false
}
]
}
Update and create multiple users.
HTTP Request
POST /api/v1/users/bulk/
Payload Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| users | Required | List of User |
Users to be updated. |
| dry_run | Optional | Boolean | Whether to perform a dry run. If dry run is true, no changes are made. |
User
| Parameter | Required | Type | Description |
|---|---|---|---|
| Required | String | Email - Domains are pre-approved by BetterWorks. Contact support@betterworks.com to add more domains. | |
| first_name | Required | String | First Name |
| last_name | Required | String | Last Name |
| employee_id | Optional | String | Employee ID - Strongly recommended. This field supports re-use of email address and prevents re-activation of old accounts. |
| department_name | Optional | String | Department name |
| title | Optional | String | User’s job title |
| manager_id | Optional | String | Employee ID of user’s manager - Must match an existing employee_id. |
| manager_email | Optional | String | Email of user’s manager - Strongly recommended. Must match an existing email. |
| is_active | Optional | Boolean | Activated/deactivated status of user |
| phone | Optional | String | Phone number |
| location | Optional | String | Location |
| preferred_name | Optional | String | Nickname |
| on_leave | Optional | Boolean | Is user out of office - will only appear in admin panel for reporting purposes. |
| matrix_manager | Optional | String | Email of a manager that may not be their direct report in BetterWorks - will only appear in admin panel for reporting purposes. |
| locale | Optional | String | Locale. Available options: cs, de, es, es_AR, en, en_GB, pt_BR, zh_Hans, zh_Hant, pl_PL, fr_FR,fr_CA, it, ja, nl, tr, hi, hr, hu, ko, ro, ru, sk, sv, th, vi |
| custom_01 | Optional | String | |
| custom_02 | Optional | String | |
| custom_03 | Optional | String | |
| custom_04 | Optional | String | |
| custom_05 | Optional | String |
Returns
A count of user changes, list of errors.
Clear Values with BW_NULL
A handful of user fields can be cleared by passing BW_NULL as the value. Special rules apply to these fields to ensure that affected user’s data does not end up in an unsupported state.
first_name,last_name, andemailcan never beBW_NULLpreferred_namecan beBW_NULLbut the user will fall back tofirst_namewhenpreferred_nameis absentmanager_idormanager_emailcan beBW_NULLand will cause both values to be cleared out and removed from the pending user (matches preexisting logic for passing empty string for both of these fields)employee_idcan beBW_NULLon create but NOT on update (matches preexisting logic for empty string handling)localecan beBW_NULLand will clear the record entry but the user will fall back to the org locale if the user locale is empty (matches preexisting logic for empty string handling)If
BW_NULLis provided foris_activethen the field value will default toTrueIf
BW_NULLis provided forterminatedthenterminatedwill default toFalse, resulting inis_activedefaulting toTrueIf
BW_NULLis provided fordeactivation_datethendeactivation_datewill returnTrue, resulting inis_activebeingTrue
Assign Roles
Example Request:
{
"roles": [
{
"role": "admin",
"user_id": 9
},
{
"employee_id": "e1234",
"role": "superadmin"
},
{
"email": "<Email Address>",
"role": "none"
},
{
"role": "superadmin",
"user_id": 12
},
{
"departments": [
5,
6
],
"role": "groupadmin",
"user_id": 13
}
{
"admin_groups": [7],
"role": "groupadmin",
"user_id": 14
}
]
}
Example Response:
{
"results": [
{
"admin_since": null,
"id": 5,
"managed_departments": [],
"name": "<First Name> <Last Name>",
"role": "superadmin"
},
{
"admin_since": 1453420800.0,
"id": 10,
"managed_departments": [],
"name": "<First Name> <Last Name>",
"role": "superadmin"
},
{
"admin_since": 1453420800.0,
"id": 12,
"managed_departments": [],
"name": "<First Name> <Last Name>",
"role": "superadmin"
},
{
"admin_since": 1453420800.0,
"id": 9,
"managed_departments": [],
"name": "<First Name> <Last Name>",
"role": "admin"
},
{
"admin_since": 1453420800.0,
"id": 13,
"managed_departments": [
{
"id": 5,
"name": "A"
},
{
"id": 6,
"name": "B"
}
],
"name": "<First Name> <Last Name>",
"role": "groupadmin"
},
{
"admin_since": 1453420800.0,
"id": 14,
"managed_admin_groups": [
{
"id": 7,
"name": "A"
}
],
"name": "<First Name> <Last Name>",
"role": "groupadmin"
}
]
}
Update roles. For details regarding how these roles function within BetterWorks, please read this article.
HTTP Request
PUT /api/v1/users/roles/
Payload Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| roles | Required | List of RoleAssignment |
Roles to be assigned. |
RoleAssignment
| Parameter | Required | Type | Description |
|---|---|---|---|
| [identifier] | Required | Unique identifier associated with the user (see below) | |
| role | Required | String | Role to assign to user. |
| departments | Optional | List of department ids | This or the admin_groups field are required when assigning groupadmin. List of departments over which an HR Admin has scope over. Note: When including a department, all children (and grand children, and on) of that department are implicitly included in the HR Admin’s scope. |
| admin_groups | Optional | List of admin group ids | This or the departments field are required when assigning groupadmin. List of admin groups over which an HR Admin as scope over. Note: When including an admin group, all children (and grand children, and on) of that group are implicitly included in the HR Admin’s scope. |
Identifier
Each RoleAssignment must have one (and only) one identifier:
| Parameter | Type | Description |
|---|---|---|
| user_id | Integer | BetterWorks user ID |
| String | BetterWorks user email | |
| employee_id | String | User’s employee ID |
Role
Each RoleAssignment must specify a role:
| Role | Description |
|---|---|
| none | This role has no special privileges. |
| groupadmin | This role gives HR Admin access over a given set of department and/or admin_group. Note: RoleAssignment must include departments and/or admin_groups. |
| admin | This role grants Admin access to the organization. |
| superadmin | This role grants Super Admin access to the organization. |
Returns
The list of updated users and their new assignments. Users that had their admin roles removed will not be included in the response.
List Users With Admin Roles
Example Response:
{
"results": [
{
"id": 1,
"uuid": "2841e4d3-3d30-467e-b3c1-3b8272303c8a",
"role": "admin",
"admin_since": 1453420800.0,
"managed_departments": [
{
"name": "<Department Name>",
"id": 17,
"uuid": "093d1993-ffd3-40fa-9fc9-0df6ad71aa82"
},
{
"name": "<Department Name>",
"id": 20,
"uuid": "78bd36d4-c5b4-43e9-9d7e-af08becb48d8"
},
],
"managed_admin_groups": [
{
"name": "<Group Name>",
"id": 333,
"uuid": "f07dea65-1fbe-4579-997f-42aecf7224da"
}
],
"name": "<First Name> <Last Name>",
},
{
"id": 2,
"uuid": "7116ecdb-79a5-4de1-bf08-bebafd191315",
"role": "superadmin",
"admin_since": 1642403601.0,
"managed_departments": [
{
"name": "<Department Name>",
"id": 115,
"uuid": "dede516c-383d-4582-b7cd-aab35c3bcc9a"
}
],
"managed_admin_groups": [
{
"name": "<Group Name>",
"id": 181,
"uuid": "507db6a6-3f37-4aa4-8abe-31e8176f8b7a"
}
],
"name": "<First Name> <Last Name>",
}
]
}
Returns list of all users with Admin, Super Admin, or HR Admin privileges.
HTTP Request
GET /api/v1/users/roles/
Returns
The list of all users with Admin, Super Admin, or HR Admin privileges.