# Prefill Embedded Online Forms

The YouTrack Form API lets you prefill fields in a Helpdesk online form that is embedded in a website. For example, when a customer opens a support form from a product page, you can use the product name from the page to fill the corresponding field in the form.

Prefilling fields reduces the amount of information that customers need to enter manually. Customers can review and change the suggested values before they submit the form.

This page explains how to connect to an embedded form, identify its fields, and set their values with JavaScript. For information about creating and configuring forms, see [Online Forms](helpdesk-online-forms.html). For a general introduction to Helpdesk projects, see [Helpdesk](helpdesk.html).

## Before You Start

The Form API works with the JavaScript embed code generated by YouTrack.

Working with the Form API requires basic knowledge of JavaScript. The code that connects to the form and sets field values runs on the web page where the form is embedded.

Before you use it:

* Create and configure the online form that you want to use. For details about the elements that you can add, see [Building Blocks](helpdesk-online-forms.html#form-building-blocks) and [Available Fields](helpdesk-online-forms.html#available-form-fields).

* [Embed the form in your website](helpdesk-online-forms.html#embed-an-online-form-in-an-external-website) and keep the generated embed code available.

* Decide which values the surrounding page can provide and which form fields should receive them.

> **Note:**
> The Form API requires adding JavaScript to the website where the form is embedded. If you manage the Helpdesk project but not the website, share the form ID and the sample script on this page with the person responsible for the website.

> **Tip:**
> If you only need to prefill the Summary or Description field in a direct link to a form, you can use [URL parameters](helpdesk-online-forms.html#embed-form-values-by-url-parameters) instead of the Form API.

After these preparations are complete, prefilling an embedded form involves the following:

1. [Connect to the embedded form](#establish-connection) using its form ID.

2. [Identify the form fields](#block-references) by their block IDs or titles.

3. Use the [Form API methods](#methods) to inspect field values and set the values you want to prefill.

The sample script in the next section shows the complete flow. The sections that follow explain each part in detail.

## Sample Script

The sample below demonstrates how to prefill an embedded form with JavaScript. It connects to a form, sets values for the Email, Summary, and Description fields, and sets values for custom fields named Due date and Priority. The form ID, field names, and values in the code are examples.

```JAVASCRIPT
<script>
// Connect to the embedded form.
YTFeedbackForm.getClientJSApi('680e7600-000f-4029-bfe9-ddf479c73ef7').then(async form => {

    // Get the blocks that are available through the Form API.
    const blocks = form.getBlocks();

    // Set values for the predefined fields.
    form.setBlockValue('email', 'jane.doe@example.com');
    form.setBlockValue('summary', 'Assistance Required');
    form.setBlockValue('description', 'I need assistance, please get back to me.');

    // Set the current date in a custom field titled Due date.
    form.setBlockValue('Due date', new Date());

    // Find the custom field titled Priority.
    const priorityBlock = blocks.find(block => block.title === 'Priority');

    if (priorityBlock) {
        // Load the available values without applying a text filter.
        const priorityValues = await form.getBlockValues(priorityBlock.id, '');

        if (priorityValues?.length) {
            // Select the first available value.
            form.setBlockValue(priorityBlock.id, priorityValues[0]);
        }
    }
});
</script>
```

The example checks that the Priority block and at least one selectable value are available before it sets the field. This prevents the custom-field part of the script from failing when the form configuration is different.

## Connect to the Embedded Form

Each embedded form has a unique form ID. You can find this ID in the [embed code generated by YouTrack](helpdesk-online-forms.html#embed-an-online-form-in-an-external-website).

Popup Mode:

![The form ID in the embed code viewed in Popup mode.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/form-id-popup-mode.png)

Inline Mode:

![The form ID in the embed code viewed in Inline mode.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/form-id-inline-mode.png)

Pass the form ID to the `getClientJSApi` method to establish a connection:

```JAVASCRIPT
YTFeedbackForm.getClientJSApi('680e7600-000f-4029-bfe9-ddf479c73ef7').then(async form => {
    // Your code goes here.
});
```

The method returns a promise that resolves when the form is ready. The `form` parameter inside the callback gives you access to the Form API methods described below. Replace the example ID with the ID from your embed code.

> **Note:**
> Make sure the ID matches a form embedded on the same page. If no embedded form uses this ID, the connection is not established and the code inside the callback doesn't run.

## Refer to Form Fields

The Form API calls the input fields in a form blocks. Methods that read or update a block use the `blockReference` parameter to identify it.

You can use either of the following values as a block reference:

* The block ID returned by the `getBlocks` method.

* The block title shown in the form. Title matching is not case-sensitive.

If a title can change or more than one block has the same title, use the block ID to avoid ambiguity.

### Predefined Fields

You can refer to the following predefined fields by name without first looking up their block IDs:

* `email`

* `summary`

* `description`

The following statements set values for these fields:

```JAVASCRIPT
// Setting the email value to jane.doe@example.com.
form.setBlockValue('email', 'jane.doe@example.com');

// Setting the summary.
form.setBlockValue('summary', 'Assistance Required');

// Setting the description.
form.setBlockValue('description', 'I need assistance, please get back to me.');
```

## Form API Methods

In the return types below, `Value` represents a form value object. Its properties depend on the field type. For fields with a list of selectable values, use the objects returned by `getBlockValues` when you call `setBlockValue`.

### getBlocks

Returns the blocks in the form that are available through the Form API. Use this method to inspect block IDs, titles, types, and default values.

Syntax: `getBlocks()`

#### Returned Value

| Type | Description |
| --- | --- |
| `Array<Block>` | An array of blocks available through the Form API. |

#### Block Object

| Property | Type | Description |
| --- | --- | --- |
| `id` | `String` | The block ID. |
| `type` | `String` | The block type. |
| `title` | `String` | The block title. For a block without a custom title, this property contains the block type. |
| `hasValues` | `Boolean` | Indicates whether the block provides a list of selectable values. |
| `defaultValue` | `Value \| Array<Value>` | The default value configured for the block. |

### getBlockValue

Returns the current value of a block. Use this method when the value for one block depends on information entered in another block.

Syntax: `getBlockValue(blockReference)`

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `blockReference` | `String` | Required. The block ID or title. |

#### Returned Value

| Type | Description |
| --- | --- |
| `Value \| Array<Value>` | The current value or values of the block. |

### getBlockValues

Loads the values that can be selected for a block, such as an enumerated custom field. You can filter the returned values and skip values that were returned by an earlier request.

Syntax: `getBlockValues(blockReference, query, skip)`

> **Note:**
> Call `getBlockValues` with the `await` operator. For details about this JavaScript operator, see the [MDN reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await).

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `blockReference` | `String` | Required. The block ID or title. |
| `query` | `String` | Required. The text used to filter the available values. Pass an empty string to return values without a text filter. |
| `skip` | `Number` | The number of matching values to skip. This parameter is optional. The default value is `0`. |

#### Returned Value

| Type | Description |
| --- | --- |
| `Promise<Array<Value>>` | A promise that resolves to an array of available values. |

### setBlockValue

Sets the value of a block. If no block matches the supplied reference, the method leaves the form unchanged.

Syntax: `setBlockValue(blockReference, value)`

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `blockReference` | `String` | Required. The block ID or title. |
| `value` | `String \| Date \| Value \| Array<Value>` | Required. The value to set.       * For text, number, and period fields, pass a string.    * For date and date-and-time fields, pass a JavaScript `Date` object.    * For a field with selectable values, pass a value object returned by `getBlockValues`. For a multi-value field, pass an array of these objects.   |