insertmicroapprows

description

Insert multiple rows into a Datatable (historically called a Microapp) in a single request.

Use this endpoint when you want batch creation semantics and can supply an array of row payloads. For the canonical explanation of row metadata, linked-table structures, and parent-child semantics, see Row Metadata and Relationships.

parameters

The X-Auth-Token and X-User-Id are derived from the values authToken and userId returned from the login endpoint and are used in the HTTP header.

Accepted top-level request properties:

microAppID - required. Datatable ID to insert into.
rows - required. Non-empty array of row objects. Maximum 10,000 rows per request.
embeddingRowID - optional default parent row ID to apply to every row in the batch.
viewers - optional row-level viewers array applied to inserted rows.
userID - optional creator override for inserted rows. If omitted, the authenticated user becomes the row creator.
ignoreActionRules - optional boolean. When true, insert action rules are skipped for the batch.

Each item in rows is a row payload keyed by field label, not a nested { rowData: ... } wrapper. Unknown keys are ignored.

Each row may also include its own embeddingRowID. If present on an individual row, it overrides the top-level embeddingRowID for that row only.

resource

{
  "microAppID": "<datatable id>",
  "embeddingRowID": "<optional default parent row id>",
  "userID": "<optional creator user id>",
  "ignoreActionRules": false,
  "rows": [
    {
      "Name": "Alice Example",
      "Status": "Lead"
    },
    {
      "embeddingRowID": "<different parent row id for this row>",
      "Name": "Bob Example",
      "Status": "Customer"
    }
  ]
}

response

Returns a summary object containing:

inserted - number of rows inserted successfully
rowIDs - IDs of the successfully inserted rows
errors - optional array of per-row failures, each with the original row index and an error message

Batch insert is partial-success capable. One row can fail while others still insert.

example

POST /api/insertmicroapprows
X-Auth-Token: <authToken from /api/login>
X-User-Id: <userId from /api/login>
Content-Type: application/json

{
  "microAppID": "contacts-datatable-id",
  "userID": "creator-user-id",
  "rows": [
    {
      "Name": "Fred",
      "Email": "fred@example.com"
    },
    {
      "Name": "Wilma",
      "Email": "wilma@example.com"
    }
  ]
}

Typical success response:

{
  "status": "success",
  "message": "Inserted 2 row(s)",
  "inserted": 2,
  "rowIDs": [
    "9860757f2bf858439ed9cc3e",
    "9860757f2bf858439ed9cc3f"
  ]
}

what you can and can't change

You can set business fields by label inside each row object.
You can set row creator with top-level userID.
You can set a default parent with top-level embeddingRowID, or override it per row with rows[n].embeddingRowID.
You cannot write arbitrary system metadata through the row object. Fields like _id, submitted, clientSubmitted, parentResourceID, and topLevelParentID are not part of the public batch insert contract.
If the caller cannot add rows to the target Datatable, the whole request fails.