---
title: "Create database record"
manual: "Reactions"
version: "main"
permalink: "https://docs.typo3.org/permalink/typo3/cms-reactions:create-database-record@main"
source: "Reactions/CreateDatabaseRecord/Index.rst"
rendered: "2026-10-03T08:20:05+00:00"
---

# Create database record {#create-database-record}

A basic reaction shipped with the system extension can be used to create records
triggered and enriched by data from the caller.

## Navigate to the backend module {#navigate-backend-module}

To create a new reaction navigate to the **Administration > Integrations > Reactions** backend
module. If you call it the first time you will see the invitation to create a
new reaction:

![Backend module "Reactions" with no reactions available](../../Images/BackendModuleEmpty.avif)

## Create a new reaction {#create-reaction}

Click on the button **Create new reaction** to add a new reaction.

![Backend form to create a new database record](../../Images/CreateDatabaseRecordConfiguration.avif)

The form provides the following general configuration fields:

-   **Reaction Type**

    Select one of the available reaction types. The system extension comes
    with the **Create database record**.

-   **Name**

    Give the reaction a meaningful name. The name is displayed on the overview
    page of the backend module.

-   **Description**

    You can provide additional information to describe, for example, the purpose
    of this reaction in detail.

-   **Identifier**

    Any reaction record is defined by a unique identifier. It is part of the
    TYPO3 URL when calling this reaction.

-   **Secret**

    The secret is necessary to authorize the reaction from the outside. It can
    be re-created anytime, but will be visible only once (until the record is
    saved). Click on the "dices" button next to the form field to create a
    random secret. Store the secret somewhere safe.

The content of the "Additional configuration" section depends on the concrete
reaction type. For the "Create database record" the following fields are
available:

-   **Table**

    Select one of the tables from the list. The corresponding fields displayed
    below change depending on the selected table. See also
    [Extend list of tables](https://docs.typo3.org/permalink/typo3/cms-reactions:create-database-record-extend-tables-list@main) on how to extend this list.

-   **Storage PID**

    Select the page on which a new record should be stored.

-   **Impersonate User**

    Select the user with the appropriate access rights that is allowed to add a
    record of this type. If in doubt, use the CLI user ("\_cli\_").

-   **Fields**

    The available fields depend on the selected table.

    Next to static field values, placeholders are supported, which can be used
    to dynamically set field values by resolving the incoming data from the
    webhook's payload. The syntax for those values is `${key}`. The key
    can be a simple string or a path to a nested value like
    `${key.nested}`.

    Text, e-mail, number, date, colour, link, checkbox, radio button and
    single-value select fields can be mapped. Relations cannot, and neither can a select
    submitting more than one value, since the map holds one string per field.
    Only the fields you may edit yourself are offered, and the reaction writes
    only those the backend user it impersonates may write.

    Every field renders the control the editing form of the target table would
    show: a calendar for a date, a colour picker for a colour, the link browser
    for a link, the items of a select, except a `text` column, which
    keeps a plain box. Each field is set to one of three things: "Do not set",
    which leaves the field to the default of the target table, "Fixed value",
    taken from the control itself, or "Payload value", a placeholder as
    described above. Every row starts on "Do not set", so a reaction writes
    the fields it was configured to write and no others.

    A field that is not set is left out of the created record entirely, and so
    is one the target table cannot hold the value of: a placeholder the request
    does not carry or answers with nothing, a select or radio value the field
    does not offer, and a checkbox value that is neither one of the wordings
    `true`, `yes` and `on` nor a number the boxes of that
    field can hold. A call that resolves no value for any field creates no
    record and is answered with `400`.

For our example we select the **Page Content** table and populate the
following fields:

![Form with additional configuration for page content](../../Images/CreateDatabaseRecordPageContent.png)

We now save and close the form - our newly created reaction is now visible:

![Backend module with reaction](../../Images/BackendModuleWithRecord.avif)

## Call the reaction manually {#call-reaction}

TYPO3 can now react on this reaction. Clicking on the **Example**
button, the skeleton of a cURL request for use on the command line is showing
up. We can adjust and run it on the console, using our placeholders as payload:

```bash
curl -X 'POST' \
    'https://example.com/typo3/reaction/a5cffc58-b69a-42f6-9866-f93ec1ad9dc5' \
      -d '{"header":"my header","text":"<p>my text</p>"}' \
      -H 'accept: application/json' \
      -H 'x-api-key: d9b230d615ac4ab4f6e0841bd4383fa15f222b6b'
```

When everything was okay and the record was created successfully, we receive a
confirmation:

```json
{"success":true}
```

If something went wrong, this is also visible, for example:

```json
{"success":false,"error":"Invalid secret given"}
```

A record can also be created while single fields of it were not written, for
example because a placeholder was not part of the payload. Those fields are
named in an additional `skippedFields` key, together with the reason they
were left out, and the key is absent when everything was written:

```json
{"success":true,"skippedFields":{"doktype":"placeholderUnresolved"}}
```

Where the target table itself rejected a value, a `warnings` key says so
without naming the field. Those messages are written for the backend log, which
is where they stay, so look them up in **System > Log**.

The content is now available on the configured page:

![The created page content record on the configured page](../../Images/CreateDatabaseRecordContentElement.png)

## Extend list of tables {#create-database-record-extend-tables-list}

By default, only a few tables can be selected for external creation in the
create record reaction. In case you want to allow your own tables to be
available in the reaction's table selection, add the table in a corresponding
[TCA override file](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/HowTo/ExtendingTca/StoringChanges/Index.html#storing-changes-extension-overrides):

**EXT:my_extension/Configuration/TCA/Overrides/sys_reaction.php**

```php
if (\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::isLoaded('reactions')) {
    \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTcaSelectItem(
        'sys_reaction',
        'table_name',
        [
            'label' => 'LLL:EXT:myext/Resources/Private/Language/locallang.xlf:tx_myextension_domain_model_mytable',
            'value' => 'tx_myextension_domain_model_mytable',
            'icon' => 'myextension-tx_myextension_domain_model_mytable-icon',
        ]
    );
}
```

In case your extension depends on EXT:reactions the `isLoaded()` check
might be skipped. Please note that tables which configured
[adminOnly](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/Ctrl/Index.html#ctrl-reference-adminonly) to true are not allowed.