Displaying the form

Render screening questions, handle conditional fields, and collect candidate answers.

Overview

Kombo’s parsing process extracts the screening questions and additional form metadata for a job posting.

This page describes the API response structure and provides advice on displaying the form in your product.

Block structure

The application form is composed of an array of blocks. Each block’s block_type tells you how to render it:

Block type	Description
SECTION	The section heading and child blocks to display.
QUESTION	A form input for the candidate’s answer.
INFORMATION	Instructional text that provides additional context.

Every job’s application form is different and dynamically parsed by Kombo. Ensure you handle the block structure by rendering all blocks in the order provided, including nested sections.

Sections

A section has a label and a children array. Its children can be questions, information blocks, or further sections.

Questions and information blocks can also appear at the top level without a section.

{
  "block_type": "SECTION",
  "label": "Personal Information",
  "children": [
    {
      "block_type": "INFORMATION",
      "category": null,
      "text": "We will use this information to contact you about your application.",
      "display_when": null
    },
    {
      "block_type": "SECTION",
      "label": "Name",
      "children": [
        {
          "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
        }
      ]
    }
  ]
}

Increase the heading level for each nested section, up to h6. For example, if your page title uses h1, start the form’s sections at h2 and increment by one per nested heading.

Sections have no display_when property of their own. Display a section and its heading only when at least one question or information block within it is visible, including through nested sections. See Conditional rendering.

Questions

Every question includes question_id, label, description, required, category, question_type, unified_key, options, and display_when.

Use question_type to choose how to render the input and question_id to identify its answer. Show the label, mark required questions, and display the description as helper text when it is not null.

The options array is present for SINGLE_SELECT and MULTI_SELECT questions and is null for other types. Each option has an id, a label, and a nullable unified_key.

Information blocks

An information block contains instructions or other content in its text property. It has no question_id and does not collect an answer.

{
  "block_type": "INFORMATION",
  "category": "EEO",
  "text": "The following equal employment opportunity questions are voluntary. Read our <a href=\"https://example.com/privacy\">privacy policy</a> for details.",
  "display_when": null
}

Render the text where it appears in the form. Information blocks follow the same display_when rules as questions, so explanations can appear alongside the questions they relate to.

HTML within labels, descriptions, and information block text

Question labels, descriptions, and information block text can contain HTML links, such as a link to a privacy policy.

This content comes from external career sites. Treat it as untrusted HTML and sanitize it before rendering.

Example

{
  "block_type": "QUESTION",
  "question_id": "6VrjehyBk685vubNydiR1hSn",
  "label": "Please accept our <a href=\"https://www.example.com/privacy\">Privacy Policy</a>",
  "description": null,
  "required": true,
  "category": null,
  "question_type": "BOOLEAN",
  "unified_key": null,
  "options": null,
  "display_when": null
}

Categories

Questions and information blocks include a category value. "EEO" identifies Equal Employment Opportunity content, and null means uncategorized.

The category describes the content. required and display_when still determine whether an answer is required.

Example

{
  "block_type": "QUESTION",
  "question_id": "35V1AegJ3qtxUEnpSDJ62e78",
  "label": "Do you have a disability?",
  "description": null,
  "required": false,
  "category": "EEO",
  "question_type": "TEXT",
  "unified_key": null,
  "options": null,
  "display_when": null
}

Question type details

The examples below pair each question type with a matching answer.

Text (TEXT)

A TEXT question accepts a non-empty string.

Question

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

Answer

{
  "question_id": "6VrjehyBk685vubNydiR1hSn",
  "answer": "John"
}

Numbers (NUMBER)

A NUMBER question accepts a number.

Question

{
  "block_type": "QUESTION",
  "question_id": "3fJx2VbNMwPq8RzKtY5dHnLu",
  "label": "How many years of professional experience do you have?",
  "description": "Enter 0 if this would be your first role.",
  "required": true,
  "category": null,
  "question_type": "NUMBER",
  "unified_key": null,
  "options": null,
  "display_when": null
}

Answer

{
  "question_id": "3fJx2VbNMwPq8RzKtY5dHnLu",
  "answer": 7
}

Booleans (BOOLEAN)

A BOOLEAN question accepts true or false.

Question

