Ninox REST API

HTTP REST / JSON is the most common interface technology these days. Ninox provides REST interfaces to read and update data.

We recommend that you use a suitable tool to send HTTP requests. Postman is a good start: https://www.getpostman.com. On Linux and macOS you can also use the curl command to issue requests from the shell/terminal.

Authentication

In order to authenticate API requests, you need to provide the API Key as an HTTP Authorization header. The format is:

Authorization: Bearer API-Key

Content-Type

NX assumes that services will provide their response as a valid JSON object. The services need to provide a Content-Type header with the value "application/json". When calling the Ninox API or sending data to other services you need to explicitly set this header in the http function, see below.

Content-Type: application/json

Get Teams

To get data from Ninox, the first step is to find the right team id. Use this request to list all your teams.

Request

GET https://api.ninoxdb.de/v1/teams

Response

[{
    "id": "67mm9vc324bM7x",
    "name": "Test-Team"
}]

Get Databases

The next step is to find the databases. With the following request you get a list of all databases within a team.

Request

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases

Response

[{
    "id": "nk5xt24oixj4",
    "name": "Invoices"
}]

Get Tables

Now, you can list all available tables in that database.

Request

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables

Response

[{
    "id": "A",
    "name": "Customer",
    "fields": [{
        "id": "A",
        "name": "First Name",
        "type": "string"
    },{
        "id": "B",
        "name": "Last Name",
        "type": "string"
    }]
}]

The body does not only list all available tables but also the table definitions. Each item consists of three properties: id, name and fields. The id is the table's id that you'll need to provide in order to get, update or delete records. The name is the user-friendly table name. Fields is an array of objects, each describing a column in the table. Each field is defined by an id, a user-friendly name and a type. See chapter "Table Definitions" for more information

Get Records

This request returns all records of the specified table. The result set is limited, though - see below.

Request

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records

Response

[{
    "id": 1,
    "sequence": 417,
    "createdAt": "2018-06-13T12:16:32",
    "createdBy": "ekL2xSxuD7jtN2F2D",
    "modifiedAt": "2018-06-15T16:05:07",
    "modifiedBy": "ekL2xSxuD7jtN2F2D",
    "fields": {
        "First Name": "Erica",
        "Last Name": "Young"
    }
}]

The response consists of an array of records. Each record has the following common attributes:

Attribute Type Description
id integer The record id, starting from 1
sequence integer The database change sequence number, when this record was last updated
createdAt string The UTC timestamp when the record has been created as 
YYYY-MM-DDThh:mm:ss
createdBy string The id of the user who created the record
modifiedAt string The UTC timestamp when the record has been updated as 
YYYY-MM-DDThh:mm:ss
modifiedBy string The id of the user who updated the record
fields object An object of all data fields, the field name is used as the key, see chapter "Table Definitions" for the value types.

Query Parameters

There are a few query parameters to control which and the amount of records to return:

Parameter Type Default Example Description
page integer 0 12 Result set page
perPage integer 100 250 Records per page
order string   First Name The field name to order the result
desc boolean false true Order descending
new boolean false true Show newest records first 
(cannot be combined with order)
updated boolean false true Show latest updates first 
(cannot be combined with order)
sinceId integer   42 Show only records with a higher ID
sinceSq integer   1567 Show only records that are created or updated after the specified database change sequence number

Example Request

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records?page=2&perPage=5&order=First%20Name

Get a single Record

If you do know the record id of the record you're interested in, use this request.

Request

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records/1

Response

{
    "id": 1,
    "sequence": 417,
    "createdAt": "2018-06-13T12:16:32",
    "createdBy": "ekL2xSxuD7jtN2F2D",
    "modifiedAt": "2018-06-15T16:05:07",
    "modifiedBy": "ekL2xSxuD7jtN2F2D",
    "fields": {
        "First Name": "Erica",
        "Last Name": "Young"
    }
}

Lookup  a single Record

If you want to get a record based on some data of record known to you then use this request.

Tip : If you already have the record id of the record you're interested in then use the Get a single Record request as that will be more efficient.

Request

POST https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/record

Note : The endpoint is record and not records.

Body

{
"B": "support@ninoxdb.de",
"C": true
}

Response

