> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Unified Keys
> Pre-fill screening questions with candidate data.
## Overview
Unified keys let you pre-fill application form questions with candidate data you already store, so the candidate has less to fill in before submitting.
While parsing job postings, Kombo classifies screening questions that match our catalog of common questions (e.g. a question labeled “Surname” is classified as `LAST_NAME`).
In your front end, you can use these classifications to pre-populate data for the candidate.
## Using unified keys
### The `unified_key` question property
Each question block in the [application form](/ai-apply/application-form) contains the nullable `unified_key` property.
```json theme={null}
{
"block_type": "QUESTION",
"question_id": "6VrjehyBk685vubNydiR1hSn",
"label": "First name",
"description": null,
"required": true,
"category": null,
"question_type": "TEXT",
"unified_key": "FIRST_NAME",
"options": null,
"display_when": null
}
```
### Select options
For unified keys with catalog type `ENUM` (questions with `question_type` `SINGLE_SELECT` or `MULTI_SELECT`), each option carries a nullable `unified_key` as well.
For example, `GENDER` has catalog type `ENUM` and supports the option keys `MALE`, `FEMALE`, `NON_BINARY`, and `NOT_SPECIFIED`.
```json theme={null}
{
"block_type": "QUESTION",
"question_id": "4niZQuc6rfGmAnMfG1gva1Ue",
"label": "Gender",
"description": null,
"required": true,
"category": null,
"question_type": "SINGLE_SELECT",
"unified_key": "GENDER",
"options": [
{
"id": "ASN2C77WyJxBH2NzpiukDu3H",
"label": "Male",
"unified_key": "MALE"
},
{
"id": "GDSBasEhkdKzu9ZxpkpYaX5h",
"label": "Female",
"unified_key": "FEMALE"
},
{
"id": "3irQtkRAj1gCmwB3uWvYAQPi",
"label": "Decline to self-identify",
"unified_key": "NOT_SPECIFIED"
},
{
"id": "Wq7tKp2ZxMnR4bVcL9sDyH3e",
"label": "Other",
"unified_key": null
}
],
"display_when": null
}
```
When submitting, the answer for a select uses the option's `id` property: a
single ID for `SINGLE_SELECT`, or an array of IDs for `MULTI_SELECT`. The
unified key is only used to find that option. Options without a counterpart in
the catalog have a `null` unified key. The option keys of each `ENUM` key are
listed in the catalog below.
### Pre-filling questions in your UI
When you render the form, walk all questions, including those nested in sections, and fill any question whose `unified_key` matches data you already store.
For a text question, write the value into the field. A question with `unified_key` `FIRST_NAME` gets the candidate's first name.
For a select, match the option the same way. If you know your user is `FEMALE`, you can search for a question with `unified_key` `GENDER`, and in that question search for an option with `unified_key` `FEMALE`. If found, pre-select that option. Otherwise, leave the question to the candidate.
Submitting works the same with or without pre-filling: you submit each `question_id` with the candidate's answer. Unified keys are never part of the submit payload (always use the `question_id`, not the `unified_key`).
New keys may be added over time, so treat keys you don't handle like `null`.
### Rendering pre-filled data in your UI
Whether to show a pre-filled question to the candidate in your UI is up to you.
We recommend pre-filling and hiding primitive questions such as `FIRST_NAME` and `LAST_NAME`, as they are not contentious.
Consent questions like `TERMS_AND_CONDITIONS` and `APPLICANT_POOL_CONSENT` should stay visible: the candidate should be able to agree to those themselves.
Hiding a question in your UI does not remove the need to include its answer in
the submission. A required question still needs an answer, so always submit
the pre-filled value. Continue to respect [conditional
rendering](/ai-apply/application-form#conditional-rendering): questions whose
`display_when` condition is not met must not be answered.
## Product implementation
When deciding which unified keys to support, consider what data you already store in your product and implement handling for the related unified keys.
For example, if your product stores the candidate’s resume, first name, and last name, you’ll want to handle the following unified keys:
* `FIRST_NAME`
* `LAST_NAME`
* `FULL_NAME`
* `RESUME`
## Complete list of unified keys
Fields related to where the candidate currently lives, including full addresses, individual address components, and residence type information
| Key | Label | Expected Type | Options |
| ----------------------- | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RESIDENCE_TYPE` | Residence Type | ENUM | `HOME`, `WORK`, `MAILING` |
| `RESIDENCE_FULL_STRING` | Full Residence | TEXT | |
| `RESIDENCE_COUNTRY` | Country | ENUM | `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW` |
| `RESIDENCE_CITY` | City | TEXT | |
| `RESIDENCE_STATE` | State/Province/Region | TEXT | |
| `RESIDENCE_LINE_1` | Residence Line 1 | TEXT | |
| `RESIDENCE_LINE_2` | Residence Line 2 | TEXT | |
| `RESIDENCE_ZIP_CODE` | Postal Code | TEXT | |
Fields that require explicit consent or agreement from the candidate, including terms of service, privacy policies, and data usage permissions
| Key | Label | Expected Type |
| ------------------------ | ---------------------- | ------------- |
| `APPLICANT_POOL_CONSENT` | Candidate Pool Consent | BOOLEAN |
| `TERMS_AND_CONDITIONS` | Terms and Conditions | BOOLEAN |
Fields containing basic personal details about the candidate, including names, gender, availability, and personal documents like resumes
| Key | Label | Expected Type | Options |
| --------------------- | ------------------- | ------------- | ----------------------------------------------- |
| `FIRST_NAME` | First Name | TEXT | |
| `LAST_NAME` | Last Name | TEXT | |
| `FULL_NAME` | Full Name | TEXT | |
| `GENDER` | Gender | ENUM | `MALE`, `FEMALE`, `NON_BINARY`, `NOT_SPECIFIED` |
| `EXPECTED_START_DATE` | Expected Start Date | DATE | |
| `RESUME` | Resume | FILE | |
| `BIRTH_DATE` | Birth Date | DATE | |
Fields related to phone numbers and telephonic contact information, including phone types, country codes, national numbers, and extensions.
Keyed fields expect different formats:
* `FULL_PHONE_NUMBER`: E.164 format
* `PHONE_NATIONAL_NUMBER`: national phone number format (e.g. 123 456 7890)
| Key | Label | Expected Type | Options |
| ----------------------- | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PHONE_NUMBER_TYPE` | Phone Number Type | ENUM | `MOBILE`, `LANDLINE`, `WORK`, `HOME` |
| `FULL_PHONE_NUMBER` | Full Phone Number | TEXT | |
| `PHONE_COUNTRY_CODE` | Phone Country Code | ENUM | `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW` |
| `PHONE_NATIONAL_NUMBER` | Phone National Number | TEXT | |
| `PHONE_EXTENSION` | Phone Extension | TEXT | |