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

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

<Warning>
  Questions and information blocks can also appear at the top level without a
  section.
</Warning>

```json theme={null}
{
  "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](#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.

```json theme={null}
{
  "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.

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

```json Example theme={null}
{
  "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.

```json Example theme={null}
{
  "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.

<AccordionGroup>
  <Accordion title="Text (TEXT)">
    A `TEXT` question accepts a non-empty string.

    ```json Question 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
    }
    ```

    ```json Answer theme={null}
    {
      "question_id": "6VrjehyBk685vubNydiR1hSn",
      "answer": "John"
    }
    ```
  </Accordion>

  <Accordion title="Numbers (NUMBER)">
    A `NUMBER` question accepts a number.

    ```json Question theme={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
    }
    ```

    ```json Answer theme={null}
    {
      "question_id": "3fJx2VbNMwPq8RzKtY5dHnLu",
      "answer": 7
    }
    ```
  </Accordion>

  <Accordion title="Booleans (BOOLEAN)">
    A `BOOLEAN` question accepts `true` or `false`.

    ```json Question theme={null}
    {
      "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
    }
    ```

    ```json Answer theme={null}
    {
      "question_id": "Xp2mKvR8sTcW4nQhJ6fBdY3z",
      "answer": true
    }
    ```

    <Warning>
      Let candidates answer consent questions themselves. Do not pre-fill consent
      answers.
    </Warning>
  </Accordion>

  <Accordion title="Dates (DATE)">
    A `DATE` question accepts an ISO 8601 date string.

    ```json Question theme={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
    }
    ```

    ```json Answer theme={null}
    {
      "question_id": "9wLtF5cPnKvX2mRj7YqZs4hB",
      "answer": "2026-09-01T00:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="Single select (SINGLE_SELECT)">
    A `SINGLE_SELECT` question accepts the `id` of one option from its `options` array.

    ```json Question theme={null}
    {
      "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
    }
    ```

    ```jsonc Answer theme={null}
    {
      "question_id": "EKaumKPGjeA97cb8ystMmkCe",
      // The option ID for "Remote"
      "answer": "BsnL4pAhNQc26uSc4JopTP3P",
    }
    ```
  </Accordion>

  <Accordion title="Multi-select (MULTI_SELECT)">
    A `MULTI_SELECT` question accepts an array of option IDs from its `options` array.

    ```json Question theme={null}
    {
      "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
    }
    ```

    ```jsonc Answer theme={null}
    {
      "question_id": "7VMWn39TqeHRT3nW12AXMD9V",
      // The option IDs for "English" and "German"
      "answer": ["4KcNp8RvXw2mYqTjF5sHbL7d", "6QhZt3WkPn9cVxRm2JfDy8sB"],
    }
    ```
  </Accordion>

  <Accordion title="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.

    ```json Question theme={null}
    {
      "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
    }
    ```

    ```json Answer theme={null}
    {
      "question_id": "3dT5df2PhyVp7Rze76S5NqrW",
      "answer": {
        "name": "john_doe_resume.pdf",
        "content_type": "application/pdf",
        "data": "JVBERi0xLjQK..."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

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

<Tip>
  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.
</Tip>

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

<Accordion title="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**.

  ```json theme={null}
  [
    {
      "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
    }
  ]
  ```
</Accordion>