{
  "block_type": "QUESTION",
  "question_id": "Xp2mKvR8sTcW4nQhJ6fBdY3z",
  "label": "I agree to the <a href=\"https://example.com/privacy\">privacy policy</a>",
  "description": null,
  "required": true,
  "category": null,
  "question_type": "BOOLEAN",
  "unified_key": "TERMS_AND_CONDITIONS",
  "options": null,
  "display_when": null
}

Answer

{
  "question_id": "Xp2mKvR8sTcW4nQhJ6fBdY3z",
  "answer": true
}

Let candidates answer consent questions themselves. Do not pre-fill consent answers.

Dates (DATE)

A DATE question accepts an ISO 8601 date string.

Question

{
  "block_type": "QUESTION",
  "question_id": "9wLtF5cPnKvX2mRj7YqZs4hB",
  "label": "When can you start?",
  "description": null,
  "required": false,
  "category": null,
  "question_type": "DATE",
  "unified_key": "EXPECTED_START_DATE",
  "options": null,
  "display_when": null
}

Answer

{
  "question_id": "9wLtF5cPnKvX2mRj7YqZs4hB",
  "answer": "2026-09-01T00:00:00.000Z"
}

Single select (SINGLE_SELECT)

A SINGLE_SELECT question accepts the id of one option from its options array.

Question

{
  "block_type": "QUESTION",
  "question_id": "EKaumKPGjeA97cb8ystMmkCe",
  "label": "What is your desired working location?",
  "description": "Select your preferred work arrangement",
  "required": true,
  "category": null,
  "question_type": "SINGLE_SELECT",
  "unified_key": null,
  "options": [
    {
      "id": "BsnL4pAhNQc26uSc4JopTP3P",
      "label": "Remote",
      "unified_key": null
    },
    {
      "id": "8T4fcKgzLxbKFUo4saXaoMTG",
      "label": "On-site",
      "unified_key": null
    }
  ],
  "display_when": null
}

Answer

{
  "question_id": "EKaumKPGjeA97cb8ystMmkCe",
  // The option ID for "Remote"
  "answer": "BsnL4pAhNQc26uSc4JopTP3P",
}

Multi-select (MULTI_SELECT)

A MULTI_SELECT question accepts an array of option IDs from its options array.

Question

{
  "block_type": "QUESTION",
  "question_id": "7VMWn39TqeHRT3nW12AXMD9V",
  "label": "Which languages do you speak?",
  "description": "Select all that apply.",
  "required": true,
  "category": null,
  "question_type": "MULTI_SELECT",
  "unified_key": null,
  "options": [
    {
      "id": "4KcNp8RvXw2mYqTjF5sHbL7d",
      "label": "English",
      "unified_key": null
    },
    {
      "id": "6QhZt3WkPn9cVxRm2JfDy8sB",
      "label": "German",
      "unified_key": null
    },
    {
      "id": "2TmXr7BpKv4wQzNh9LcFs6jY",
      "label": "French",
      "unified_key": null
    }
  ],
  "display_when": null
}

Answer

{
  "question_id": "7VMWn39TqeHRT3nW12AXMD9V",
  // The option IDs for "English" and "German"
  "answer": ["4KcNp8RvXw2mYqTjF5sHbL7d", "6QhZt3WkPn9cVxRm2JfDy8sB"],
}

Files (FILE)

A FILE question accepts one file as an object containing:

• name: the filename, including its extension.
• content_type: the file’s MIME type.
• data: the base64-encoded file contents.

Question

{
  "block_type": "QUESTION",
  "question_id": "3dT5df2PhyVp7Rze76S5NqrW",
  "label": "Resume",
  "description": "Upload your resume as a PDF.",
  "required": true,
  "category": null,
  "question_type": "FILE",
  "unified_key": "RESUME",
  "options": null,
  "display_when": null
}

Answer

{
  "question_id": "3dT5df2PhyVp7Rze76S5NqrW",
  "answer": {
    "name": "john_doe_resume.pdf",
    "content_type": "application/pdf",
    "data": "JVBERi0xLjQK..."
  }
}

Storing candidate answers

Your application can reuse the same answer format to drive the whole apply flow.

Keep a map of question_id to answer for each candidate’s application session. Using the same values when evaluating display_when conditions and building the application payload ensures these steps stay consistent.

When building screening_question_answers, turn the map into an array of { question_id, answer } entries using those stored values.

