Tables, fields, and records

1 mth ago

Query parameters and common attributes to query records with Ninox API

Tables

When retrieving data for tables using a GET, POST, or DELETE request, the response body lists all available tables as well as table definitions. Each item in a response consists of three properties, which define a table: an id, a name, and fields.

Table ids start with A, B, … AA, AB, etc., and need to be provided to get, update, or delete requests. A table name is a human-friendly name for a given table. Fields are arrays of objects, each describing a column in the table.

Fields

Each field is defined by an id, a name and a field type. Field ids start with A, B, … AA, AB, etc. A field name is a human-friendly name for a given field. For field types, refer to the table below.

Field types

Field Type	JSON Type	Example
text	string	`"Lisa"`
number	number	`13.42`
date	string	`"2021-01-23"`
datetime	string	`"2021-01-23T12:30:00"`
timeinterval	string	`"123:25:16.123"`
time	string	`"12:30:00"`
appointment	string	`"2021-01-23T12:30:00 - 2021-01-23T13:30:00"`
boolean	boolean	`true false`
choice	string	`"blue"`
url	string	`"https://ninox.com"`
email	string	`"support@ninox.com"`
phone	string	`"+1 123456789"`
location	string	`"Monbijouplatz 5, 10178 Berlin, Germany <52.5330804,13.3972939>"`
html	string	`"<h1>Hello</h1>"`

Table and field ids do not change during the lifetime of a database. A table or field id is a handle, also known as an opaque identifier. The id format may be subject to change in future Ninox versions.

Common attributes

Each record has the following common attributes:

Attributes

Attribute	JSON Type	Description	Example
`id`	integer	The record id, starting from 1	`5`
`sequence`	integer	The database change sequence number when the record was last updated	`47`
`createdAt`	string	The UTC timestamp when the record was created Format: `YYYY-MM-DDThh:mm:ss`	`"2021-09-13T18:24:26"`
`createdBy`	string	The id of the user who created the record	`"root"`
`modifiedAt`	string	The UTC timestamp when the record was updated Format: `YYYY-MM-DDThh:mm:ss`	`"2021-09-15T16:04:19"`
`fields`	object	An object of all data fields; the field name is used as the key	`"First name": "Anna"`

Query parameters

The following query parameters control which and how many records are returned when retrieving records using a GET or POST request.

Parameters

Parameter	JSON Type	Description	Default Value	Example
`query`	string	Ninox script to be executed	n/a	`(select Contact).'Email'`
`filters`	string	Stringified JSON containing criteria	n/a	`"A":"support@ninox.com"`
`page`	integer	Result set page	`0`	`12`
`perPage`	integer	Records per page	`100`	`250`
`order`	string	The field name to order the result	n/a	`"First name"`
`desc`	boolean	Order descending	`false`	`true`
`new`	boolean	Show newest records first Cannot be combined with order	`false`	`true`
`updated`	boolean	Show latest updates first Cannot be combined with order	`false`	`true`
`sinceId`	integer	Show only records with a higher id	n/a	`42`
`sinceSq`	integer	Show only records that are created or updated after the specified database change sequence number	n/a	`1567`
`ids`	boolean	Formats the records, either as field id value or as field name value	n/a	`true` `false`
`choiceStyle`	string	Format the choice field in a record, either as an option id or as a caption of a selected option	ids	ids names

When filtering records, encode the path parameter using the encodeURIComponent()function in JavaScript.

Example

Before encoding, a JSON string containing the following
(select Contact).'Email'
after URI encoding becomes
%28select%20Contact%29.%27Email%27