# insertmicroapprow

### description

Add a new row to a Datatable (historically called a Microapp).

Use [Row Metadata and Relationships](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/row-metadata-and-relationships) for the canonical definition of shared row semantics such as `embeddingRowID`, linked-table structures, and metadata fields returned after creation.

### 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.
* `rowData` - required. Name/value pairs for business fields. Keys are matched against field labels and are case-sensitive.
* `embeddingRowID` - optional parent row ID when inserting a child row in a sub-table relationship.
* `userID` - optional creator override. If omitted, the authenticated user becomes the row creator.
* `viewers` - optional viewers array for the inserted row.
* `teamViewers` - optional team-viewers array for the inserted row.
* `ignoreActionRules` - optional boolean. When `true`, insert action rules are skipped.

Unknown keys inside `rowData` are ignored. System metadata such as `_id`, `submitted`, `clientSubmitted`, `parentResourceID`, and `topLevelParentID` is not writable through `rowData`.

#### resource

```json
{
  "microAppID": "<insert datatable id here>",
  "rowData": {
    "ExampleFieldName": "ExampleValue"
  },
  "embeddingRowID": "<optional parent row id>",
  "userID": "<optional creator user id>",
  "viewers": [
    "<optional user id>"
  ],
  "teamViewers": [
    "<optional team id>"
  ],
  "ignoreActionRules": true
}
```

### response

Returns the status of the request and, on success, the new `rowID`.

### example

```
POST /api/insertmicroapprow
X-Auth-Token: <the authtoken you got back after authentication>
X-User-Id: <the userid you got back after authentication>

{
	"microAppID":"contacts-datatable-id",
	"rowData":{
		"Name":"Fred"
	}
}
```

You should get back:

```
{
    "status": "success",
    "rowID": "9860757f2bf858439ed9cc3e"
}
```

### Child Row Example Using `embeddingRowID`

When inserting into a child Datatable, include `embeddingRowID` to link the new row to its parent row:

```
POST /api/insertmicroapprow
X-Auth-Token: <the authtoken you got back after authentication>
X-User-Id: <the userid you got back after authentication>

{
    "microAppID": "invoice-lines-datatable-id",
    "embeddingRowID": "invoice-row-id",
    "rowData": {
        "product": "Widget",
        "quantity": 2,
        "price": 19.95
    }
}
```

Use `embeddingRowID` for parent-child sub-table relationships. Do not confuse it with linked-table `crossAppRowID`, which points to a referenced row in another Datatable.

### Optional Metadata Example

This example shows the optional top-level parameters that the endpoint accepts:

```http
POST /api/insertmicroapprow
X-Auth-Token: <the authtoken you got back after authentication>
X-User-Id: <the userid you got back after authentication>

{
  "microAppID": "contacts-datatable-id",
  "embeddingRowID": "parent-row-id",
  "userID": "creator-user-id",
  "viewers": ["user-a", "user-b"],
  "teamViewers": ["team-1"],
  "ignoreActionRules": true,
  "rowData": {
    "Name": "Metadata Example"
  }
}
```

### Linked Table Field Example

When inserting a row with a linked table (cross app) field, you need to provide both the `crossAppRowID` (the ID of the row you're linking to) and a `value` object containing the display information.

```
POST /api/insertmicroapprow
X-Auth-Token: <the authtoken you got back after authentication>
X-User-Id: <the userid you got back after authentication>

{
    "microAppID": "your-microapp-id",
    "rowData": {
        "organizationName": "Acme Corp",
        "marketplaceListing": {
            "crossAppRowID": "marketplace-listing-row-id",
            "value": {
                "label": "listingName",
                "value": "AI Customer Support Solution"
            }
        },
        "assignedUser": {
            "crossAppRowID": "user-row-id", 
            "value": {
                "label": "name",
                "value": "John Smith"
            }
        }
    }
}
```

**Key Points:**

* `crossAppRowID`: The `_id` of the row in the linked table
* `value.label`: The field name from the linked table to display
* `value.value`: The actual display value from that field

You should get back:

```
{
    "status": "success",
    "rowID": "newly-created-row-id"
}
```

### what you can and can't change

* You can populate Datatable fields by label in `rowData`.
* You can set row creator with top-level `userID`.
* You can set row-level `viewers` and `teamViewers` with top-level properties.
* You can assign a parent row with top-level `embeddingRowID`.
* You cannot use `rowData` to set arbitrary system metadata like `_id`, `submitted`, `clientSubmitted`, `parentResourceID`, or `topLevelParentID`.
* If the Datatable has Viewers or Team Viewers fields configured to inherit from the parent row, those values may be inherited from the `embeddingRowID` row rather than taken from omitted row content.

### See Also

* [Row Metadata and Relationships](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/row-metadata-and-relationships) - Canonical metadata, `embeddingRowID`, and linked-table semantics
* [insertmicroapprows](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/insertmicroapprows) - Batch insert version of this operation
* [Common API Examples](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/common-api-examples#create-a-new-contact) - See this operation in all three API formats
* [microappdata/row](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microappdata-row#linkedtable-crossapp-row-field-example) - Understanding linked table field structure
* [updatemicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/updatemicroapprow#linked-table-field-update-example) - Updating linked table fields

***