Skip to main content

The ZeyOS Standard REST API provides access to almost all of your ZeyOS data and gives you a powerful tool to connect third-party applications and other systems with ZeyOS, without having to write a custom ZeyOS app.

You may access the ZeyOS Standard REST API via https://cloud.zeyos.com/{INSTANCE}/api/v1/, provided that you supply a valid token generated through the ZeyOS Authentication API via https://cloud.zeyos.com/{INSTANCE}/auth/v1/.

Return Values and Error Handling​

The ZeyOS Standard REST API currently only returns JSON data and an HTTP status code indicating the outcome of a request.

HTTP status code 200 or 201 are used to indicate a successful response, and the result will be a JSON object.

When an error occurs, the HTTP status code will be 400 or greater, and the response will be a text message.

We recommend that you treat any HTTP status code greater than or equal to 400 as an error.

Data Retrieval​

The ZeyOS Standard REST API allows you to execute complex queries, including simple joins and composite filters.

Let's take a look at the following example:

Query (query.json):

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname"
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "SalesAgent": "assigneduser.name"
  },
  "filters": {
    "visibility": 0,
    "contact.country": {"IN": ["DE", "AT", "GB"]},
    2: [
      "OR",
      {"lastmodified": {">": 1524472045}},
      {"contact.lastmodified": {">": 1524472045}}
    ]
  },
  "sort": [
    "+lastname",
    "-contact.country"
  ],
  "limit": 3,
  "offset": 0
}

Request:

$ curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H "Content-Type: application/json" \
  --data @./query.json \
  https://cloud.zeyos.com/demo/api/v1/accounts/

Response:

[{
	"Id": 2,
	"Name": "BEQ Building Equipment",
	"Nickname": null,
	"Address": "Queensstreet",
	"Postalcode": "12923",
	"Town": "London",
	"Country": "GB",
	"SalesAgent": "Max Mueller"
}, {
	"Id": 15,
	"Name": "CleanTexx",
	"Nickname": null,
	"Address": "Tower Bridge",
	"Postalcode": "12923",
	"Town": "London",
	"Country": "GB",
	"SalesAgent": null
}, {
	"Id": 1,
	"Name": "Lightexx AG",
	"Nickname": null,
	"Address": "Schmittstr. 4",
	"Postalcode": "80172",
	"Town": "Munich",
	"Country": "DE",
	"SalesAgent": null
}]

Field Selection​

The field selection references all fields you want to have included in your query results. You can either specify your field selection as and array or as an object. Using an object is useful if you want to specify alias names. In the example above, we select the field lastname with an alias called name.

If you are not certain what fields are available for which entity, you can either check the entity reference in this document or the ZeyOS Schema Documentation.

Besides selecting the entity's own fields, you can also perform simple join operations within the entity's first degree relationships. In order to discover relationships, it's best to check the ZeyOS Schema Documentation, it also contains a graphical map of all entity relationships.

Besides related tables you can also select extdata fields. extdata is a concept in ZeyOS which allows for storing additional values for all entities in ZeyOS. Whenever you create a new form field in ZeyOS, the field's value is stored in extdata.

Filters​

You can specify composite filters as you would in a regular SQL statement:

filters <array/json> = {
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 ["AND/OR/NOT", {...}, {...}]
}

The following filter operators are supported:

  • =: Equals
  • !=, <>: Not equals
  • <: Less than
  • <=: Less than or equal to
  • >: Greater than
  • >=: Greater than or equal to
  • IN: Contains (e.g. "field": {"IN": ["value1", "value2"]})
  • !IN: Does not contain

For strings you can also use the following operators:

  • ~: Matches regular expression
  • ~*: Matches regular expression, case-insensitive
  • !~: Not matches regular expression
  • !~*: Not matches regular expression, case-insensitive
  • ~~: Is like
  • ~~*: Is like, case-insensitive
  • !~~: Not like
  • !~~*: Not like, case-insensitive

Search Queries​

The query parameter allows to specify a search string, that will be applied to all searchable strings, such as name.

Sorting​

You can sort by multiple columns by defining an array of column names.

sort <array/json> = {
 "field1",
 "+field2",
 "-field3"
}

Adding modifiers will set the sorting mode:

  • + for ascending
  • - for descending

Pagination​

Sometimes the result size might be too large to be selected through one query. In such cases it makes sense to use pagination to page through the results.

Obviously, the first thing you need to know is the number or records in order to calculate the number of pages. This can be achived throuch the count modifier.

For example:

{
  "count": 1,
  "filters": {
    "visibility": 0,
    "contact.country": {"IN": ["DE", "AT", "GB"]},
    2: [
      "OR",
      {"lastmodified": {">": 1524472045}},
      {"contact.lastmodified": {">": 1524472045}}
    ]
  }
}

Result:

{
  "count":5
}

Now that you have the number of records, you can easily page through the result by using the limit and offset parameters.

Expanding JSON and Binary Data​

Some table columns include JSON data or reference binary files. The expand parameter allows you to specify to load the columns content automatically.

For example:

{
  "fields": [
    "ID",
    "subject",
    "binfile"
  ],
  "expand": [
    "binfile"
  ],
  "limit": 1
}

Request:

$ curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H "Content-Type: application/json" \
  --data @./query.json \
  https://cloud.zeyos.com/demo/api/v1/messages/

Result:

[{"ID":188,"subject":"Test","binfile":{"content":"UmV0dXJuLVBhdGg6IDx..."}}]

This example will return the entire e-mail message as RFC 822.