For the complete documentation index, see [llms.txt](https://docs.certn.co/api/llms.txt). This page is also available as [Markdown](https://docs.certn.co/api/certn-api-v-1.0/api-reference/resources/application-parameters.md).

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](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters/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](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters/request-flags). Find the required parameters for specific checks in their page under [Run a check](https://docs.certn.co/api/v-1.0/guides/checks).

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](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#phonenumber)) |  |
| `information` | object ([Information](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#information)) |  |

## Check-specific parameter

| Parameter | Type | Note |
|-----------|------|------|
| `position_or_property_location` | object ([Position or Property Location](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#position-or-property-location)) |  |
| `employment_sector` | string <enum> | See [Purpose of check (Basic Disclosure And Barring Service Check](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#purpose-of-check-basic-disclosure-and-barring-service-check) |
| `requested_countries` | Array of strings | For [International Criminal Record Check](https://docs.certn.co/api/v-1.0/guides/checks/international-criminal-record-check) |
| `social_media_details` | object ([Social Media Details](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#specialization)) |  |

## 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`. |
| `certn_verification` | string <enum> | [Application parameters](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#enums) ( [Application parameters](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#verification)) |
| `verification_notes` | string | Notes supplementing the `certn_verification` field results |
| `address_reference` | object ([Address Reference](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#address-reference)) |  |

### Address Reference

| Parameter | Type | Note |
|-----------|------|------|
| `email` | object ([Email](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#email)) |  |
| `phone_number` | object ([PhoneNumber](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#phonenumber)) |  |
| `name` | object ([Name](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#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](http://www.criminal-code.ca/) |
| `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` or Already obtained: `FALSE` |
| `highest_level` | string | Determine the highest level for Certn to verify |

### Degree

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

### Education

| Parameter | Type | Note |
|-----------|------|------|
| `institution` | string \* |  |
| `degree` | object ([Degree](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#degree)) |  |
| `current` | boolean \* | Currently (in the process of) obtaining it: `TRUE` or Already obtained: `FALSE` |
| `start_date` | string \* | `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 |
| `specializations` | object ([Specialization](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#specialization)) |  |
| `address` | object ([Base Address](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#baseaddress)) | Address of the institution |

### Education verification notes

| Parameter | Type | Note |
|-----------|------|------|
| `certn_verification` | string <enum> | [Application parameters](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#enums) ( [Application parameters](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#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  |
| `contact_last_name` | string | Last name of the employer reference  |
| `contact_position` | string | Position of the employer reference  |
| `contact_email` | string | Email for the employer reference  |
| `contact_phone` | string | Phone number for the employer reference  |
| `can_contact` | boolean | Can Certn contact this reference? |

### 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 <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](https://docs.certn.co/api/v-1.0/api-reference/resources/region-codes) |
| `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 \* | `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](https://docs.certn.co/api/v-1.0/guides/checks/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](https://docs.certn.co/api/v-1.0/api-reference/resources/region-codes) |
| `birth_other_province_state` | string | Province or state if outside Canada or US |
| `birth_country` | string | [ISO country code](https://docs.certn.co/api/v-1.0/api-reference/resources/region-codes) |
| `license_number` | string |  |
| `license_valid` | boolean |  |
| `license_province_state` | string | [ISO province or state code](https://docs.certn.co/api/v-1.0/api-reference/resources/region-codes) |
| `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](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#address)) |  |
| `employers` | Array of object ([Employer](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#employer)) |  |
| `educations` | Array of object ([Education](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#education)) |  |
| `credentials` | Array of object ([Credential](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#credential)) |  |
| `convictions` | Array of object ([Conviction](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#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](https://docs.certn.co/api/v-1.0/api-reference/resources/region-codes) |

### 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](https://docs.certn.co/api/api-reference/resources/region-codes#provinces-and-states) |
| `country` | string \* | [ISO country code](https://docs.certn.co/api/v-1.0/api-reference/resources/region-codes#countries) |
| `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](https://docs.certn.co/api/v-1.0/api-reference/resources/application-parameters#employment_sector-values) 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 |

**Last updated 2 years ago**

This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the [privacy policy](/content/privacy-policy/index.html).