application parameters.md

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

Application parameters

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.

{% hint style="info" %} 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. {% endhint %}

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	See #purpose-of-check-basic-disclosure-and-barring-service-check
`requested_countries`	Array of strings	For /pages/-MiMb6nZb56Vb2GWZNHg
`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	`R`, `O`, `S` Rent, Own, Staying with friends or family
`cost`	number	Monthly payment (rent, mortgage, etc.)
`start_date`	string
`end_date`	string `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	#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
`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	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	`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`
d
verification
d_level: `HIGHEST`

Degree

Parameter	Type	Note
`degree`	string
`verified`	boolean `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	`YYYY-MM-DD`
`end_date` *	string `nullable`	`YYYY-MM-DD` Not required if `current` = `TRUE`
`highest_level`	string	Determine the highest level for Certn to verify Use with `education`
d
verification
d_level: `HIGHEST`
`specializations` *	object (Specialization)
`address` *	object (Base Address)	Address of the institution

Education verification notes

Parameter	Type	Note
`certn_verification`	string	#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	`PER_HOUR`, `PER_MONTH`, `PER_YEAR`, `BIWEEKLY`, `BIMONTHLY` Default: `PER_YEAR`
`start_date`	string
`end_date`	string `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

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	`YYYY-MM-DD`
`end_date`	string	`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	`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	`YYYY-MM-DD`
`phone_number`	string	Non-numerical characters will be removed
`sin_ssn`	string	Social Insurance Number / Social Security Number
`gender`	string	Required when running a /pages/-Mi8EDAjjmirZKJqut0r 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	`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	`NONE`, `WORK`, `HOME`, `CELL`, `OTHER`
`number`	string
`country`	string	ISO country code

Position or Property Location

{% hint style="info" %} The parameters to use for position_or_property_location will depend on your location_type. {% endhint %}

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

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

location_type *

string

HR: Gig Location

Not available to PM

For any other industries, use these ones:

Parameter	Type	Note
`location_type` *	string	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](#employment_sector-values "mention") 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