Ninox REST API

NOTICE:
Please note that we moved to ninox.com from ninoxdb.de. What does this mean for our API users?
- The new API interface is https://api.ninox.com/v1 and it is advisable to build new integration on top of the new interface.
- The old interface https://api.ninoxdb.de/v1 will continue to work so customers need not to worry about old integration (Zapier/Integromat/Custom) built on old interface.

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:

Query Parameters

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

Example Request

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

Filter Records

This request returns all records of the specified table that matches the filter criteria specified as query parameters.

Request

GET https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records?filters={}

Query Parameters

Important Note

The query parameter needs to be escaped using any URI component encoding methods.

An example method used for escaping query params in Javascript will be - encodeURIComponent('{"A":"support@ninoxdb.de"}')

So a JSON string containing following -

{"A":"support@ninoxdb.de"}

after URI encoding will become -

%7B%22A%22%3A%22support%40ninoxdb.de%22%7D

Example Request

GET https:/https://api.ninoxdb.de/v1/teams/67mm9vc324bM7x/databases/nk5xt24oixj4/tables/A/records?filters=%7B%22A%22%3A%22support%40ninoxdb.de%22%7D

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 : B and C 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:

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 202 ACCEPTED

Delete File From Record

With the following request you can upload files to Ninox record

Request

DELETE  https://api.ninoxdb.de/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".

Execute a Ninox Script

With the following request you can execute any valid Ninox script against a database.

Few things to consider -

1. The output of the script will be streamed back as the response.
2. Scripts having any compilation errors will terminate the request with a null reponse.

Request

The request can be executed using both GET and POST HTTP methods

GET https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/query?query=1+2

Query Parameters

 1+2 

 (select Contact).'Email' 

 3 

 ["support@ninoxdb.de", "webinar@ninoxdb.de"] 

Important Note

The query parameter needs to be escaped using any URI component encoding methods.

An example method used for escaping query params in Javascript will be - encodeURIComponent('1+2')

So a parameter containing following -

(select Contact).'Email'

after URI encoding will become -

(select%20Contact).'Email'

POST https://api.ninoxdb.de/v1/teams/:teamid/databases/:databaseid/query

 {"query":"1+2"} 

 {"query":(select Contact).'Email'} 

 3 

 ["support@ninoxdb.de", "webinar@ninoxdb.de"]