Skip to main content

ZeyOS REST API Reference

Access all your ZeyOS data and connect third-party applications via a powerful, standards-based REST API.

Connection Basics

Every REST request targets one ZeyOS instance and uses the same authentication and query model.

REST base URLhttps://cloud.zeyos.com/{INSTANCE}/api/v1/Replace {INSTANCE} with the customer instance name, for example demo.
Authentication APIhttps://cloud.zeyos.com/{INSTANCE}/auth/v1/Use the Authentication API to obtain and manage bearer tokens.
Request headerAuthorization: Bearer <token>Send the bearer token with every REST API request.

Authentication Flow

  1. Obtain a tokenCreate a bearer token with the Authentication API, or use the current ZeyOS session cookie inside browser-based ZeyOS apps.
  2. Call a resource endpointList/query endpoints use POST with a JSON request body. Resource URLs end with the entity name, such as /accounts/ or /contacts/.
  3. Handle status codesTreat every HTTP status code greater than or equal to 400 as an error. Successful list responses return JSON data.
Minimal requestcurl
curl -sS -X POST \
  -H "Authorization: Bearer $ZEYOS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  "https://cloud.zeyos.com/$ZEYOS_INSTANCE/api/v1/contacts/"

Get Started

AuthenticationObtain a bearer token via OAuth 2.0 or authenticate via session cookie.Auth API reference Browse EndpointsExplore all entities — accounts, contacts, tasks, and more.View endpoints OpenAPI SpecificationDownload the machine-readable spec to use with Postman, Insomnia, or an AI agent.Download api.json

Query Body Model

Most list endpoints accept the same JSON body. Start with fields and filters, then add sorting, pagination, or expansion as needed.

query.jsonPOST
{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "City": "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,
  "expand": ["extdata"]
}
fieldsarray | objectSelect returned columns. Use an object when you want response aliases.
filtersobject | arrayCombine field conditions with AND, OR, and NOT groups.
querystringApply a search string to searchable text fields such as name.
sortarraySort by one or more columns. Prefix with + for ascending or - for descending.
countnumberReturn the number of records matching the current filters before paging.
limit / offsetnumberPage through large result sets after using count to determine total records.
expandarrayInline JSON fields or binary file references directly in the response.

Key Concepts

All endpoints share a common query model. Learn it once and apply it everywhere.

Field Selection & JoinsSelect specific fields as an array or object with aliases. Traverse first-degree relationships and extdata custom fields.
Composite FiltersCombine conditions with AND / OR / NOT. Supports equality, range, IN, regex, and LIKE operators.
Sorting & PaginationSort by multiple columns with + / - modifiers. Use count, limit, and offset to page through results.
Expanding Binary & JSONInline JSON and binary file content in query results with the expand parameter.

Practical Details

AliasesWhen fields is an object, keys become the response property names and values point to database fields."Name": "lastname"
Relationship fieldsFirst-degree relationships can be selected or filtered with dot notation after checking the schema reference."assigneduser.name"
Custom fieldsForm-builder values are stored in extdata and can be queried like regular fields."extdata.nickname"
CountsSend count before paging when you need to calculate total pages.{"count": 1, "filters": {"visibility": 0}}
Binary expansionUse expand for file references when you need the referenced content in the same response."expand": ["binfile"]
ErrorsError responses use HTTP status codes 400 and above and return a plain-text message.status >= 400

Filter Operators

Comparison=!=<><<=>>=IN!IN
Text matching~~*!~!~*~~~~*!~~!~~*
Boolean groupsANDORNOT

Return Values

200 / 201SuccessResponse body is a JSON object or array.
400+ErrorResponse body is a plain-text error message.

Related Documentation

Schema ReferenceField names and entity relationships.SDK DocsClient SDK for JavaScript / TypeScript.