Certn API
Sign In Certn Certn Help

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

ParameterTypeNote

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 parameterTypeNote

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

ParameterTypeNote

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>

#enums (#verification)

verification_notes

string

Notes supplementing the certn_verification field results

address_reference

object (Address Reference)

Address Reference

ParameterTypeNote

email

object (Email)

phone_number

object (PhoneNumber)

name

object (Name)

Base Address

ParameterTypeNote

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

ParameterTypeNote

offense *

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

Credential

ParameterTypeNote

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

ParameterTypeNote

degree

string <date>

verified

boolean <date> nullable

Education

ParameterTypeNote

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

ParameterTypeNote

certn_verification

string <enum>

#enums (#verification)

verification_notes

string

Notes supplementing the certn_verification field results

Employer

ParameterTypeNote

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

ParameterTypeNote

certn_verification

string <enum>

#enums (#verification)

verification_notes

string

Notes supplementing the certn_verification field results

Employer References

ParameterTypeNote

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

ParameterTypeNote

address

string

Required for email references

Enhanced Identity Verification

ParameterTypeNote

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

ParameterTypeNote

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

ParameterTypeNote

first_name *

string

middle_name

string

last_name *

string

Phone Number

ParameterTypeNote

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:

ParameterTypeNote

location_type *

string <enum>

HR: Gig Location

Not available to PM

For any other industries, use these ones:

ParameterTypeNote

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)

ParameterTypeNote

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

ParameterTypeNote

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

ParameterTypeNote

specialization

string

Name of the specialization

PreviousResourcesNextRequest flags

Last updated