Curl and the betterworks API

Contents

• What is curl?
• Authentication
• URI Structure and Versioning
• How to get a goal ID
• Sample GET Requests
• Sample POST Requests
• Sample PUT Requests
• See Using the betterworks API For More Detailed Information

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.  Here's an example:

curl --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" https://app.betterworks.com/api/v1/users/:identifier/

URI Structure and Versioning

All BetterWorks APIs require specifying an API version in the request URL.

Ex. 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/).

How to get a goal ID

An easy way to get the goal ID is to go to "Additional Actions" in the Actions column > Bulk Edit.  Then you can get the goal id from the URL shown below.

Sample GET Requests

Get a specific goal (GET /api/v1/goals/:id/) - ID is required

curl -X GET --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" -H "Content-Type: application/json" https://app.betterworks.com/api/v1/goals/5537351/

Get User

curl -X GET --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" -H "Content-Type: application/json" https://app.betterworks.com/api/v1/users/fictional@betterworks.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": "super department"}'

Sample PUT Request

Assign Roles

curl -X PUT --header "Authorization: APIToken 33ee80167fad49739a71ccf8a0e5679e" https://app.betterworks.com/api/v1/users/roles/ --data '{ "roles": [ { "email": "fictional@betterworks.com", "role": "admin"}, {"email": "fictionalemployee_1@betterworks.com", "role": "admin"} ] }'

See Using the betterworks API For More Detailed Information

More detailed information about api keys can be found by visiting Using the betterworks API. Further documentation and technical details for the API can be found at developers.betterworks.com.