1. Betterworks
  2. How-to
  3. Integrations

API Integration

Contents

What Does It Do?

The Betterworks REST API allows applications to access and send Betterworks data using GET and POST calls. GET refers to accessing data from Betterworks; viewing a record. POST refers to sending data to Betterworks; updating a record.

  • GET & POST:
    • User Data: Employee ID, title, department, manager, etc. 
    • Goal Data: Goal and milestone history including assessments (if applicable) and comments.
  • GET Only:
    • Conversation Data: Templates and individual conversations, including responses. 
    • Feedback Data: Templates and individual feedback, including responses.
    • Recognition Data: Users who received recognition, provided recognition, hashtags used, etc.
    • Calibration Data: Cycles and talent records. 

API Key Access

Any application can use the Betterworks API as long as every call contains an active API key. API keys are tied to users in Betterworks. As such, the data returned is based on the permissions of the key holder. Super Admins have complete access while users in other roles (i.e. HR Admin, Admin, and non-Admin user) have significantly less. This means that if a user is unable to access certain information in the Betterworks user interface, they won't be able to access it via the API. 

Example:

Jane Doe is a Super Admin and uses her key to submit a GET call for a list of departments in the organization. That information is returned without issue. 

John Doe is a non-Admin user and uses his key to submit a GET call for a list of departments in the organization. He receives an error message informing him that he does not have permission to retrieve this data. This is because when David logs into Betterworks, he can't access the Admin module where the department list resides. In short, the API functionality is adhering to the permissions of his role. 

If you'd rather not link the API key to a real user's account (since it will no longer work if the user leaves the organization and their Betterworks account is deactivated), you can create a dummy account in Betterworks:

dummy_account_for_api.png

Note: The dummy account will need to be granted Super Admin access and you'll need to log in at least once to accept that Betterworks privacy notice. API calls initiated by users who haven't accepted the privacy notice will not go through. If your organization is using the Betterworks SSO integration, you can either add the dummy account to your IDP or use the email address of an existing service account in your IDP. 

Generating An API Key

To generate an API key, follow these steps:

  1. Navigate to Admin → Platform Configuration → Betterworks API
    Choose a user to associate with the API key.
  2. Click Generate Key
  3. The generated API key will appear under "Active Keys."

Note: The same user can have multiple API keys.

api_key.png

Revoking A Key

An API key can be revoked at any time by simply clicking the Revoke button next to the key. This will immediately revoke the key. However, previously revoked keys can also be reactivated by clicking the Reactivate button:

reactivate_api_key.png

Betterworks API Documentation

Just like a guidebook helps you understand a new device, our API documentation helps navigate through Betterworks APIs easily. It has all the important information you need to use Betterworks APIs in your organization.

To get started, check out the video below for an overview. It'll give you useful insights to understand this documentation better.  

API Requests Examples

Earlier in this article, we introduced different types of requests supported by Betterworks REST API—GET Only and POST. Now, let's look at some examples to understand how it works. Use these examples as references to adapt and implement them for your needs.

  1. Retrieving User Data with a GET Request:
  2. Bulk Uploading User Goals to Betterworks with a POST Request:

Additional Resources