Tables, fields, and records

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	number	"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	"[e-mail]"
phone	string	"[phone]"
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:

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.

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":"[e-mail]"
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