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.Provide the applicant's email address, along with the appropriate Request flags. All other parameters are optional.
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.
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 | |
Check-specific parameter | Type | Note |
---|---|---|
position_or_property_location | | |
purpose_of_check | string <enum> | |
employment_sector | string <enum> | |
requested_countries | Array of strings | |
social_media_details | |
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> | |
verification_notes | string | Notes supplementing the certn_verification field results |
address_reference | |
Parameter | Type | Note |
---|---|---|
email | | |
phone_number | | |
name | |
Parameter | Type | Note |
---|---|---|
address | string | |
unit | string | |
city * | string | |
province_state * | string | |
country * | string | |
postal_code | string | |
Parameter | Type | Note |
---|---|---|
offence * | string | |
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 |
Parameter | Type | Note |
---|---|---|
degree | string <date> | |
verified | boolean <date> nullable | |
Parameter | Type | Note |
---|---|---|
institution * | string | |
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 | |
specializations * | | |
address * | Address of the institution |
Parameter | Type | Note |
---|---|---|
certn_verification | string <enum> | |
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> | |
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 | |
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 | |
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 * | | |
employers | | |
educations | | |
credentials | | |
convictions | |
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 |
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 |
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> | Use string 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> | Use string 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> | Use string OTHER |
reason_for_check * | string | |
place_of_work * | string | |
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 | |
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
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 |
Last modified 1d ago