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:
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
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
Parameter | Type | Default | Example | Description |
---|---|---|---|---|
filters | string | N.A. |
Stringified JSON containing criteria to be used for filters {"fields":{"Email":"support@ninoxdb.de"}} {"A":"support@ninoxdb.de"} |
|
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 | |
ids | boolean | style in which filters are provided | true false |
Formats the records returned either as field id - value or field name - value. |
choiceStyle | string | ids | ids names |
Formats the choice field in a record either as option id or caption of selected option |
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:
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" |
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.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 -
- The output of the script will be streamed back as the response.
- 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
Parameter | Type | Description | Example | Response |
---|---|---|---|---|
query | string | Ninox script that will be executed |
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
Request Body | Content-Type | Description | Example | Response |
---|---|---|---|---|
{"query":"1+2"} |
application/json | Ninox script that will be executed |
{"query":"1+2"} {"query":(select Contact).'Email'} |
3 ["support@ninoxdb.de", "webinar@ninoxdb.de"] |