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	object (Position or Property Location)
employment_sector	string <enum>	See Purpose of check (Basic Disclosure And Barring Service Check)
requested_countries	Array of strings	For International Criminal Record Check
social_media_details	object (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>	Application parameters (Application parameters)
verification_notes	string	Notes supplementing the certn_verification field results
address_reference	object (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 *	object (Specialization)
address *	object (Base Address)	Address of the institution

Education verification notes

Parameter	Type	Note
certn_verification	string <enum>	Application parameters (Application parameters)
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>	Application parameters (Application parameters)
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	ISO country code
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	ISO province or state code
birth_other_province_state	string	Province or state if outside Canada or US
birth_country	string	ISO country code
license_number	string
license_valid	boolean
license_province_state	string	ISO province or state code
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	ISO country code

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	ISO province or state code
country *	string	ISO country code
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