Omit unanswered optional questions from the submission.

Conditional rendering

Questions and information blocks have a nullable display_when property. When it is null, the block is always visible. Otherwise, display the block only when the referenced question’s current answer matches answer_equals.

The condition refers to a question through question_id. Match against the answer you store for that question:

Referenced question type	Condition is met when
BOOLEAN	The answer equals the condition’s true or false value.
SINGLE_SELECT	The selected option ID equals answer_equals.
MULTI_SELECT	At least one selected option ID occurs in the answer_equals array.

If the referenced question has no answer yet, the condition is not met. For multi-selects, the arrays do not need to be identical: a condition containing English and German is met if the candidate selects either language, or both.

Re-evaluate conditions whenever an answer changes. A conditional question can reveal further questions, so follow the chain of conditions recursively. When a question’s condition is no longer met, remove its answer from storage. This prevents an old answer from keeping further questions visible or being included in the submission.

A required question needs an answer only when its condition is met. Do not submit answers to questions whose conditions are not met. Hide a section and its heading when none of its questions or information blocks remain visible, including within nested sections.

Complete application form example

Below you’ll find a sample application form to use as test data for your form renderer.

This example combines all block types and all question types. It includes nested sections, required and optional questions, HTML links, EEO content, and unified keys on questions and options.

Show the complete JSON

Check these behaviors:

• Initial state (no answers): hide all conditional blocks and empty sections.
• Select Remote as the working location: show the Remote Work section.
• Try both computer answers: show the matching conditional equipment questions.
• Deselect Remote as the working location: hide its sections and clear their answers.
• Select Hybrid: show its information block and heading.
• Languages: show Language Experience only for English or German.
• Gender: show the follow-up only for Prefer to self-describe.

