Certn API
Search
K
Links

Application parameters

Certn API parameters for how to request checks, collect information and generate reports.
This article lists all the parameters available when making PUT or POST calls to the /applicants endpoints.

Invite an applicant

Provide the applicant's email address, along with the appropriate Request flags. All other parameters are optional.

Run a quick screen

Provide the required parameters for each of your checks, along with the appropriate Request flags. Find the required parameters for specific checks in their page under Run a check.
An asterisk (*) next to a parameter name indicates that it's a required parameter within that object. The API will throw an error if the object is present but the parameter is missing.

Main parameters

Parameter
Type
Note
tag
string
Group related applications by tag
email
string
phone_number
object
Include country code to invite the applicant via SMS (Example: 12507897897)
information
object (Information)
Check-specific parameter
Type
Note
position_or_property_location
employment_sector
string <enum>
requested_countries
Array of strings
social_media_details

Parameter objects

Address

Parameter
Type
Note
address
string
unit
string
city *
string
county*
string
Required for US addresses. Omit or provide "" for countries other than US.
province_state *
string
country *
string
postal_code *
string
rent_or_own
string <enum>
R, O, S
Rent, Own, Staying with friends or family
cost
number
Monthly payment (rent, mortgage, etc.)
start_date
string <date>
end_date
string <date> nullable
Provide if address is not current, i.e. current is false.
current *
boolean
If this is the current address: true.
Although not recommended, if a value for current is not specified, end_date will be used to determine if the address is current.
certn_verification
string <enum>
verification_notes
string
Notes supplementing the certn_verification field results
address_reference

Address Reference

Parameter
Type
Note
email
object (Email)
phone_number
object (PhoneNumber)
name
object (Name)

Base Address

Parameter
Type
Note
address
string
unit
string
city *
string
county *
string
Required for US addresses. Omit or provide "" for countries other than US.
province_state *
string
country *
string
postal_code
string

Conviction

Parameter
Type
Note
offense *
string
Conviction code in the Criminal Code of Canada
date_of_sentence *
string <date>
Conviction date YYYY-MM-DD
court_location *
string
Sentencing court as city, province, country
description *
string
Description of the offense

Credential

Parameter
Type
Note
date_of_certification *
string <date>
YYYY-MM-DD
certification *
string
Certification title
institution *
string
description *
string
Description of the certification
current *
boolean
Currently (in the process of) obtaining it: TRUE
Already obtained: FALSE
highest_level
string
Determine the highest level for Certn to verify Use with credential_verification_level: HIGHEST

Degree

Parameter
Type
Note
degree
string <date>
verified
boolean <date> nullable

Education

Parameter
Type
Note
institution *
string
degree *
object (Degree)
current *
boolean
Currently (in the process of) obtaining it: TRUE Already obtained: FALSE
start_date *
string <date>
YYYY-MM-DD
end_date *
string <date> nullable
YYYY-MM-DD Not required if current = TRUE
highest_level
string
Determine the highest level for Certn to verify Use with education_verification_level: HIGHEST
specializations *
address *
object (Base Address)
Address of the institution

Education verification notes

Parameter
Type
Note
certn_verification
string <enum>
verification_notes
string
Notes supplementing the certn_verification field results

Employer

Parameter
Type
Note
company_name *
string
position *
string
income
number
pay_period
string <enum>
PER_HOUR, PER_MONTH, PER_YEAR, BIWEEKLY, BIMONTHLY
Default: PER_YEAR
start_date
string <date>
end_date
string <date> nullable
contact_first_name
string
First name of the employer reference Used for reference checks
contact_last_name
string
Last name of the employer reference Used for reference checks
contact_position
string
Position of the employer reference Used for reference checks
contact_email
string
Email for the employer reference Used for reference checks
contact_phone
string
Phone number for the employer reference Used for reference checks
can_contact
boolean
Can Certn contact this reference? Used for reference checks

Employer verification notes

Parameter
Type
Note
certn_verification
string <enum>
verification_notes
string
Notes supplementing the certn_verification field results

Employer References

Parameter
Type
Note
company_name *
string
Company of the employer reference
position *
string
The position of the applicant when they worked for the company
start_date *
string <date>
YYYY-MM-DD
end_date
string <date>
YYYY-MM-DD (optional)
first_name *
string
Reference's first name
last_name *
string
Reference's last name
reference_job_title *
string
The position held by the reference at the company
relationship *
string
Relationship between the reference and the applicant.
e.g. supervisor, manager, etc.
email *
string
The reference's email address.
Required for email references.
phone_number
string
The reference's phone number.
Required for phone references.

Email

Parameter
Type
Note
address
string
Required for email references

Enhanced Identity Verification

