Settings and packages
How to organize general resources in Certn's API, such as Superteams, Teams, Users, and Packages .
Demo environment
When sending test data to the following endpoints, change the domain to https://demo-api.certn.co.
To view a list of all application parameters, visit Application parameters.
Team hierarchy
Organizations often need a structured team hierarchy for billing, user management, and package organization. Certn now supports a two-tiered hierarchy (Superteam and Team levels).
As a partner, you're required to have at least one Superteam, but you can create more Superteams and add Teams under them as needed.
This hierarchy is useful when you have end users who should only access background checks related to specific groups, rather than the entire organization's checks. If you're a reseller, using multiple Superteams can help you categorize background checks by customers and control the data visible in your end users' portal.
Superteams
A superteam serves as the higher of the two levels within your account hierarchy. It functions as an overarching entity under which other teams are organized.
Retrieve a list of your superteams
GET https://api.certn.co/api/v1/superteams/
View the list of your superteams.
{
"count": int,
"next": URL,
"previous": URL,
"results": [
{
"id": string <uuid>,
"name": string
}
]
}Retrieve details of a specific superteam
GET https://api.certn.co/api/v1/superteams/{superteam_id}/
View the details of a specific superteam using the team id.
Path Parameters
superteam_id*
string
ID of the superteam
{
"id": string <uuid>,
"name": string,
"is_secure_sms_enabled": boolean,
"is_report_id_enabled": boolean,
"street_address": string,
"city": string,
"postal_code": string,
"province_state": string,
"other_province_state": string,
"country": string
}Create a superteam
POST https://api.certn.co/api/v1/superteams/
Create a new superteam.
Request Body
name*
string
Superteam name
street_address*
string
Street address of Superteam's primary location
city*
string
City of Superteam's primary location
country*
string <enum>
Country Code for Superteam's primary location. Must be one of "CA", "US", "GB", or "AU".
postal_code*
string
Postal code of Superteam's primary location
other_province_state
string
If province_state is OT, provide the province or state of the Superteam's primary location
is_secure_sms_enabled*
boolean
SMS enabled or disabled for the team
is_report_id_enabled
boolean
{
"id": "string <uuid>",
"name": "string",
"is_secure_sms_enabled": boolean,
"street_address": "string",
"city": "string",
"postal_code": "string",
"province_state": "string",
"country": "string"
}Update a superteam
PUT https://api.certn.co/api/v1/superteams/{superteam_id}/
Path Parameters
superteam_id*
string <uuid>
Superteam id
Request Body
name*
string
Superteam name
is_secure_sms_enabled*
boolean
SMS enabled or disabled for the team
is_report_id_enabled*
boolean
street_address*
string
Street address of Superteam's primary location
city*
string
City of Superteam's primary location
postal_code*
string
Postal code of Superteam's primary location
province_state*
string
for Superteam's primary location
other_province_state
string
If province_state is OT, provide the province or state of the Superteam's primary location
country*
string
ISO Country Code for Superteam's primary location. Must be one of "CA", "US", "GB", or "AU".
[
{
"id": string <uuid>,
"name": string,
"business_number": integer,
"accounting_first_name": string,
"accounting_last_name": string,
"accounting_email": string,
"team_first_name": string,
"team_last_name": string,
"team_email": string,
"team_phone_number": string,
"street_address": string,
"city": string,
"province_state": string <two letter code>,
"country": string <ISO Country Code>,
"postal_code": string,
"website": string,
"industry": string,
"active_user_count": integer,
"internal_name": string,
"team_type": string,
}
]Teams
A team serves as the lower of the two levels within your account hierarchy. It functions as an entity under a superteam. A superteam can have many teams. If pre_pay is set to false, Certn will invoice a team each month according to the checks ordered during that billing cycle. If pre_pay is set to true, the applicant's background check process will require them to pay online.
Retrieve a list of your teams
GET https://api.certn.co/api/v1/teams/
View a list of all your teams.
The results are sent via paginated response. To retrieve the next page, send a request to the URL under the field next, or add one to your page counter:
https://api.certn.co/api/v1/teams/?page=<pgNum>
You can also filter the list by a superteam by providing the superteam id as a query parameter.
Query Parameters
superteam*
string <uuid>
Superteam id
page
int
Page number to retrieve
{
"count": int,
"next": URL,
"previous": URL,
"results": [
{
"id": string <uuid>,
"name": string,
"superteam": string <uuid>,
"pre_pay": boolean
"street_address": string,
"city": string,
"postal_code": string,
"province_state": string,
"other_province_state": string,
"country": string,
"accounting_first_name": string,
"accounting_last_name": string,
"accounting_email": string,
"accounting_email_cc": string,
},
]
}Retrieve team details
GET https://api.certn.co/api/v1/teams/{team_id}/
View the details of a team.
Path Parameters
team_id*
string <uuid>
Team id
{
"id": string <uuid>,
"name": string,
"superteam": string <uuid>,
"type": string <Enum>,
"pre_pay": boolean,
"street_address": string,
"city": string,
"postal_code": string,
"province_state": string,
"other_province_state": string,
"country": string,
"accounting_first_name": string,
"accounting_last_name": string,
"accounting_email": string,
"accounting_email_cc": string
}Create a team
POST https://api.certn.co/api/v1/teams/
Create a new team.
Request Body
name*
string
Unique team name
type*
string <enum>
Team type, "HR" or "PM"
country*
string <enum>
ISO country code for team's primary location. Must be one of "CA", "US", "GB", or "AU".
pre_pay
boolean
Billing to be pre-paid. Default false.
superteam*
string <uuid>
Superteam
street_address
string
Street address of Team's primary location
city
string
City of Team's primary location
postal_code
string
Postal code of Team's primary location
other_province_state
string
If province_state is OT, provide the province or state of the Team's primary location
accounting_email_cc
string
Email addresses to CC invoice emails to
accounting_email
string
Email address to send invoices to
accounting_last_name
string
Last name of accountant responsible for handling team billing
accounting_first_name
string
First name of accountant responsible for handling team billing
{
"id": string <uuid>,
"name": string,
"superteam": string <uuid>,
"type": string <Enum>,
"pre_pay": boolean,
"street_address": string,
"city": string,
"postal_code": string,
"province_state": string,
"other_province_state": string,
"country": string,
"accounting_first_name": string,
"accounting_last_name": string,
"accounting_email": string,
"accounting_email_cc": string
}Update a team
PUT https://api.certn.co/api/v1/teams/{team_id}/
Update the details of a team.
A PUT request is an entire resource replacement.
Path Parameters
team_id*
string <uuid>
Team id
Request Body
name*
string
Unique team name
type*
string <enum>
Team type, "HR" or "PM"
country*
string <enum>
ISO country code for Team's primary location. Must be one of "CA", "US", "GB", or "AU".
pre_pay*
boolean
Billing type. Default false.
superteam*
string <uuid>
Superteam id
postal_code*
string
Postal code of Team's primary location
city*
string
City of Team's primary location
street_address*
string
Street address of Team's primary location
accounting_first_name*
string
First name of accountant responsible for handling team billing
accounting_last_name*
string
Last name of accountant responsible for handling team billing
accounting_email*
string
Email address to send invoices to
accounting_email_cc*
string
Email addresses to CC invoice emails to
other_province_state
string
If province_state is OT, provide the province or state of the Superteam's primary location
{
"id": string <uuid>,
"name": string,
"superteam": string <uuid>,
"type": string <Enum>
"pre_pay": boolean,
"street_address": string,
"city": string,
"postal_code": string,
"province_state": string,
"other_province_state": string,
"country": string,
"accounting_first_name": string,
"accounting_last_name": string,
"accounting_email": string,
"accounting_email_cc": string
}Retrieve a team's address reference templates
GET https://api.certn.co/api/v1/teams/{team_id}/address/reference_templates/
View the details of all address reference templates for a team.
Path Parameters
team_id*
string
ID of the team
[
{
"id": string,
"name": string,
"version": string,
"description": string,
"type": string < enum > ,
"questions": [{
"id": string,
"index": int,
"question": string,
"type": string < enum > ,
"multiple_choice_options": [
string,
string
],
"multiple_choice_correct_option": string,
"is_verifiable": boolean,
"is_required": boolean
}, {
"id": string,
"index": int,
"question": string,
"type": string < enum > ,
"multiple_choice_options": [
string,
string
],
"multiple_choice_correct_option": string,
"is_verifiable": boolean,
"is_required": boolean
}
]
}
]
Retrieve a team's employer reference templates
GET https://api.certn.co/api/v1/teams/{team_id}/employer/reference_templates/
View the details of all employer references templates for a team.
Path Parameters
team_id
string
ID of the team
[
{
"id": string,
"name": string,
"version": string,
"description": string,
"type": string < enum > ,
"questions": [{
"id": string,
"index": int,
"question": string,
"type": string < enum > ,
"multiple_choice_options": [
string,
string,
string
],
"multiple_choice_correct_option": string,
"is_verifiable": boolean,
"is_required": boolean
}, {
"id": string,
"index": int,
"question": string,
"type": string < enum > ,
"multiple_choice_options": [
string,
string,
string
],
"multiple_choice_correct_option": string,
"is_verifiable": boolean,
"is_required": boolean
}
]
}
]Users
A user is the individual that orders background checks via your platform. They can be assigned as the Owner of a background check to track activity as well. To grant your users access to the Certn platform for viewing reports or managing settings, they must have a login created using this method.
By default, users will not receive a Welcome email from Certn when they are created. However, they can receive a temporary password by following Forgot my password? link.
Retrieve a list of users
GET https://api.certn.co/api/v1/users/
View a list of users.
Query Parameters
superteam
string <uuid>
Superteam id
team
string <uuid>
Team id
is_active
boolean
{
"count": int,
"next": URL,
"previous": URL,
"results": [
{
"id": string <uuid>,
"first_name": string,
"last_name": string,
"is_active": boolean,
"superteam": string <uuid>,
"team": string <uuid>
}
]
}Retrieve a user's details
GET https://api.certn.co/api/v1/users/{user_id}/
View a user's details.
Path Parameters
user_id*
string <uuid>
User id
{
"id": string <uuid>,
"first_name": string,
"last_name": string,
"email": string,
"language": string <Enum>,
"is_active": boolean,
"superteam": string <uuid>,
"team": string <uuid>
}Create a user
POST https://api.certn.co/api/v1/users/
Create a new user.
Request Body
first_name*
string
User's first name
last_name*
string
User's last name
email*
string
User's email, unique
language*
string <enum>
User's language. Must be either "en" or "fr"
team*
string <uuid>
Team id
is_active*
boolean
Default true
{
"id": string <uuid>,
"first_name": string,
"last_name": string,
"email": string,
"language": string <Enum>,
"is_active": boolean,
"team": string <uuid>
}Update a user
PUT https://api.certn.co/api/v1/users/{user_id}/
Path Parameters
first_name*
string
User's first name
last_name*
string
User's last name
email*
string
User's email, unique
language*
string <enum>
Language for user details. Must be either "en" or "fr"
team*
string <uuid>
Team id
is_active*
boolean
Default true
{
"id": string <uuid>,
"first_name": string,
"last_name": string,
"email": string,
"language": string <Enum>,
"is_active": boolean,
"team": string <uuid>
}Packages
A collection of varied background check searches is known as a package. Retrieve these packages to enable your end users to choose from them on your platform.
Retrieving specific packages allows you to identify the correct Request Flags to include when users invite or instantly screen an applicant via Human Resources.
Or when users invite or instantly screen an applicant via Property Management.
Retrieve your packages
GET https://api.certn.co/api/v1/packages/
Query Parameters
superteam
string <uuid>
Superteam id
team
string <uuid>
Team id
Retrieve details for a specific package by id
GET https://api.certn.co/api/v1/packages/{package_id}/
Path Parameters
package_id
string <uuid>
ID of the package
{
"id": string <uuid>,
"name": "Package Name",
"superteam": string <uuid>,
"team": string <uuid>,
"request_flags": [
"request_enhanced_identity_verification",
"request_social_media_check",
"request_us_criminal_record_check_tier_1"
],
"settings": {
"requested_countries": [string],
"us_criminal_record_check_years": 7,
"employer_questionaire_id": string <uuid>,
"address_questionaire_id": string <uuid>,
"employer_references_max": int,
"employer_references_min": int,
"address_references_max": int,
"address_references_min": int,
"employment_verification_min": int,
"employment_verification_max": int,
"education_verification_min": int,
"education_verification_max": int,
"credential_verification_min": int,
"credential_verification_max": int,
"credential_verification_level": string <Enum>,
"education_verification_level": string <Enum>,
"employer_references_years": int,
"address_references_years": int,
"employment_verification_years": int,
"address_references_years_or_individually": string <Enum>,
"employer_references_years_or_individually": string <Enum>,
"employment_verification_years_or_individually": string <Enum>,
"purpose_of_check": string <Enum>,
"position_title": string,
"place_of_work": string,
"license_type": string,
"issuing_authority": string,
"reason_for_check": string,
"state_or_territory": string,
"location_of_work": string,
"volunteer_role": string,
"volunteer_organization": string,
"role_or_position_title": string,
"employment_sector": string <Enum>
}
}Create a package
POST https://api.certn.co/api/v1/packages/
Request Body
team
string <uuid>
Team id. Defaults to api user's team if not provided.
name*
string
Name of package
{
"id": string <uuid>,
"name": string,
"team": string <uuid>,
"request_flags": [
string
]
"settings": {
object (Package settings)
}
}Update a package
PUT https://api.certn.co/api/v1/packages/{package_id}/
Path Parameters
package_id*
string <uuid>
ID of package
Request Body
name*
string
Name of package
team*
string <uuid>
Team id
{
"id": string <uuid>,
"name": "Package Name",
"superteam": string <uuid>,
"team": string <uuid>,
"request_flags": [
"request_enhanced_identity_verification",
"request_social_media_check",
"request_us_criminal_record_check_tier_1"
],
"settings": {
"requested_countries": [string],
"us_criminal_record_check_years": 7,
"employer_questionaire_id": string <uuid>,
"address_questionaire_id": string <uuid>,
"employer_references_max": int,
"employer_references_min": int,
"address_references_max": int,
"address_references_min": int,
"employment_verification_min": int,
"employment_verification_max": int,
"education_verification_min": int,
"education_verification_max": int,
"credential_verification_min": int,
"credential_verification_max": int,
"credential_verification_level": string <Enum>,
"education_verification_level": string <Enum>,
"employer_references_years": int,
"address_references_years": int,
"employment_verification_years": int,
"address_references_years_or_individually": string <Enum>,
"employer_references_years_or_individually": string <Enum>,
"employment_verification_years_or_individually": string <Enum>,
"purpose_of_check": string <Enum>,
"position_title": string,
"place_of_work": string,
"license_type": string,
"issuing_authority": string,
"reason_for_check": string,
"state_or_territory": string,
"location_of_work": string,
"volunteer_role": string,
"volunteer_organization": string,
"role_or_position_title": string,
"employment_sector": string <Enum>
}
}Delete a package
DELETE https://api.certn.co/api/v1/packages/{package_id}/
Path Parameters
package_id*
string <uuid>
ID of package
Last updated
Was this helpful?