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

{% 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](#information)) |                                                                               |

| Check-specific parameter        | Type                                                                     | Note                                                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `position_or_property_location` | object ([Position or Property Location](#position-or-property-location)) |                                                                                                                                            |
| `employment_sector`             | string \<enum>                                                           | See [#purpose-of-check-basic-disclosure-and-barring-service-check](#purpose-of-check-basic-disclosure-and-barring-service-check "mention") |
| `requested_countries`           | Array of strings                                                         | <p>For </p><p><a data-mention href="../../guides/checks/international-criminal-record-check">international-criminal-record-check</a></p>   |
| `social_media_details`          | object ([Social Media Details](#specialization))                         |                                                                                                                                            |

## Parameter objects

### Address

<table><thead><tr><th width="249.33333333333331">Parameter</th><th>Type</th><th>Note</th></tr></thead><tbody><tr><td><code>address</code></td><td>string</td><td></td></tr><tr><td><code>unit</code></td><td>string</td><td></td></tr><tr><td><code>city</code> *</td><td>string</td><td></td></tr><tr><td><code>county</code>*</td><td>string</td><td>Required for US addresses. Omit or provide "" for countries other than US.</td></tr><tr><td><code>province_state</code> *</td><td>string</td><td></td></tr><tr><td><code>country</code> * </td><td>string</td><td></td></tr><tr><td><code>postal_code</code> *</td><td>string</td><td></td></tr><tr><td><code>rent_or_own</code></td><td>string &#x3C;enum></td><td><p><code>R</code>, <code>O</code>, <code>S</code> </p><p></p><p>Rent, Own, Staying with friends or family</p></td></tr><tr><td><code>cost</code></td><td>number</td><td>Monthly payment (rent, mortgage, etc.)</td></tr><tr><td><code>start_date</code></td><td>string &#x3C;date></td><td></td></tr><tr><td><code>end_date</code></td><td>string &#x3C;date> <code>nullable</code></td><td>Provide if address is not current, i.e. <code>current</code> is <code>false</code>.</td></tr><tr><td><code>current</code> *</td><td>boolean</td><td><p>If this is the current address: <code>true</code>.</p><p></p><p>Although not recommended, if a value for <code>current</code> is <strong>not</strong> specified, <code>end_date</code> will be used to determine if the address is current.</p></td></tr><tr><td><code>certn_verification</code></td><td>string &#x3C;enum></td><td><a data-mention href="#enums">#enums</a> (<a data-mention href="#verification">#verification</a>)</td></tr><tr><td><code>verification_notes</code></td><td>string</td><td>Notes supplementing the <code>certn_verification</code> field results</td></tr><tr><td><code>address_reference</code></td><td>object (<a href="#address-reference">Address Reference</a>)</td><td></td></tr></tbody></table>

### Address Reference

| Parameter      | Type                                 | Note |
| -------------- | ------------------------------------ | ---- |
| `email`        | object ([Email](#email))             |      |
| `phone_number` | object ([PhoneNumber](#phonenumber)) |      |
| `name`         | object ([Name](#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/)![](https://1603615932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mb7UCYXOrIqSvqbGTR2%2Fuploads%2Fbdlx8v4ady44WZ7x7y0K%2F16x16_2.png?alt=media\&token=63e63f36-8c7e-4f14-b435-1aabf76a9cdb) |
| `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        | <p>Currently (in the process of) obtaining it: <code>TRUE</code></p><p>Already obtained: <code>FALSE</code></p>                                                                                                                |
| `highest_level`            | string         | <p>Determine the highest level for Certn to verify<br><br><em>Use with</em> <a href="request-flags#credential-verification-flags"><em><code>credential\_verification\_level</code></em></a><em>: <code>HIGHEST</code></em></p> |

### Degree

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

### Education

| Parameter            | Type                                       | Note                                                                                                                                                                                                                         |
| -------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `institution` \*     | string                                     |                                                                                                                                                                                                                              |
| `degree` \*          | object ([Degree](#degree))                 |                                                                                                                                                                                                                              |
| `current` \*         | boolean                                    | <p>Currently (in the process of) obtaining it: <code>TRUE</code><br>Already obtained: <code>FALSE</code></p>                                                                                                                 |
| `start_date` \*      | string \<date>                             | `YYYY-MM-DD`                                                                                                                                                                                                                 |
| `end_date` \*        | string \<date> `nullable`                  | <p><code>YYYY-MM-DD</code><br><br><em>Not required if <code>current</code> = <code>TRUE</code></em></p>                                                                                                                      |
| `highest_level`      | string                                     | <p>Determine the highest level for Certn to verify<br><br><em>Use with</em> <a href="request-flags#education-verification-flags"><em><code>education\_verification\_level</code></em></a><em>: <code>HIGHEST</code></em></p> |
| `specializations` \* | object ([Specialization](#specialization)) |                                                                                                                                                                                                                              |
| `address` \*         | object ([Base Address](#baseaddress))      | Address of the institution                                                                                                                                                                                                   |

### Education verification notes

| Parameter            | Type           | Note                                                                  |
| -------------------- | -------------- | --------------------------------------------------------------------- |
| `certn_verification` | string \<enum> | [#enums](#enums "mention") ([#verification](#verification "mention")) |
| `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>            | <p><code>PER\_HOUR</code>, <code>PER\_MONTH</code>, <code>PER\_YEAR</code>, <code>BIWEEKLY</code>, <code>BIMONTHLY</code></p><p></p><p>Default: <code>PER\_YEAR</code></p> |
| `start_date`         | string \<date>            |                                                                                                                                                                            |
| `end_date`           | string \<date> `nullable` |                                                                                                                                                                            |
| `contact_first_name` | string                    | <p>First name of the employer reference <br><br><em>Used for reference checks</em></p>                                                                                     |
| `contact_last_name`  | string                    | <p>Last name of the employer reference<br><br><em>Used for reference checks</em></p>                                                                                       |
| `contact_position`   | string                    | <p>Position of the employer reference<br><br><em>Used for reference checks</em></p>                                                                                        |
| `contact_email`      | string                    | <p>Email for the employer reference<br><br><em>Used for reference checks</em></p>                                                                                          |
| `contact_phone`      | string                    | <p>Phone number for the employer reference<br><br><em>Used for reference checks</em></p>                                                                                   |
| `can_contact`        | boolean                   | <p>Can Certn contact this reference?<br><br><em>Used for reference checks</em></p>                                                                                         |

### Employer verification notes

| Parameter            | Type           | Note                                                                  |
| -------------------- | -------------- | --------------------------------------------------------------------- |
| `certn_verification` | string \<enum> | [#enums](#enums "mention") ([#verification](#verification "mention")) |
| `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         | <p>Relationship between the reference and the applicant. </p><p><br><em>e.g. supervisor, manager, etc.</em></p> |
| `email` \*               | string         | <p>The reference's email address. </p><p><strong>Required for email references.</strong></p>                    |
| `phone_number`           | string         | <p>The reference's phone number. </p><p><strong>Required for phone references.</strong></p>                     |

### 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/api-reference/resources/region-codes)                                                                                                   |
| `id_type` \*            | string \<enum> | `PASSPORT`, `DRIVING_LICENSE`, `ID_CARD`, `VISA`                                                                                                                                     |
| `face_image` \*         | string         | <p>Base64 encoded selfie. Accepts <code>JPEG</code> or <code>PNG</code>. </p><p></p><p>Size: <10MB</p><p>Sides: <8000 pixels per side longest >300 pixels</p>                        |
| `id_frontside_image` \* | string         | <p>Base64 encoded image of the ID's front.</p><p>Accepts <code>JPEG</code> or <code>PNG</code>.</p><p></p><p>Size: <10MB</p><p>Sides: <8000 pixels per side, longest >300 pixels</p> |
| `id_backside_image`     | string         | <p>Base64 encoded image of the ID's back.</p><p>Accepts <code>JPEG</code> or <code>PNG</code>.</p><p></p><p>Size: <10MB</p><p>Sides: <8000 pixels per side, longest >300 pixels</p>  |
| `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>                              | <p>Required when running a  <a data-mention href="../../guides/checks/canadian-criminal-record-check">canadian-criminal-record-check</a><br>Available values: <code>M</code>, <code>F</code>, <code>X</code> <br><br>Optional with other checks<br>Available values: <code>M</code>, <code>F</code> </p> |
| `birth_city`                 | string                                      |                                                                                                                                                                                                                                                                                                          |
| `birth_province_state`       | string                                      | [ISO province or state code](https://docs.certn.co/api/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/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/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](#address))       |                                                                                                                                                                                                                                                                                                          |
| `employers`                  | Array of object ([Employer](#employer))     |                                                                                                                                                                                                                                                                                                          |
| `educations`                 | Array of object ([Education](#education))   |                                                                                                                                                                                                                                                                                                          |
| `credentials`                | Array of object ([Credential](#credential)) |                                                                                                                                                                                                                                                                                                          |
| `convictions`                | Array of object ([Conviction](#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/api-reference/resources/region-codes) |

### 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                                                                |
| ------------------ | -------------- | ------------------------------------------------------------------- |
| `location_type` \* | string \<enum> | <p>HR: <code>Gig Location</code><br> </p><p>Not available to PM</p> |

For any other industries, use these ones:

| Parameter           | Type           | Note                                                                                                              |
| ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `location_type` \*  | string \<enum> | <p>HR: <code>Position Location</code></p><p>PM: <code>Property Location</code></p>                                |
| `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/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](#employment_sector-values "mention") list below. |
| `role_or_position_title`\* | string         |                                                                                                                                                                                       |

<details>

<summary><code>employment_sector</code> values</summary>

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`&#x20;
* `ARTS AND ENTERTAINMENT`
* `LEISURE, SPORT AND TOURISM`
* `FOSTER/ADOPTION`
* `CHILD CARE`
* `DRIVERS`
* `LAW ENFORCEMENT AND SECURITY`
* `RECRUITMENT AND HR`

</details>

### Social Media Details <a href="#specialization" id="specialization"></a>

| 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 <a href="#specialization" id="specialization"></a>

| Parameter        | Type   | Note                       |
| ---------------- | ------ | -------------------------- |
| `specialization` | string | Name of the specialization |