Version: v1

ZeyOS Standard REST API

Authentication

OAuth 2.0: oauth

OAuth 2.0 Authorization (RFC 6749); use the ZeyOS OAuth 2.0 API POST /oauth2/v1/token to obtain a valid bearer token

Security Scheme Type:	oauth2
OAuth Flow (authorizationCode):	Token URL: https://cloud.zeyos.com/{INSTANCE}/oauth2/v1/token Authorization URL: https://cloud.zeyos.com/{INSTANCE}/oauth2/v1/authorize Refresh URL: https://cloud.zeyos.com/{INSTANCE}/oauth2/v1/token Scopes:

API Key: session

Session Cookie Authentication (RFC 6265)

Security Scheme Type:	apiKey
Header parameter name:	ZEYOSID

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/.

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

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:

Bash

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

Response:

JSON

[{
	"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:

Text

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.

Text

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:

JSON

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

Result:

JSON

{
  "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:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

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:

Bash

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

Response:

JSON

[{
	"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:

Text

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.

Text

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:

JSON

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

Result:

JSON

{
  "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:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

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/.

Authentication

The REST API is only usable for authenticated users. Authentication is supported in two common ways:

1. Internal apps: If the user is already logged in to ZeyOS and you call the REST API from a browser-based ZeyOS app, the current ZeyOS session can be used.
2. External apps: Obtain a bearer token from the ZeyOS Authentication API and send it with every REST API request.

Once a token has been obtained, include it in the Authorization header:

Bash

curl -X POST \
  -H 'Authorization: Bearer YourApiToken' \
  -H 'Content-Type: application/json' \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  https://cloud.zeyos.com/demo/api/v1/contacts/

OpenAPI Specification

The complete REST API is also published as a machine-readable OpenAPI document. Use it to generate API clients, import the API into tools such as Postman or Insomnia, or hand it to an AI agent:

• /__doc/openapi/api.json - REST API OpenAPI specification (alias: /openapi.json)
• /__doc/openapi/oauth2.json - Authentication API (OAuth2) specification (alias: /openapi.oauth2.json)

The canonical source of these files is https://cloud.zeyos.com/__doc/openapi/. For an interactive, endpoint-by-endpoint view of the same specification, see the REST API Reference.

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):

JSON

{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "Address": "contact.address",
    "Postalcode": "contact.postalcode",
    "Town": "contact.city",
    "Country": "contact.country",
    "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:

Bash

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

Response:

JSON

[{
	"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 an 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 JSON objects and nested condition arrays:

JSON

{
 "field": "value",
 "field2": {"=": "value"},
 "field3": {"<": "value1", ">": "value2"},
 "field4": {"IN": ["value1", "value2"]},
 "1": ["AND", {"field5": "value5"}, {"field6": {"!=": "value6"}}]
}

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.

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.

The first thing you need to know is the number of records in order to calculate the number of pages. This can be achieved through the count modifier.

For example:

JSON

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

Result:

JSON

{
  "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 load the column content automatically.

For example:

JSON

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

Request:

Bash

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

Result:

JSON

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

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

Contact

ZeyOS GmbH & Co. KG: [email protected]

URL: https://www.zeyos.com

Terms of Service

https://www.zeyos.com/termsofservice