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: Authorization:

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 times 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

GET /Security/Authenticate: Validates that the API key is active and returns the associated app id.
GET /Tables/List: Get all tables in an app. Table IDs are used in other endpoints.
GET /Tables/{tableId}/Fields: Get all fields in a table. Field IDs (or names) are used when creating, updating, and filtering.
GET /Tables/{tableId}/Records: Get filtered table data. Record IDs are used when creating foreign key relationships.
POST /Tables/{tableId}/Records/Create: Create a record, such as a ticket.
PATCH /Tables/{tableId}/Records/{recordId}/Edit: Update an existing record.
PATCH /Tables/{tableId}/Records/{recordId}/Activate: Activate an inactive/archived record.
PATCH /Tables/{tableId}/Records/{recordId}/Inactivate: Inactivate/archive an active record.
GET /DataModels/List: Get all data models in an app. Data model IDs are used when getting data model results.
GET /DataModels/{dataModelId}/Results: Get filtered results from a data model configured in Settings > Data Models.
POST /Integrations/DataImport/{dataImportId}: Runs a configured Data Import (Settings > Data Imports) to insert and/or update records from JSON or an uploaded file.

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 requires a JSON body, type=excel requires an uploaded file, and omitting type uses the JSON body when Content-Type is application/json, otherwise the uploaded file.

Option A: JSON body

Header: Content-Type: application/json. Accepted JSON shapes are 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, or schema.columns as objects with name, plus data. Example:

{
  "columns": ["Part", "Standard Cost"],
  "data": [
    ["ABC-100", 12.5],
    ["ABC-200", 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 requires .xlsx, JSON Data Import requires .json, and Delimited Data Import requires delimited text per the import's delimiter settings.

A success response returns success: true, a message, and totalRecordsLoaded. A validation / transform error 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: id, name, active
Field: id, tableId, name, active, required, type, nullable, plus type-specific flags (alphaChannel and recordColor for color fields, recordDueDate for date fields, integerDigits/decimalDigits for decimal fields, recordSort for integer fields, foreignTableId for record reference fields, recordName/recordIcon for short text fields, recordAssignedTo for user fields, multiSelect/values/columns for drop down fields)
DropDownRow: id, values
Result: fields (ResultField[]), rows (ResultRow[])
ResultField: fieldId, dataModelTableId (only from DataModels endpoints)
ResultRow: id, active, values
RecordUpdate: tableId, recordId
DataImportResult: success, message, totalRecordsLoaded
DataModel: id, name, active, dataModelTables
DataModelTable: id, tableId, tableName, alias, primary (a table can appear more than once, so dataModelTableId and tableId are not the same)
ResultsRequest: matchType (any, all, or none), activeType (active, inactive, or all), filters (Filter[])
Filter: dataModelTableId (only for data model results), fieldId, operator, value, value2 (required for range operators such as Between)

Filter Operators

Pass the enum name as the operator string. Supported operators include Empty, NotEmpty, Equal, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual, Between, Overlaps, DayRange, WeekRange, MonthRange, YearRange, Contains, StartsWith, EndsWith, ContainedIn, InTheLastYear/Quarter/Month/Week, InTheNextYear/Quarter/Month/Week, LastYear/Quarter/Month/Week, NextYear/Quarter/Month/Week, ThisYear/Quarter/Month/Week, Yesterday, Today, Tomorrow, Now, InTheLastHour/4Hours/8Hours/12Hours/24Hours, InTheNextHour/4Hours/8Hours/12Hours/24Hours, and AssignedToTeam. AssignedToMe and AssignedToMyTeam are session-user specific and are not supported via API.

RecordValues

Values to assign when creating or updating a record, as an object mapping field id or field name to field value:

{
  "values": {
    "123": "New ticket summary",
    "Status": "Open"
  }
}