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 ()

Check-specific parameter

Type

Note

position_or_property_location

object ()

employment_sector

string <enum>

See

requested_countries

Array of strings

For

social_media_details

object ()

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

object ()

Address Reference

Parameter

Type

Note

email

object ()

phone_number

object ()

name

object ()

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

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 : HIGHEST

Degree

Parameter

Type

Note

degree

string <date>

verified

boolean <date> nullable

Education

Parameter

Type

Note

institution *

string

degree *

object ()

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 : HIGHEST

specializations *

object ()

address *

object ()

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 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 ()

employers

Array of object ()

educations

Array of object ()

credentials

Array of object ()

convictions

Array of object ()

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 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

PreviousResources NextRequest flags

Last updated 1 year ago

Was this helpful?