NAV
Developer Documentation
Output

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.

In the example below the API will return all users modified on or before January 1st 2019.

In the example below the API will return all users modified between January 1st 2019 and January 31st 2019.

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

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": "JIRA",
  "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": "Google Sheets",
      "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": "Udemy",
  "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.

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

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

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
email 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.

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
email 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.