Docs

API Library

API Authentication / Overview

All API endpoints require that a valid API key be in the Authorization header. API keys are set up in Settings > API Keys.

The header on all API calls should be as follows:

Authorization: <API Key>

APIs use appropriate verbs. Using the wrong verb results in an error. All errors use appropriate response codes. Response code 200 means the request was successful.

The production API server is: https://api.essembi.ai

Endpoints returning Result data return a maximum of 10,000 cells (rows × columns). Use filtering to return a more specific result set.

Suggested first call: GET /Security/Authenticate to verify the API key before calling data endpoints.

Ways to Create and Update Records

  • Table record endpoints — Create or edit one record at a time with POST /Tables/{tableId}/Records/Create and PATCH /Tables/{tableId}/Records/{recordId}/Edit.
  • Data Import API — Run a configured Data Import with JSON or an uploaded Excel/JSON/delimited file to insert and update many records in one call.
  • Essembi FTP + Data Import — Upload files to the Essembi-provided FTP site; Essembi pulls the files into a Data Import for insert/update processing. See Data Imports.

Endpoints

Verb Name Url Parameters Return
GET Authenticate
Validates that the API key is active and returns the associated app id.		 /Security/Authenticate { message, appId }
GET List Tables
Used to get all tables in an app. Table IDs are used in other endpoints.		 /Tables/List Table[]
GET List Table Fields
Used to get all fields in a table. Field IDs (or names) are used when creating, updating, and filtering.		 /Tables/{tableId}/Fields tableId (Url) Field[]
GET Get Table Records
Used to get filtered table data. Record IDs are used when creating foreign key relationships.		 /Tables/{tableId}/Records tableId (Url), ResultsRequest (body, optional) Result
POST Create Table Record
Used to create a record, such as a ticket.		 /Tables/{tableId}/Records/Create tableId (Url), RecordValues (body) RecordUpdate
PATCH Edit Table Record
Used to update an existing record.		 /Tables/{tableId}/Records/{recordId}/Edit tableId (Url), recordId (Url), RecordValues (body) RecordUpdate
PATCH Activate Table Record
Used to activate an inactive/archived record.		 /Tables/{tableId}/Records/{recordId}/Activate tableId (Url), recordId (Url) RecordUpdate
PATCH Inactivate Table Record
Used to inactivate/archive an active record.		 /Tables/{tableId}/Records/{recordId}/Inactivate tableId (Url), recordId (Url) RecordUpdate
GET List Data Models
Used to get all data models in an app. Data model IDs are used when getting data model results.		 /DataModels/List DataModel[]
GET Get Data Model Results
Used to get filtered results from a data model configured in Settings > Data Models.		 /DataModels/{dataModelId}/Results dataModelId (Url), ResultsRequest (body, optional) Result
POST Execute Data Import
Runs a configured Data Import (Settings > Data Imports) to insert and/or update records from JSON or an uploaded file. Supports JSON body and Excel import files (also JSON/delimited files when the Data Import File Type requires them).		 /Integrations/DataImport/{dataImportId} dataImportId (Url), optional query type=json|excel, JSON body or multipart file DataImportResult

Execute Data Import via API

Use this endpoint to run the same Data Import configurations available in the app. The Data Import’s Transform & Load Script controls insert vs update behavior.

Endpoint: POST https://api.essembi.ai/Integrations/DataImport/{dataImportId}

Optional query parameter:

  • type=json — Require a JSON body
  • type=excel — Require an uploaded file
  • Omit type — Use JSON body when Content-Type is application/json; otherwise use the uploaded file

Option A — JSON body

Header: Content-Type: application/json

Accepted JSON shapes:

  • columns (or Columns) as a string array, plus data (or Data) as an array of row arrays
  • columns plus data as an array of objects keyed by column name
  • schema.columns as objects with name, plus data 
{
  "columns": ["Part", "Standard Cost"],
  "data": [
    ["ABC-100", 12.5],
    ["ABC-200", 18.0]
  ]
}

{
  "columns": ["Part", "Standard Cost"],
  "data": [
    { "Part": "ABC-100", "Standard Cost": 12.5 },
    { "Part": "ABC-200", "Standard Cost": 18.0 }
  ]
}

Option B — File upload (Excel / JSON / delimited)

