# 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](/api/api-reference/resources/application-parameters/request-flags.md). All other parameters are optional.

## **Run a quick screen**

Provide the required parameters for each of your checks, along with the appropriate [Request flags](/api/api-reference/resources/application-parameters/request-flags.md). Find the required parameters for specific checks in their page under [Run a check](/api/guides/checks.md).

{% 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="/pages/-MiMb6nZb56Vb2GWZNHg">/pages/-MiMb6nZb56Vb2GWZNHg</a></p>                                       |
| `social_media_details`          | object ([Social Media Details](/api/api-reference/resources/application-parameters.md#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/)![](/files/i1X0t7ez6Vlx9HiwQQXC) |
| `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="/pages/Ff7ETG6TNO6WG3WwLh8e#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="/pages/Ff7ETG6TNO6WG3WwLh8e#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](/api/api-reference/resources/region-codes.md)                                                                                                                     |
| `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="/pages/-Mi8EDAjjmirZKJqut0r">/pages/-Mi8EDAjjmirZKJqut0r</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](/api/api-reference/resources/region-codes.md)                                                                                                                                                                                                     |
| `birth_other_province_state` | string                                      | Province or state if outside Canada or US                                                                                                                                                                                                                                      |
| `birth_country`              | string                                      | [ISO country code](/api/api-reference/resources/region-codes.md)                                                                                                                                                                                                               |
| `license_number`             | string                                      |                                                                                                                                                                                                                                                                                |
| `license_valid`              | boolean                                     |                                                                                                                                                                                                                                                                                |
| `license_province_state`     | string                                      | [ISO province or state code](/api/api-reference/resources/region-codes.md)                                                                                                                                                                                                     |
| `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](/api/api-reference/resources/region-codes.md) |

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.certn.co/api/api-reference/resources/application-parameters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.