Understand Ninox API and set up your environment
Ninox moved from ninoxdb.de to ninox.com. The current interface is api.ninox.com/v1. We recommend building new integrations on top of the new interface.
The old interface api.ninoxdb.de/v1 continues to work, so you don't need to migrate old integrations built with Zapier, Integromat, or other custom solutions.
To use the Ninox API, you need the following:
Ninox license
Ninox Personal Access Token
Ninox REST API
Depending on the details of your server environment:
Public Cloud, Private Cloud, or Private Cloud On-Premises
Zapier, Integromat, or a similar solution
Use Postman to send API requests. Alternatively, call endpoints in your shell/terminal using the cURL command. A third option is the http function in the Ninox formula editor.
The Ninox API is an organized RESTful API. It consists of predictable URLs, form-encoded requests, JSON-encoded responses, and common HTTP response codes. The API also uses standard authentication and verbs.
The Ninox API uses Bearer Tokens to authenticate requests. View and manage your Personal Access Tokens in your admin settings in the Ninox web app.
To authenticate your API requests, include the accessToken in the HTTP Authorization header. Content in curly brackets { } signifies a placeholder. Both the curly brackets and the content within must be replaced for the authentication to work.
Ninox recommends that API requests be made over HTTPS. In the Public and Private Cloud, HTTP requests are redirected to HTTPS. If you try to make API requests over plain HTTP and don't follow the redirect, they will fail. Even if you have a username and password, API requests without authentication will also fail.
Ninox expects services to provide their responses in JSON. To provide a response as a valid JSON object, the services need to provide application/json in the HTTP Content-Type representation header.
The Personal Access Token, or API key, is included with every HTTP request made to the Ninox API.
If you are the owner of a workspace, follow the steps below to obtain the API key:
Visit ninox.com.
Click the Start Ninox button to open the web app.
If you don't see the Start Ninox button, log in with your Ninox credentials first.
In the top-right corner, click the Actions gear icon.
In the drop-down menu, select Integrations.
In the pop-up window, click the Generate button.
Copy the API key to your clipboard.
To delete or revoke a Personal Access Token, click the Delete Token cross mark icon that appears to the right of the generated API key.
Your Ninox API keys grant read and write access to all of your databases, so keep your tokens secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.
Ninox uses conventional HTTP response codes to indicate whether an API request was successful or unsuccessful. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx indicate a server error.
Status code
Definition
200 OK
The request has succeeded. The meaning of the success depends on the HTTP method:
GET: The resource has been fetched and is transmitted in the message body.
HEAD: The representation headers are included in the response without any message body.
PUT or POST: The resource describing the result of the action is transmitted in the message body.
TRACE: The message body contains the request message as received by the server.
201 Created
The request has succeeded and a new resource has been created as a result. This is typically the response sent after POST requests, or some PUT requests.
202 Accepted
The request has been received but not yet acted upon. It is noncommittal, since there is no way in HTTP to later send an asynchronous response indicating the outcome of the request. It is intended for cases where another process or server handles the request, or for batch processing.
204 No Content
There is no content to send for this request, but the headers may be useful. The user-agent may update its cached headers for this resource with the new ones.
Status code
Definition
400 Bad Request
The server could not understand the request due to invalid syntax.
401 Unauthorized
Although the HTTP standard specifies ”unauthorized,” semantically this response means ”unauthenticated.” That is, the client must authenticate itself to get the requested response.
403 Forbidden
The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server.
404 Not Found
The server can not find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 to hide the existence of a resource from an unauthorized client. This response code is probably the most famous one due to its frequent occurrence on the web.
422 Unprocessable Entity (WebDAV)
The request was well-formed but was unable to be followed due to semantic errors.
Status code
Definition
500 Internal Server Error
The server has encountered a situation it doesn't know how to handle.
501 Not Implemented
The request method is not supported by the server and cannot be handled. The only methods that servers are required to support (and therefore that must not return this code) are GET and HEAD.
502 Bad Gateway
This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response.
Query parameters and common attributes to query records with Ninox API
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.
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.
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.
Each record has the following common attributes:
The following query parameters control which and how many records are returned when retrieving records using a GET or POST request.
When filtering records, encode the path parameter using the encodeURIComponent()function in JavaScript.
Before encoding, a JSON string containing the following
after URI encoding becomes
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"
string
"support@ninox.com"
phone
string
"+1 123456789"
location
string
"Monbijouplatz 5, 10178 Berlin, Germany
<52.5330804,13.3972939>"
html
string
"<h1>Hello</h1>"
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"
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