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 contains the nullable unified_key property.

{
  "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.

{
  "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: 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

Applicant Residence

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

Consent

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

Personal Information

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

Phone

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