[
  {
    "block_type": "INFORMATION",
    "category": null,
    "text": "Please complete the questions below. Read our <a href=\"https://example.com/privacy\">privacy policy</a> for details about how we use your information.",
    "display_when": null
  },
  {
    "block_type": "SECTION",
    "label": "Personal Information",
    "children": [
      {
        "block_type": "SECTION",
        "label": "Name",
        "children": [
          {
            "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
          },
          {
            "block_type": "QUESTION",
            "question_id": "Hjsapofs69cx2iAu6MtTfhoh",
            "label": "Last name",
            "description": null,
            "required": true,
            "category": null,
            "question_type": "TEXT",
            "unified_key": "LAST_NAME",
            "options": null,
            "display_when": null
          }
        ]
      },
      {
        "block_type": "SECTION",
        "label": "Documents",
        "children": [
          {
            "block_type": "QUESTION",
            "question_id": "3dT5df2PhyVp7Rze76S5NqrW",
            "label": "Resume",
            "description": "Upload your resume as a PDF.",
            "required": true,
            "category": null,
            "question_type": "FILE",
            "unified_key": "RESUME",
            "options": null,
            "display_when": null
          }
        ]
      }
    ]
  },
  {
    "block_type": "QUESTION",
    "question_id": "9wLtF5cPnKvX2mRj7YqZs4hB",
    "label": "When can you start?",
    "description": null,
    "required": false,
    "category": null,
    "question_type": "DATE",
    "unified_key": "EXPECTED_START_DATE",
    "options": null,
    "display_when": null
  },
  {
    "block_type": "QUESTION",
    "question_id": "3fJx2VbNMwPq8RzKtY5dHnLu",
    "label": "How many years of professional experience do you have?",
    "description": "Enter 0 if this would be your first role.",
    "required": true,
    "category": null,
    "question_type": "NUMBER",
    "unified_key": null,
    "options": null,
    "display_when": null
  },
  {
    "block_type": "SECTION",
    "label": "Work Preferences",
    "children": [
      {
        "block_type": "QUESTION",
        "question_id": "EKaumKPGjeA97cb8ystMmkCe",
        "label": "What is your desired working location?",
        "description": "Select your preferred work arrangement.",
        "required": true,
        "category": null,
        "question_type": "SINGLE_SELECT",
        "unified_key": null,
        "options": [
          {
            "id": "BsnL4pAhNQc26uSc4JopTP3P",
            "label": "Remote",
            "unified_key": null
          },
          {
            "id": "8T4fcKgzLxbKFUo4saXaoMTG",
            "label": "On-site",
            "unified_key": null
          },
          {
            "id": "2cJDK3dq4WNjovohSG7dSpfd",
            "label": "Hybrid",
            "unified_key": null
          }
        ],
        "display_when": null
      },
      {
        "block_type": "SECTION",
        "label": "Remote Work",
        "children": [
          {
            "block_type": "INFORMATION",
            "category": null,
            "text": "Remote applicants should include their timezone so we can schedule interviews.",
            "display_when": {
              "question_id": "EKaumKPGjeA97cb8ystMmkCe",
              "answer_equals": "BsnL4pAhNQc26uSc4JopTP3P"
            }
          },
          {
            "block_type": "QUESTION",
            "question_id": "2H26BKTbDn2ygN2GfEcCsUP8",
            "label": "What timezone are you in?",
            "description": null,
            "required": true,
            "category": null,
            "question_type": "TEXT",
            "unified_key": null,
            "options": null,
            "display_when": {
              "question_id": "EKaumKPGjeA97cb8ystMmkCe",
              "answer_equals": "BsnL4pAhNQc26uSc4JopTP3P"
            }
          },
          {
            "block_type": "QUESTION",
            "question_id": "AdM1EuwBKE4pz94SSRHMgmba",
            "label": "Do you have a computer you can use for work?",
            "description": null,
            "required": false,
            "category": null,
            "question_type": "BOOLEAN",
            "unified_key": null,
            "options": null,
            "display_when": {
              "question_id": "EKaumKPGjeA97cb8ystMmkCe",
              "answer_equals": "BsnL4pAhNQc26uSc4JopTP3P"
            }
          },
          {
            "block_type": "SECTION",
            "label": "Equipment",
            "children": [
              {
                "block_type": "INFORMATION",
                "category": null,
                "text": "You can use your own computer.",
                "display_when": {
                  "question_id": "AdM1EuwBKE4pz94SSRHMgmba",
                  "answer_equals": true
                }
              },
              {
                "block_type": "QUESTION",
                "question_id": "FuVZvF26NueKcN46o5euHeGx",
                "label": "Tell us about your computer",
                "description": null,
                "required": false,
                "category": null,
                "question_type": "TEXT",
                "unified_key": null,
                "options": null,
                "display_when": {
                  "question_id": "AdM1EuwBKE4pz94SSRHMgmba",
                  "answer_equals": true
                }
              },
              {
                "block_type": "INFORMATION",
                "category": null,
                "text": "We can send you a computer.",
                "display_when": {
                  "question_id": "AdM1EuwBKE4pz94SSRHMgmba",
                  "answer_equals": false
                }
              },
              {
                "block_type": "QUESTION",
                "question_id": "DBgqkooeYSxVG5UzqZbm1mUH",
                "label": "Where should we send your computer?",
                "description": null,
                "required": true,
                "category": null,
                "question_type": "TEXT",
                "unified_key": null,
                "options": null,
                "display_when": {
                  "question_id": "AdM1EuwBKE4pz94SSRHMgmba",
                  "answer_equals": false
                }
              }
            ]
          }
        ]
      },
      {
        "block_type": "SECTION",
        "label": "Office Work",
        "children": [
          {
            "block_type": "QUESTION",
            "question_id": "3JXLEnMr1GhaR9gYoiE9xE8Y",
            "label": "Which office would you prefer?",
            "description": null,
            "required": true,
            "category": null,
            "question_type": "SINGLE_SELECT",
            "unified_key": null,
            "options": [
              {
                "id": "EHCqUb5E6xzfjnfHT2LEgmM7",
                "label": "Berlin",
                "unified_key": null
              },
              {
                "id": "5RbHT73StFM5tHdF3aVr4do1",
                "label": "London",
                "unified_key": null
              }
            ],
            "display_when": {
              "question_id": "EKaumKPGjeA97cb8ystMmkCe",
              "answer_equals": "8T4fcKgzLxbKFUo4saXaoMTG"
            }
          }
        ]
      },
      {
        "block_type": "SECTION",
        "label": "Hybrid Work",
        "children": [
          {
            "block_type": "INFORMATION",
            "category": null,
            "text": "Hybrid roles include both office and remote work. We will discuss the schedule during your interview.",
            "display_when": {
              "question_id": "EKaumKPGjeA97cb8ystMmkCe",
              "answer_equals": "2cJDK3dq4WNjovohSG7dSpfd"
            }
          }
        ]
      }
    ]
  },
  {
    "block_type": "QUESTION",
    "question_id": "7VMWn39TqeHRT3nW12AXMD9V",
    "label": "Which languages do you speak?",
    "description": null,
    "required": true,
    "category": null,
    "question_type": "MULTI_SELECT",
    "unified_key": null,
    "options": [
      {
        "id": "4KcNp8RvXw2mYqTjF5sHbL7d",
        "label": "English",
        "unified_key": null
      },
      {
        "id": "6QhZt3WkPn9cVxRm2JfDy8sB",
        "label": "German",
        "unified_key": null
      },
      {
        "id": "2TmXr7BpKv4wQzNh9LcFs6jY",
        "label": "French",
        "unified_key": null
      }
    ],
    "display_when": null
  },
  {
    "block_type": "SECTION",
    "label": "Language Experience",
    "children": [
      {
        "block_type": "INFORMATION",
        "category": null,
        "text": "This role involves working with English- and German-speaking customers.",
        "display_when": {
          "question_id": "7VMWn39TqeHRT3nW12AXMD9V",
          "answer_equals": [
            "4KcNp8RvXw2mYqTjF5sHbL7d",
            "6QhZt3WkPn9cVxRm2JfDy8sB"
          ]
        }
      },
      {
        "block_type": "QUESTION",
        "question_id": "GnB5PQh7h3va7LEApWZ2qiMt",
        "label": "Describe your experience using English or German at work",
        "description": null,
        "required": false,
        "category": null,
        "question_type": "TEXT",
        "unified_key": null,
        "options": null,
        "display_when": {
          "question_id": "7VMWn39TqeHRT3nW12AXMD9V",
          "answer_equals": [
            "4KcNp8RvXw2mYqTjF5sHbL7d",
            "6QhZt3WkPn9cVxRm2JfDy8sB"
          ]
        }
      }
    ]
  },
  {
    "block_type": "SECTION",
    "label": "Equal Employment Opportunity",
    "children": [
      {
        "block_type": "INFORMATION",
        "category": "EEO",
        "text": "The following questions are voluntary.",
        "display_when": null
      },
      {
        "block_type": "QUESTION",
        "question_id": "4niZQuc6rfGmAnMfG1gva1Ue",
        "label": "Gender",
        "description": null,
        "required": false,
        "category": "EEO",
        "question_type": "SINGLE_SELECT",
        "unified_key": "GENDER",
        "options": [
          {
            "id": "ASN2C77WyJxBH2NzpiukDu3H",
            "label": "Man",
            "unified_key": "MALE"
          },
          {
            "id": "GDSBasEhkdKzu9ZxpkpYaX5h",
            "label": "Woman",
            "unified_key": "FEMALE"
          },
          {
            "id": "3iVt2sfbpw8BjCikCWJAVHgJ",
            "label": "Non-binary",
            "unified_key": "NON_BINARY"
          },
          {
            "id": "3irQtkRAj1gCmwB3uWvYAQPi",
            "label": "Prefer not to say",
            "unified_key": "NOT_SPECIFIED"
          },
          {
            "id": "Wq7tKp2ZxMnR4bVcL9sDyH3e",
            "label": "Prefer to self-describe",
            "unified_key": null
          }
        ],
        "display_when": null
      },
      {
        "block_type": "QUESTION",
        "question_id": "35V1AegJ3qtxUEnpSDJ62e78",
        "label": "Please describe your gender, if you wish",
        "description": null,
        "required": false,
        "category": "EEO",
        "question_type": "TEXT",
        "unified_key": null,
        "options": null,
        "display_when": {
          "question_id": "4niZQuc6rfGmAnMfG1gva1Ue",
          "answer_equals": "Wq7tKp2ZxMnR4bVcL9sDyH3e"
        }
      }
    ]
  },
  {
    "block_type": "QUESTION",
    "question_id": "Xp2mKvR8sTcW4nQhJ6fBdY3z",
    "label": "I agree to the <a href=\"https://example.com/privacy\">privacy policy</a>",
    "description": null,
    "required": true,
    "category": null,
    "question_type": "BOOLEAN",
    "unified_key": "TERMS_AND_CONDITIONS",
    "options": null,
    "display_when": null
  }
]