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 (Phone Number)
​
information
object (Information)
​
position_or_property_location
object (Position or Property Location)
​
purpose_of_check
string <enum>
See Purpose of check (ACIC)​
requested_countries
Array of strings
For 
​International Criminal Record Check​
Purpose of check (ACIC)
The parameters to use for an Australian Criminal Intelligence Commission Check will depend on the purpose of your check (purpose_of_check).
If you're running an ACIC for employment, use these parameters:
Parameter
Type
Note
purpose_of_check
string <enum>
EMPLOYMENT
position_title
string
​
place_of_work
string
​
If you're running an ACIC for licensing, use these parameters:
Parameter
Type
Note
purpose_of_check
string <enum>
LICENSE
license_type
string
​
issuing_authority
string
​
If you're running an ACIC for a purpose not tied to employment or licensing, use these parameters:
Parameter
Type
Note
purpose_of_check
string <enum>
OTHER
reason_for_check
string
​
place_of_work
string
​
Parameter objects
Address
Parameter
Type
Note
address
string
​
unit
string
​
city *
string
​
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>
​enums (verification)
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
​
province_state *
string
​
country *
string
​
postal_code
string
​
Conviction
Parameter
Type
Note
offence *
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>
​enums (verification)
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>
​enums (verification)
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
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

Parameter	Type	Note
`tag`	string	Group related applications by tag
`email`	string
`phone_number`	object (Phone Number)
`information`	object (Information)
`position_or_property_location`	object (Position or Property Location)
`purpose_of_check`	string <enum>	See Purpose of check (ACIC)
`requested_countries`	Array of strings	For International Criminal Record Check

Parameter	Type	Note
`purpose_of_check`	string <enum>	`EMPLOYMENT`
`position_title`	string
`place_of_work`	string

Parameter	Type	Note
`purpose_of_check`	string <enum>	`LICENSE`
`license_type`	string
`issuing_authority`	string

Parameter	Type	Note
`purpose_of_check`	string <enum>	`OTHER`
`reason_for_check`	string
`place_of_work`	string

Parameter	Type	Note
`address`	string
`unit`	string
`city` *	string
`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>	enums (verification)
`verification_notes`	string	Notes supplementing the `certn_verification` field results
`address_reference`	object (Address Reference)

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

Parameter	Type	Note
`address`	string
`unit`	string
`city` *	string
`province_state` *	string
`country` *	string
`postal_code`	string

Parameter	Type	Note
`offence` *	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

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`

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

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

Parameter	Type	Note
`certn_verification`	string <enum>	enums (verification)
`verification_notes`	string	Notes supplementing the `certn_verification` field results

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

Parameter	Type	Note
`certn_verification`	string <enum>	enums (verification)
`verification_notes`	string	Notes supplementing the `certn_verification` field results

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.

Parameter	Type	Note
`address`	string	Required for email references

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

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)

Parameter	Type	Note
`first_name` *	string
`middle_name`	string
`last_name` *	string

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

Parameter	Type	Note
`location_type` *	string <enum>	HR: `Gig Location` Not available to PM

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

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

Parameter	Type	Note
`specialization`	string	Name of the specialization

API Reference - Previous

Resources

Request flags

Last modified 25d ago