Contents
What Does It Do?
The Betterworks REST API allows applications to access and send Betterworks data using GET and POST calls. GET means to access data from Betterworks; view a record. POST means to send data to Betterworks; update a record.
- GET & POST:
- User Data: Employee ID, title, department, manager, etc.
- OKR Data: Objective and key result history including assessments 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.
Additional Resources
Note: You can use any API client with Betterworks. However, if you happen to have Postman, loading the files referenced above will save a lot of time.
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.
For 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:
Note: The dummy account will need to be given Super Admin access and you'll have to log into the dummy account at least once in order to accept that Betterworks privacy notice. API calls initiated by users who haven't accepted the privacy notice will not go through. As such, if your organization is using SSO with Betterworks, you'll either want to add the dummy account to your IdP as well or use the email address of an existing service account in your IdP.
Generating An API Key
To generate an API key, go to:
Admin → Platform Configuration → Betterworks API
Then:
1. Select a user to assign to the API key
2. Click "Generate Key"
3. The API key will be generated and display under "Active Keys"
Note: The same user can have multiple API keys.
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 next to the key:
