To follow this guide, you need a demo account. Make sure it's fully set up according to our instructions on how to request a demo account.

Send a request

‌To communicate with our API, you'll need to build HTTP requests. You can use the programming language of your choice to achieve this. We provide examples of scripts using Python, but most of the content you'll work with will be in JSON.‌

Get your API access token

‌To gain access to our API, you will need your Client ID and Client Secret. Instructions for getting these values can be found in Use the API. You should take special precautions to keep your client secret a secret. In the example below (using our demo environment https://demo-api.certn.co), we show you how you can use secrets stored in a .env file.

First, make a request to get your access token. This token will be required to make all other API requests. For this step, make a GET request to our /token/ endpoint. If you're new to HTTP requests, visit W3Schools for useful guides.

import requests
from dotenv import dotenv_values


# An example of how to manage your Client ID and Client Secret, using a .env file
secrets = dotenv_values(".env")

client_id = secrets["CLIENT_ID"]
client_secret = secrets["CLIENT_SECRET"]

# add the 
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}
body = {"grant_type": "client_credentials"}

# url to retrieve your access token
url = "https://demo-api.certn.co/token/"

# Send the HTTP request to the API via POST, 
# including your Client ID and Client Secret for authentication
response = requests.post(
    url, 
    headers=headers, 
    auth=(client_id, client_secret), 
    data=body
)

# retrieve the access token
access_token = response.data.get("access_token")

With everything set properly and a good internet connection, you should receive a response.status_code of 200 OK. The response.data object should look something like:

You'll need this access_token as a bearer token in headers for all requests to our API. Let's see how to use this to Understand your general resources.

Errors

Please see Get and use an Authorization Token and Error codes for more details on types of errors, and how to resolve them.

Contact the Certn Partnerships Team

To request a demo account, email Certn's Partnership Team at partnerships@certn.co. They will arrange a call to learn about your organization's specific requirements and to help you set up your demo account.

Once created, you will be invited into your demo account via email, and prompted to create a password.

Set up your account for API tests

Set up your account on our dashboard to start testing our API.

2. Enter your email and password

3. Click Log in

5. Click Settings

6. Locate the team you want to use for testing

7. Click Settings for this team

Add a payment card

Adding a payment card to your account allows you to test a greater variety of features. Since this is a demo environment, you can use the card information provided below.

From your team's Settings page:

1. Click Billing

2. Click Connect Payment Card

3. Fill in the following card number: 4242 4242 4242 4242

4. Add an expiry date in the future

5. Fill in the following CVC: 424

6. Click Authorize Card

Create an API key

1. Navigate back to the dashboard by clicking the Certn logo in the top left

2. Click on the Partner tab

3. Click Refresh Keys

4. Click OK to accept that a new key will be created, inactivating the previously generated key

5. Click Copy

6. A new Client ID and Secret Key will appear in a modal for copy/pasting

   1. Once this modal is closed, the Secret Key will not be accessible anymore

You can now start testing the API with your demo account.

Get production access

When you’re ready to use the API in production, send us an email at apisupport@certn.co.

You'll need to know how to Get your access token before you can follow the instructions in this section.

Organizational structure

When you're set up within Certn, you belong to an organization. This organization has a few levels of hierarchy:

• Superteams

  • Teams

    • Users

Superteams can have multiple Teams and Teams can have multiple Users. When you're added to Certn, you're linked to a Team, which is linked to a Superteam.

Authorization header

You'll need an Authorization header with a valid Bearer token. This token is your access token you retrieved according to Get your access token.

• Replace access_token with your API access token:

{ "Authorization": "Bearer {access_token}" }

Retrieve your Users

In the beginning, you'll be the only User in your organizational account. Let's retrieve your users by making a GET request to our /users/ endpoint.

import requests

# Use your access token in the header.
headers = { "Authorization": f"Bearer {access_token}" }

# URL to retrieve a list of your users
url = "https://demo-api.certn.co/api/v1/users/"

# Send the HTTP request to the API via GET
response = requests.get(url, headers=headers)

############### Optional ###############

# Brings errors to the forefront
response.raise_for_status()

# Writes the contents of the response in a file named "user_list.json"
with open("user_list.json", "w") as f:
    f.write(response.text)

############# End Optional #############

In this example, we saved the results of the call to a new file named user_list.json.‌

With everything set properly and a good internet connection, you should receive a response status of 200 OK.

For more details on the structure of the User list response, see #retrieve-a-list-of-users.

Errors

‌Errors are a relatively common occurrence when working with APIs. It's always good to know how to prevent them and what to do when they arise.‌

See Error Codes for details on types of errors and how to resolve them.

You'll need to know to follow the instructions in this page.

Get the URL

‌You can find the URLs for all our endpoints in the section of this documentation. Knowing how to use them can be helpful, so we'll show you how they're created.‌

In this example, you'll be making calls to our demo environment, https://demo-api.certn.co.‌

We currently divide our endpoints for application management by permissible purpose:‌

• Human Resources endpoints start with /api/v1/hr/

• Property Management endpoints start with /api/v1/pm/

Later on, you'll request a , which is under /applications. You'll also make it a , so you'll be filling all of the information yourself instead of sending it to your applicant. To make it a quickscreen, add /quick to your URL.‌

Put this together and you get the URL for your call.

• Choose the URL that corresponds to your industry to continue:

Format the request body

1. To request a Softcheck, add the request-flag 'request_softcheck': true to your request body.‌

2. For your applicant, use our CEO's name, Andrew McLeod.

3. For the applicant's address, use our office location in Victoria, BC.

   1. 1006 Fort St, Victoria, BC V8V 3K4, Canada

4. For the owner_id, use the id of the User requesting the application. In this situation, it's you. See , to find out how to retrieve your User id.

5. For position_or_property_location, use the location of the position (Human Resources industry) or property (Property Management industry) for which you are running the check. In the example, we're hiring for a position (HR industry) that will be located in Blanshard St, Victoria. See for more information on this field.

Send the request

‌Now we're ready to bring it all together. Our /applications endpoint accepts POST requests, so make sure that is what you use.

Here is what your full script may look like when using Python:

In the previous example, we saved the results of the call to a new file named softcheck_demo.json.‌

With everything set properly and a good internet connection, you should receive a response status of 201 Created.

Errors

You'll need to know how to before you can follow the instructions in this section.

Request

The results you got from the Softcheck quickscreen creation call indicate that we received your request and are actively working on it. You can see this by checking the report_status field, which will likely be ANALYZING. These results will not be updated in real-time. To retrieve the updated versions, you can set up a , or send requests to one of our endpoints.

Choose your endpoint

In this guide, we'll show you how to send requests to our API to retrieve the status of your application via our endpoints. When using this method, keep sending requests until the field report_status is marked as COMPLETE. Then, you can view your final report.

We'll use the /applicants endpoint, which allows you to retrieve the report as a JSON object.

Get your application ID

To tell the API which application to retrieve, you need to provide it with the right application ID. You'll find it in the response of the creation call, under id. We use , so it'll be formatted like this:123e4567-e89b-12d3-a456-426614174000

Set up your URL

Once you have your application ID, append it to /applicants URL.

1. Choose the URL that corresponds to your industry

2. In the URL, replace {application_id} with your application's ID

Send the request

Now we're ready to bring it all together. Our /applicants endpoint accepts GET requests, so make sure that is what you use.

Here is what your full script may look like when using Python:

In the previous example, we saved the results of the call to a new file named results_softcheck_demo.json.‌

With everything set properly and a good internet connection, you should receive a response status of 200 OK.

Errors