> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# create_record

> Add one record to a data table — a deal, an account, any row. One record per call, meant for adjustments.

Add one record to a data table — a deal, an account, any row.

Call get\_data\_table first: its `fields` give the ids to write, the type each
value must take, the labels a picklist accepts, and `editable`, false for the
fields no write can set (lookups and links to another table). Its
`adjustment_reasons` say whether a `reason` is required here.

One record per call, meant for adjustments: loading many records is an import,
done from the Qobra web app. Statements are not recalculated by this call, just
as when a record is added in the web app — they pick it up at the next automatic
recalculation, or when someone refreshes them.

Requires write permission on data tables. Available only where the Qobra write
tools beta is enabled. Every write is recorded in the audit trail as the `Qobra
MCP` agent.

## Parameters

<Accordion title="Body" defaultOpen>
  <ParamField body="data_table_id" type="string" required>
    Id of the data table to add the record to — the id list\_data\_tables
    returns. Local and integration tables are both accepted.
  </ParamField>

  <ParamField body="values" type="object[]" required>
    The record's cells, one per field to set. A field left out takes its
    default; the name field defaults to 'New record'.

    <Expandable title="object properties">
      <ParamField body="field_id" type="string" required>
        Id of the column — a field id get\_data\_table returns. Only a field
        whose `editable` is true can be written.
      </ParamField>

      <ParamField body="value" type="string | number | boolean | string[]">
        The cell's new value, in the shape the read tools serve it: a number
        for amount / float / percentage (a percentage is the ratio, 0.8 for
        80%), true/false for bool, an ISO date for date, text for string, one
        option label for picklist, a list of option labels for
        multipicklist, and a user id for user. null empties the cell.
      </ParamField>

      <ParamField body="currency" type="string">
        Currency code of an amount (EUR, USD…). Omit it to keep the cell's
        currency; ignored on every other type.
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="reason" type="string">
    Why the record is added — one of the table's `adjustment_reasons` from
    get\_data\_table. Required only when that list is not null; omit it
    otherwise.
  </ParamField>

  <ParamField body="comment" type="string">
    Optional note kept in the record's history.
  </ParamField>
</Accordion>

The call is refused, with a message naming the problem, when a `field_id` is
unknown or listed twice, when a field is a lookup or a link to another table,
when a value does not match its field's type or picklist options, or when the
table requires a `reason` and none from its `adjustment_reasons` was passed.

## Example

```json theme={null}
{
  "data_table_id": "665f1c2e8a4b3d0012a7e9f1",
  "values": [
    { "field_id": "665f1c2e8a4b3d0012a7e9f2", "value": "Acme renewal" },
    { "field_id": "665f1c2e8a4b3d0012a7e9f3", "value": 12000, "currency": "EUR" },
    { "field_id": "665f1c2e8a4b3d0012a7e9f4", "value": "2026-09-15" },
    { "field_id": "665f1c2e8a4b3d0012a7e9f5", "value": "Closed won" }
  ],
  "reason": "Missing deal",
  "comment": "Signed offline, not yet in the CRM."
}
```

## Response

<Accordion title="Body" defaultOpen>
  <ResponseField name="data_table" type="object">
    The table the record was created in, whose `fields` header names the
    record's values in order — the same row list\_data\_tables returns. See
    [`list_data_tables`](/mcp_documentation/tools/list_data_tables) for the
    full field breakdown.
  </ResponseField>

  <ResponseField name="record" type="object">
    The record as it now exists — the same row list\_data\_table\_records
    returns, so the id can be reused straight away. Its `values` are read in
    the order of `data_table.fields`. See
    [`list_data_table_records`](/mcp_documentation/tools/list_data_table_records)
    for the full field breakdown.
  </ResponseField>
</Accordion>