Parameter
Type
Note
id_country *
string
id_type *
string <enum>
PASSPORT, DRIVING_LICENSE, ID_CARD, VISA
face_image *
string
Base64 encoded selfie. Accepts JPEG or PNG.
Size: <10MB
Sides: <8000 pixels per side longest >300 pixels
id_frontside_image *
string
Base64 encoded image of the ID's front.
Accepts JPEG or PNG.
Size: <10MB
Sides: <8000 pixels per side, longest >300 pixels
id_backside_image
string
Base64 encoded image of the ID's back.
Accepts JPEG or PNG.
Size: <10MB
Sides: <8000 pixels per side, longest >300 pixels
on_success_url
string
Valid URL. Optional when using the redirect URL. Size: <= 200 characters

Information

Parameter
Type
Note
first_name *
string
middle_name
string
last_name *
string
last_name_at_birth
string
former_names
string
alias
string
date_of_birth *
string <date>
YYYY-MM-DD
phone_number
string
Non-numerical characters will be removed
sin_ssn
string
Social Insurance Number / Social Security Number
gender
string <enum>
Required when running a Canadian Criminal Record Check Available values: M, F, X Optional with other checks Available values: M, F
birth_city
string
birth_province_state
string
birth_other_province_state
string
Province or state if outside Canada or US
birth_country
string
license_number
string
license_valid
boolean
license_province_state
string
license_other_country
boolean nullable
Is the license from the same country as the applicant's residential country?
license_type
string <enum>
CA, US, INTERNATIONAL, NONE
cover_letter
string
addresses *
Array of object (Address)
employers
Array of object (Employer)
educations
Array of object (Education)
credentials
Array of object (Credential)
convictions
Array of object (Conviction)

Name

Parameter
Type
Note
first_name *
string
middle_name
string
last_name *
string

Phone Number

Parameter
Type
Note
phone_type
string <enum>
NONE, WORK, HOME, CELL, OTHER
number
string
country
string

Position or Property Location

The parameters to use for position_or_property_location will depend on your location_type.
If you're in the Gig economy and the position you're hiring for won't be tied to a single location, use this parameter:
Parameter
Type
Note
location_type *
string <enum>
HR: Gig Location
Not available to PM
For any other industries, use these ones:
Parameter
Type
Note
location_type *
string <enum>
HR: Position Location
PM: Property Location
city *
string
province_state *
string
country *
string
postal_code *
string
county *
string
US only

Purpose of check (Basic Disclosure And Barring Service Check)

Parameter
Type
Note
employment_sector*
string <enum>
When running a Basic Disclosure And Barring Service Check, you must include one of values listed in the employment_sector values list below.
role_or_position_title*
string
employment_sector values
When running a Basic Disclosure and Barring Service Check, you must include one of the following values for the employment_sector parameter:
  • LOCAL GOVERNMENT
  • CENTRAL GOVERNMENT
  • PUBLIC SECTOR- OTHER
  • NHS
  • PRESCHOOL EDUCATION
  • PRIMARY EDUCATION
  • SECONDARY EDUCATION
  • ACADEMY EDUCATION
  • FURTHER EDUCATION
  • HIGHER EDUCATION
  • INDEPENDENT EDUCATION
  • VOLUNTARY/CHARITY
  • PRIVATE HEALTHCARE
  • AGRICULTURE, FORESTRY AND FISHING
  • MINING AND QUARRYING
  • MANUFACTURING
  • RETAIL
  • ENERGY AND AIR CONDITIONING
  • WATER AND WASTE MANAGEMENT
  • CONSTRUCTION
  • TRADE OR REPAIR OF VEHICLES
  • TRANSPORTATION AND STORAGE
  • ACCOMMODATION AND FOOD SERVICE
  • INFORMATION AND COMMUNICATION
  • FINANCIAL AND INSURANCE
  • REAL ESTATE ACTIVITIES
  • PROFESSIONAL, TECHNICAL
  • ADMINISTRATIVE AND SUPPORT
  • SOCIAL CARE
  • ARTS AND ENTERTAINMENT
  • LEISURE, SPORT AND TOURISM
  • FOSTER/ADOPTION
  • CHILD CARE
  • DRIVERS
  • LAW ENFORCEMENT AND SECURITY
  • RECRUITMENT AND HR

Social Media Details

Parameter
Type
Note
high_school_name
string
Name of the high school
college_name
string
Name of the college
twitter_url
string
Twitter URL or handle
facebook_url
string
Facebook URL or handle
instagram_url
string
Instagram URL or handle
linkedin_url
string
LinkedIn URL or handle
tiktok_url
string
Tiktok URL or handle
reddit_url
string
Reddit URL or handle

Specialization

Parameter
Type
Note
specialization
string
Name of the specialization