Send multipart/form-data with a file field named file (or the first form file). The file extension must match the Data Import File Type:

  • Excel Data Import → .xlsx
  • JSON Data Import → .json
  • Delimited Data Import → delimited text per the import’s delimiter settings

Success response

{
  "success": true,
  "message": "...",
  "totalRecordsLoaded": 25
}

Validation / transform error response

Returns HTTP 400 with messages and optional row/column/table/field details when the transform or load fails.

For FTP-based delivery into the same Data Import configurations, see Data Imports.

Data Transfer Objects

Table

A table, such as Ticket, that has been set up in Settings > Tables.

  • id (int)
  • name (string)
  • active (boolean)

Field

A field in a table, such as Ticket Summary.

  • id (int)
  • tableId (int)
  • name (string)
  • active (boolean)
  • required (boolean)
  • type (string)
  • nullable (boolean, only for nullable field types)
  • alphaChannel (boolean, only for color fields)
  • recordColor (boolean, only for color fields)
  • recordDueDate (boolean, only for date fields)
  • integerDigits (int, only for decimal fields)
  • decimalDigits (int, only for decimal fields)
  • recordSort (boolean, only for integer fields)
  • foreignTableId (int, only for record reference fields)
  • recordName (boolean, only for short text fields)
  • recordIcon (boolean, only for short text fields)
  • recordAssignedTo (boolean, only for user fields)
  • multiSelect (boolean, only for drop down fields)
  • values (DropDownRow[], only for drop down fields)
  • columns (string[], only for drop down fields)

DropDownRow

A value (row) in a drop down field.

  • id (int)
  • values (string[])

Result

The results of querying a data model or specific table.

  • fields (ResultField[])
  • rows (ResultRow[])

ResultField

A field (column) included in query results.

  • fieldId (int)
  • dataModelTableId (int, only returned from DataModels endpoints, not from Tables endpoints)

ResultRow

A result values row from querying a data model or specific table.

  • id (int)
  • active (int)
  • values (any[])

RecordUpdate

Information about a record that has been created or updated.

  • tableId (int)
  • recordId (int)

DataImportResult

Result of executing a Data Import via API.

  • success (boolean)
  • message (string)
  • totalRecordsLoaded (int)

DataModel

A data model configured in Settings > Data Models.

  • id (int)
  • name (string)
  • active (bool)
  • dataModelTables (DataModelTable[])

DataModelTable

A reference to a table included in a data model. Because a table can appear more than once, dataModelTableId and tableId are not the same.

  • id (int)
  • tableId (int)
  • tableName (string)
  • alias (string)
  • primary (boolean)

ResultsRequest

Filters for querying data from a table or data model.

  • matchType (string: any, all, or none — how filters combine, similar to the in-app filter form. Default is all)
  • activeType (string: active, inactive, all — which records to return. Applies to the primary table in data model results. Default is active)
  • filters (Filter[])

Filter

A filter inside a request.

  • dataModelTableId (int, only used when filtering data model results, not table record results)
  • fieldId (int)
  • operator (string — see Filter Operators below)
  • value (any)
  • value2 (any — required for range operators such as Between)

Filter Operators

Pass the enum name as the operator string. Supported operators:

  • Empty, NotEmpty
  • Equal, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual
  • Between, Overlaps, DayRange, WeekRange, MonthRange, YearRange
  • Contains, StartsWith, EndsWith, ContainedIn
  • InTheLastYear, InTheLastQuarter, InTheLastMonth, InTheLastWeek
  • InTheNextYear, InTheNextQuarter, InTheNextMonth, InTheNextWeek
  • LastYear, LastQuarter, LastMonth, LastWeek
  • NextYear, NextQuarter, NextMonth, NextWeek
  • ThisYear, ThisQuarter, ThisMonth, ThisWeek
  • Yesterday, Today, Tomorrow
  • Now, InTheLastHour, InTheLast4Hours, InTheLast8Hours, InTheLast12Hours, InTheLast24Hours
  • InTheNextHour, InTheNext4Hours, InTheNext8Hours, InTheNext12Hours, InTheNext24Hours
  • AssignedToTeam

Not supported via API: AssignedToMe, AssignedToMyTeam (session-user specific).

RecordValues

Values to assign when creating or updating a record.

  • values (object — map of field id or field name to field value)
{
  "values": {
    "123": "New ticket summary",
    "Status": "Open"
  }
}
Back to help
On this page
    Essembi Help Guide