Contents
- What is cURL?
- Authentication
- Structure & Versioning
- Retrieving An Objective (Goal) ID
- Sample GET Requests
- Sample POST Request
- Sample PUT Request
- Additional Resources
What Is cURL?
cURL is a command-line tool that supports just about any protocol there is and allows HTTP requests from the shell.
Authentication
With the shell, you can pass the correct header with each request:
curl --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" https://app.betterworks.com/api/v1/users/:identifier/
Structure & Versioning
All Betterworks APIs require specifying an API version in the request URL:
i.e. GET https://app.betterworks.com/api//user/ or GET https://preview.betterworks.com/api//user/ if developing against the preview environment.
The most current API version is V1 (GET https://app.betterworks.com/api/v1/user/).
Retrieving An Objective (Goal) ID
An easy way to retrieve an objective (goal) ID is to go to "Additional Actions" in the Actions column → Bulk Edit. The ID will be in the URL:
Sample GET Requests
Get a specific goal (GET /api/v1/goals/:id/)
curl -X GET --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" -H "Content-Type: application/json" https://app.betterworks.com/api/v1/goals/12084804/
Get user
curl -X GET --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" -H "Content-Type: application/json" https://app.betterworks.com/api/v1/users/jane.doe@acmecorp.com/
Filter on owner
curl -X GET --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" -H "Content-Type: application/json" https://app.betterworks.com/api/v1/goals/filter/?owner=148665
Sample POST Request
Create department
curl -X POST --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" https://app.betterworks.com/api/v1/departments/ --data '{"name": "finance department"}'
Sample PUT Request
Assign roles
curl -X PUT --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" https://app.betterworks.com/api/v1/users/roles/ --data '{ "roles": [ { "email": "jane.doe@acmecorp.com", "role": "admin"}, {"email": "john.doe@acmecorp.com", "role": "admin"} ] }'