{
"id": 1,
"sequence": 19,
"createdAt": "2018-09-06T12:21:04",
"createdBy": "admin",
"modifiedAt": "2018-10-08T17:15:52",
"modifiedBy": "admin",
"fields": {
"Name": "Ninox Support",
"Email": "support@ninoxdb.de",
"Has Replied?": true
}
}

Tip : and in request body are field ids/column ids for the fields Email and Has Replied ? respectively. Issue a request to fetch the target table to know which field map to what id.

Update Records

Multiple records can be updated and/or created with a single request. The request body must contain an array of all records to create or update. 

To update a record: Specify the record's id and all fields that shall be updated.

To create a record: Leave out the id.

Request

POST https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records

Headers

Content-Type: application/json

Body

[{
    "id": 1,
    "fields": {
        "First Name": "Erica-Maria"
    }
},{
    "fields": {
        "First Name": "Lisa",
        "Last Name": "Schmidt"
    }
}]

Response

[{
    "id": 1,
    "sequence": 418,
    "createdAt": "2018-06-13T12:16:32",
    "createdBy": "ekL2xSxuD7jtN2F2D",
    "modifiedAt": "2018-06-15T16:05:07",
    "modifiedBy": "ekL2xSxuD7jtN2F2D",
    "fields": {
        "First Name": "Erica-Maria",
        "Last Name": "Young"
    }
},{
    "id": 48,
    "sequence": 418,
    "createdAt": "2018-06-15T16:05:07",
    "createdBy": "ekL2xSxuD7jtN2F2D",
    "modifiedAt": "2018-06-15T16:05:07",
    "modifiedBy": "ekL2xSxuD7jtN2F2D",
    "fields": {
        "First Name": "Lisa",
        "Last Name": "Schmidt"
    }
}]

Create Records

See Update Records, the same request can be used to create records by leaving out the id.

Delete a Record

A single record can be deleted with the following request. At the time, it's not possible to delete multiple records with one request.

Request

DELETE https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records/1

Response

{}

An empty object indicates that the deletion took effect.

Table Definitions

Tables are defined by an id, a human-friendly name and an array of fields. Table ids start with "A", "B", … "AA", "AB", …

Each field is defined by an id, a human-friendly name and a type. Field ids start with "A", "B", … "AA", "AB", … 

Note: Table and field ids won't change during the life time of a database. Don't make assumption about the format of an id but use this as an opaque identifier since the format may be subject to change in future versions.

Field types are defined as follows:

Ninox Field Type JSON Value Example
text string "Lisa"
number number 13.42
date number "2018-01-23"
datetime string "2018-01-23T12:30:00"
timeinterval string "123:25:16.123"
time string "12:30:00"
appointment string "2018-01-23T12:30:00 - 2018-01-23T13:30:00"
boolean boolean true, false
choice string "Blue"
url string "http://ninoxdb.de"
email string "support@ninoxdb.de"
phone string "+1 123456789"
location string "Marienstraße 10, 10117 Berlin, Germany <52.52202224731445,13.38234806060791>"
html string "<h1>Hello</h1>"

Fetch Files From Record

With the following request you can fetch files accociated with the record.

Request

GET  https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/tables/:tableid/records/:recordid/files

Response

[{
   "name": "image3.jpg",
   "contentType": "image/jpeg",
   "size": 56969,
   "modifiedDate": 1550506659843,
   "modifiedUser": "......",
   "seq": 220
}]

Download File From Record

With the following request you can download files attached to a record

Request

GET https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/tables/:tableid/records/:recordid/files/:filename

Response

The file itself

Upload File To A Record

With the following request you can upload files to Ninox record

Request

POST  https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/tables/:tableid/records/:recordid/files

Content-Type

Content-Type: multipart/form-data

Valid File Names

The name of the file to be uploaded should not contain the following special characters  \,/,*,?,>,<,|,"

Response

A response message saying "File Uploaded Successfully" with Content-Type = text/html and a status code of 200 OK

Delete File From Record

With the following request you can upload files to Ninox record

Request

DELETE  https://api.ninoxdb.test/v1/teams/:teamid/databases/:databaseid/tables/:tableid/records/:recordid/files/:filename

Valid File Name

Please enter the name of the file with the file extension.

Response

- A status code of 204 No Content without any message in case of successful deletion.
- A status code of 404 Not Found along with text message saying "File already deleted" in case of file not found/already deleted".