Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This version of our API documentation is intended for our clients with Partner Accounts. This version provides information about some additional functionality that is unavailable for non-partner accounts. For non-partner clients we recommend using our Certn API v 1.0 documentation. You can select the Certn API v 1.0 documentation using the dropdown (top left) or navigate to Certn API v 1.0.
Version 1.1.2 Last update: Jan. 23, 2024
In this site you will find everything you need to interact with Certn's API. These docs are for Certn clients who need to use our services in ways other than the Certn App, for example, to integrate with Applicant Tracking Systems or other proprietary software. Get started with a demo account to try out the API. To learn more about Certn and the background checks we offer, head over to certn.co!
For help articles and general knowledge, head over to help.certn.co.
Don't worry, we've got you covered! You can browse our handy guides to walk through most of our features, or better yet, start at the beginning!
You can find all our endpoints, along with code samples, in the API Reference section. We divide them by industry:
We have guides to help you with account management:
Did you encounter an error? Or perhaps you're looking for the FAQ? No matter what your question is, these docs should have your answer.
You can also try our search function!
The API may differ between accounts due to integration and legacy considerations.
Find the latest changes to this documentation in our API documentation changelogs.
How to sign up for a demo account.
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 on our dashboard to start testing our API.
Enter your email and password
Click Log in
Click Settings
Locate the team you want to use for testing
Click Settings for this team
You can manage your account settings and billing info from here.
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:
Click Billing
Click Connect Payment Card
Fill in the following card number: 4242 4242 4242 4242
Add an expiry date in the future
Fill in the following CVC: 424
Click Authorize Card
Navigate back to the dashboard by clicking the Certn logo in the top left
Click on the Partner tab
Click Refresh Keys
Click OK to accept that a new key will be created, inactivating the previously generated key
Click Copy
A new Client ID and Secret Key will appear in a modal for copy/pasting
Once this modal is closed, the Secret Key will not be accessible anymore
You can now start testing the API with your demo account.
When testing on our demo environment, you'll receive prefilled server responses to calls made with mock data.
When you’re ready to use the API in production, send us an email at apisupport@certn.co.
Click the profile icon
To follow this guide, you need a demo account. Make sure it's fully set up according to our instructions on how to .
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 , but most of the content you'll work with will be in .
To gain access to our API, you will need your Client ID and Client Secret. Instructions for getting these values can be found in . 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 for useful guides.
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 .
Please see and for more details on types of errors, and how to resolve them.
How manage your team settings and billing information as a Certn API user.
Enter your email and password
Click Log in
Click Settings
Locate your team
Click the Settings button
You can manage Billing info and other team settings from here.
Adding a payment card to your account allows you to use our services in the demo environment. You can also use this option in production, if paying by card.
Click Billing
Click Connect Payment Card
Fill in your credit card number
Add the expiry date and CVC number
Click Authorize Card
Navigate back to the dashboard by clicking the Certn logo in the top left
Click on the Partner tab
Click Refresh Keys
Click OK to accept that a new key will be created, inactivating the previously generated key
Click Copy
A new Client ID and Secret Key will appear in a modal for copy/pasting
Once this modal is closed, the Secret Key will not be accessible anymore
You can now start testing the API with your demo account.
You'll need to know how to Get your access token before you can follow the instructions in this section.
When you're set up within Certn, you belong to an organization. This organization has a few levels of hierarchy:
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.
Replace access_token
with your API access token:
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.
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
.
200 OK
{
[...]
"results": [
{
"id": "string<uuid>",
[...]
},
]
}
For more details on the structure of the User list response, see #retrieve-a-list-of-users.
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 how to create an application before you can follow the instructions in this section.
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 webhook, or send requests to one of our endpoints.
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.
Once your report is ready, you can download it as a PDF or HTML file via our /reports
endpoint.
Once you have your application ID, append it to /applicants
URL.
Choose the URL that corresponds to your industry
In the URL, replace {application_id}
with your application's ID
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
.
200 OK
[...]
"id": "<number>"
[...]
"report_status": "COMPLETE"
[...]
Please see Error codes for more details on types of errors, and how to resolve them.
You'll need to know your User id to follow the instructions in this page.
You can find the URLs for all our endpoints in the API Reference 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 Softcheck, which is under /applications
. You'll also make it a quickscreen, 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:
To request a Softcheck, add the request-flag 'request_softcheck': true
to your request body.
For your applicant, use our CEO's name, Andrew McLeod.
For the applicant's address, use our office location in Victoria, BC.
1006 Fort St, Victoria, BC V8V 3K4, Canada
For the owner_id
, use the id of the User requesting the application. In this situation, it's you. See #retrieve-your-users, to find out how to retrieve your User id.
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 #position-or-property-location for more information on this field.
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
.
201 Created
[...]
"id": "<number>",
[...]
"report_status": "ANALYZING",
[...]
The id in the response corresponds to the newly created applicant. Copy this id, as you'll need it next to Retrieve the results.
Please see Error codes for more details on types of errors, and how to resolve them.
Example Python request (replace CLIENT_ID and CLIENT_SECRET):
Replace TOKEN
with your API key in the following header:
Include this header in every call to our API, and keep it secure. It is your access key.
Token lifespan is indicated by the expires_in
parameter returned when a new token is requested. The default value is 36000
seconds (10 hours).
We have two types of integration users: Admin and Support users.
Admin users have access to all background checks in your Certn account and can manage your integration settings in the Partner dashboard, as well as settings for Teams.
Support users have access to all background checks in your Certn account, they cannot access or change any settings.
Creating Support users is a convenient way to assist your end users independently without needing assistance from Certn support!
Enter your email and password
Click Log in
Click Partner tab
Click Add User
Provide the Email, First Name & Last Name
Select the appropriate user role
Admin has access to Partner tools, as well as view reports and results. End-user management and team management is available through the API.
Support has access to view reports and results. They cannot manage users or teams, or access the API.
Deselect user permissions, if applicable. By default, Admin and Support users will have access to all user permissions
Can Create Reports - Allows user to order background checks
Can View Reports - Allows user to view completed background checks
Can Share Reports - Allows use to download and share background checks
Can View Applications - Allows user to view in progress background checks
Can Create and Edit Packages - Allows user to create and edit packages
Can Order Individual Checks - Allows user to order background checks from the a la carte menu
Create a temporary password in the New Password field, save to share with the user later, and advise them to reset their password upon first login
Passwords must be at least 8 characters long and contain at least one uppercase letter, number and special character (ie: !@#$%^&*)
Click Save
No User Limit
There is no charge for integration users, and you can have as many seats as required.
Keep in mind
Integration users are different than end users, and have access to all background checks associated with your customers
Client ID - The unique identifier making up the first half of your key
Client Secret - A secret key used to verify your application's identity
We recommend using the industry standard OAuth client library for your stack to handle key-token exchanges.
Go to the Partner Tab
Click refresh keys
Click Ok to accept that previously generated keys will be lost
Copy the Client ID and Client Secret Note: the client secret must be copied here or it will be lost and new key pairs must be generated
Go to the Partner tab
Application secrets are only available once, at the time of creation. Certn hashes application secrets on the backend and so it is not possible to retrieve the secrets once they've been created.
If you are already logged in go to https://app.certn.co
To log in, go to https://app.certn.co/login
Click the profile icon
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.
In the user_list.json
file, you should see one user listed in the results: it's you! Look for the id
field for your User, and copy that value. We use universally unique identifiers (UUIDs) for ids, so it'll be formatted like this:123e4567-e89b-12d3-a456-426614174000.
You'll need this to Create your first application.
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 universally unique identifiers (UUIDs), so it'll be formatted like this:123e4567-e89b-12d3-a456-426614174000
To gain access to our API, you need a valid token in an . The token is granted by our API in exchange for a . This can also be handled by third party OAuth client libraries.
If you are already logged in go to
To log in, go to
Our API authenticates users using the . This means that a Client ID and Client Secret are exchanged for a token which can be used to make requests.
You will see your Client ID under API Keys
Our regular invite process (where applicants fill the information in themselves) gathers the required consent from your applicants for each of our checks. No action is required on your part.
Using our quickscreen process allows you to enter the applicant's information without involving them directly. When issuing checks via this method, it is your responsibility to gather and obtain consent for each of the checks you plan to run.
If you've never obtained consent from your applicants before, please browse the resources in our Compliance Library. Or you can contact our compliance team to inquire about the appropriate measures to take before sending your applications.
All webhook management can be done via the Partner page.
Navigate to the Partner tab
Enter your webhook URL
Click Enable Integration
Note: The webhook URL can be changed at anytime. The secret string cannot be changed, if it is compromised, contact Certn support.
Secrets are set at the Partner level
Partner resellers will use the same webhook and secret across all accounts and sub-accounts
Our API sends updates as POST requests to your user-defined endpoints as they become available.
When receiving a 408
, 500
, 502
, 503
, or 504
status code, it retries up three additional times, waiting longer between each call. For any other status code over 399
, the API backs off on first try.
For added security, you can opt to have Certn send you signed payloads. When enabled, our API adds a Certn-Signature
header along with each request to your endpoints. This header allows you to confirm that the request came from us.
After this setup, Certn starts to sign each webhook it sends to the endpoint.
A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Certn includes a timestamp in the Certn-Signature
header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.
Use Network Time Protocol (NTP) to ensure that your server’s clock is accurate and synchronizes with the time on Certn’s servers.
Certn generates the timestamp and signature each time an event is sent to your endpoint. If Certn retries an event (e.g., your endpoint previously replied with a non-2xx
status code), then a new signature and timestamp is generated for the new delivery attempt.
The Certn-Signature
header included in each signed event contains a timestamp and one or more signatures. The timestamp is prefixed by t=
, and each signature is prefixed by a scheme. Schemes start with v
, followed by an integer. Currently, the only valid live signature scheme is v1
.
Newlines have been added for clarity, but a Certn-Signature header is on a single line.
Certn generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you should ignore all schemes that are not v1
.
It is possible to have multiple signatures with the same scheme-secret pair. This can happen when you roll (ie. expire) an endpoint’s secret from the Dashboard. The previous secret will remain active for 48 hours. During this time, your endpoint has multiple active secrets and Certn generates one signature for each secret.
You can verify a Certn signature using the following steps.
Split the header, using the ,
character as the separator, to get a list of elements. Then split each element, using the =
character as the separator, to get a prefix and value pair.
The value for the prefix t
corresponds to the timestamp, and v1
corresponds to the signature (or signatures). You can discard all other elements.
signed_payload
stringThe signed_payload
string is created by concatenating:
The timestamp (as a string)
The character .
The actual JSON payload (i.e., the request body, as text)
(The original binary string)
Note: Using JS Express, this may cause a problem (no access to the original string without adding middleware)
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload
string as the message.
Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.
To verify an individual signature (after preparing the signed_payload
and splitting the v1
prefix from the signature):
Whether you're hiring a new employee, accepting a tenant, or partnering with a business, these checks provide essential insights. They help ensure safety, reliability, and trust by revealing a person's history, criminal records, financial stability, and more.
Please review our extensive catalog of available background screening checks below!
Here are the articles in this section:
Include this flag in the body of your request:
To invite an applicant to complete a screen, include this parameter in the body of your request:
email
The candidate will be asked to disclose their Australian citizenship status and to provide supporting documentation (proof of citizenship or visa).
The following example contains fields for someone applying for a license.
Clear results
Records found
This check is available in Australia
This check is not available for a
Industry | Availability | Endpoints |
---|
See all available
Report field:
Send Australia RTW requests with the following sets of data on our to retrieve our pre-filled reports. Specify "non-Australian citizen" during the application process for both cases of test data.
First name | Last name |
---|
First name | Last name |
---|
Andrew | McLeod |
Will | NoRights |