Follow

How do I use the Checklick API?

If your organization wants to integrate its own systems with Checklick, you can use Checklick's API. The API is available to all organizations.

Quick Start

To jump right in and send a test request to Checklick:

  1. Log in to Checklick as a manager of your organization
  2. Click the user context menu (top right)
  3. Click your name
  4. Find the section API Secret Key and click generate new key
  5. You should now see a text box with a sample cURL command. Copy and paste this into your terminal and hit enter.
  6. You should get a JSON response with a list of all people in your organization.

About the API

Checklick's API is a RESTful based API that returns data as JSON. The API adheres to the JSON-API specification, which is a documented standard for the structure of API requests and responses.

Each manager in Checklick is able to generate their own secret API key (independent of their username and password), which they can use to access data within Checklick via the API.

The scope of an API user’s data access will be the same as their scope of access in the web app. An API user will only be able to view and edit data from people within organizations they manage, and organizations they may view because of checklist licences.

API Endpoints

The API uses stateless, resource-based URIs. The following endpoints are available from https://api.checklick.com as of the latest API version (version 2):

URI HTTP Verb Description
/users GET Retrieve all people visible to this organization
/users POST Create one new person
/users/1 GET Retrieve one person
/users/1 PATCH Update one person
/users/1/assessments GET Retrieve all assessments (skill records) for one person
/users/1/assessments/1 GET Retrieve a specific assessment record for one person
/users/1/credentials GET Retrieve all credential records (achieved levels) for one person
/users/1/credentials/1 GET Retrieve a specific credential record for one person
/users/1/tag-applications GET Retrieve all tag applications (general tags) for one person
/users/1/tag-applications/1 GET  Retrieve a specific tag application for one person
/users/1/tag-applications POST Apply an existing tag to a person
/users/1/tag-applications/1 DELETE Remove an existing tag from a person
/tags GET Retrieve all existing tags (created by your organization) 
/tags POST Create one new tag
/tags/1 GET Retrieve one existing tag
/tags/1 PATCH  Update one existing tag
/tags/1 DELETE Delete one existing tag
/tags/1/tag-applications GET Reveal all tag applications (general tags) of one tag.
/tags/1/tag-applications PUT Apply an existing tag to a person
/tags/1/tag-applications/1 GET Retrieve a specific tag application for one person
/tags/1/tag-applications/1 DELETE Remove an existing tag from a person 
/checklists GET Retrieve all checklists available to this organization
/checklists/1 GET Retrieve a specific checklist
/levels GET Retrieve all levels available to this organization
/levels/1 GET  Retrieve a specific level
/levels/1/credentials GET  Retrieve all credentials (achieved levels) for this level and awarded to people visible to this organization
/levels/1/credentials/1 GET  Retrieve a specific credential
/sections GET  Retrieve all sections available to this organization
/sections/1 GET  Retrieve a specific section
/skills GET  Retrieve all skills available to this specific organization
/skills/1 GET  Retrieve a specific skill
/skills/1/assessments GET  Retrieve all assessments (skill records levels) for this skill and recorded for people visible to this organization
/skills/1/assessments/1 GET  Retrieve a specific assessment


Connection Requirements

API Subdomain

All requests must be sent to api.checklick.com. Any API requests sent to app.checklick.com, www.checklick.com or any other Checklick subdomain will be refused.

HTTPS

Requests sent over HTTP will be refused. All requests must be send using HTTPS. 

Content-Type Header

All requests must include the JSON API vendor-specific media type header. For example:

Content-Type:application/vnd.api+json

API Version Header

The Checklick API is versioned, meaning future updates to the API won't necessarily break your current API implementation. The current API version is 2. All requests should include a version number as a header. For example:

Api-Version:2

Secret Key

Checklick uses secret keys to authenticate each request (instead of username and password). Every manager of an organization can create a unique secret key. Here's how to generate your key:

  1. Log in to Checklick as a manager of your organization
  2. Click the user context menu (top right)
  3. Click your name
  4. Find the section API Secret Key and click generate new key

All requests must include a valid secret key. For example:

Authorization:Token token=2c96ef73e5ad003362b1851cb7c607f3

Organization ID

Many Checklick organization managers manage more than one organization. As an additional method of authentication, all requests must include a header that specifies an organization ID that is from an organization managed by the user who's secret key was passed. For example:

Organization-Id:999

The organization ID will be used as the "context" for the request, meaning that the data that you received will be limited the same data you can access when you are managing that specific organization.

Putting It All Together

If you are using cURL, your request might look something like this:

curl -X GET \
https://api.checklick.com/users \
-H 'Api-Version: 2' \
-H 'Authorization: Token token=2c96ef73e5ad003362b1851cb7c607f3' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Organization-Id: 999'

This is a dummy request with fake headers. For a request with your own real headers, you can copy-and-paste the sample cURL command that is shown just beneath your API key in Checklick.

Pagination, Searching and Filtering

Pagination

Results with more than 10 items will automatically be paginated. You'll see links at the bottom of your results to the first, next and last pages. For example:

"links": {
"first": "https://api.checklick.com/users?page%5Bnumber%5D=1&page%5Bsize%5D=10",
"last": "https://api.checklick.com/users?page%5Bnumber%5D=1&page%5Bsize%5D=10"

Searching or Filtering

When accessing endpoints that return multiple items, you can include a filter parameter to limit the numbers of items shown to you. These parameters should be included in your request as query parameters.

Most attributes can be used as parameters. For example, to filter all of your people by a specific last name, try:

https://api.checklick.com/users?filter[last_name]=Smith

Comments