Structure of a search

What this is about

With POST {basis}/query you get a list of objects of a model, for example all customers from Köln, sorted by name, 25 per page. The body has two parts:

• response says which fields each object in the list has. This is the same field selection as for reading, see Field selection with response.
• parameter says which objects come back, and in which order.

A complete request

{
  "response": ["id", "name", "city"],
  "parameter": {
    "query": {
      "type": "AND",
      "filter": [
        { "key": "city", "value": "Köln", "param": "EQ" }
      ],
      "group": []
    },
    "order": [ { "field": "name", "order": "ASC" } ],
    "page": 0,
    "limit": 25,
    "meta": true
  }
}

flowchart TB
    B["Body of POST /query"] --> R["response<br/>which fields"]
    B --> P["parameter"]
    P --> Q["query<br/>which objects (filter tree)"]
    P --> O["order<br/>in which order"]
    P --> S["page + limit<br/>which slice"]
    P --> M["meta<br/>information about the list"]
    Q --> T["type: AND or OR"]
    Q --> F["filter: single conditions<br/>key, value, param"]
    Q --> G["group: subgroups<br/>again with type, filter, group"]

Default values

Everything in parameter may be left out. Then these values apply:

The response

POST /api/rest/crm/customer/query
{ "response": ["id", "name"],
  "parameter": { "limit": 2, "order": [{ "field": "name", "order": "ASC" }] } }

{
  "data": [
    { "id": "5a2b…", "name": "Alt-Muster AG" },
    { "id": "7c1d…", "name": "Muster GmbH" }
  ],
  "meta": {
    "error": false,
    "totalCount": 42,
    "currentPage": 0,
    "currentLimit": 2
  }
}

data is the list of objects on this page. Among other things, meta contains totalCount, the number of all matches across all pages. The response is shortened, see Paging and match count for all information in meta.

What happens along the way

A search needs the same read role as reading a single object. The endpoint exists only if the model enables it, see Which endpoints a model has.

All variants

Pitfalls