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:
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, 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 displayed 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: