1. Betterworks
  2. Betterworks
  3. Admin

Platform Configuration: API

Contents

What Does It Do?

Note: Outbound SFTP is an alternative option to our API. For more information, see the Outbound SFTP Overview Support article and contact your Program Architect, your Customer Success Manager, or your Support Account Manager.

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. 

Note: We recommend generating and sending a unique X-Request-Id header value for each public API call. In the event of an error, this will make future troubleshooting easier because our team will be able to search for the unique value.

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 Smith 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 Smith 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 John 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.

Retrieving User Data with a GET Request

Bulk Uploading User Goals to Betterworks with a POST Request

 

Additional Resources

Troubleshooting

We recommend generating and sending a unique X-Request-Id header with each API call. This practice facilitates easier troubleshooting.

You can include your own X-Request-Id header value when making API calls. The value should ideally be unique for every call (i.e. a UUID or a sequential number).

  • If you provide an X-Request-Id, the API will return it in the response.
  • If you do not provide one, the API will assign and return its own X-Request-Id.

The X-Request-Id value can be included in Support requests (support@betterworks.com) to streamline troubleshooting.

FAQs

Why can't I see all the responses when using the API?

Our APIs use pagination. This means responses are spread across multiple pages. You must add specific parameters to the URL to access the next page. For example, please see below:


Note: size=100 is the max limit 

Why isn't the 'deployment_id' working for 'Get a list of conversations'?

You first need to run 'GET a list of conversations templates' and obtain the deployment_id from the deployment array. Then, you must add this deployment_id as a parameter/param before running the request. This can be done by going to the 'Params' tab and adding a value for deployment_id.