insertmicroapprow

description

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

Use 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

{
  "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:

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