Data format

This section describes the flags that can be used in various requests. The result returned in JSON depends on the used flags.

To get the values of several flags in one response, specify the sum of these flags in the request. For example, to receive the general properties 0x00000001 (1) and the custom properties 0x00000002 (2) of a unit group, specify 3.

In requests, flags must be specified in DEC format. HEX is supported only as a text format, for example "flags":"0x101".

If you specify a flag as a string, the server reads it as follows:

• a value that starts with 0x is a HEX number;
• a value that starts with 0 is an octal number;
• any other value is a DEC number.

Don’t add leading zeros to flags specified as strings. For example, "flags":"0101" is read as the octal number 101, that is 65 in DEC, not 101.

Flags define which data you request. Your access rights to the item define which of this data you receive.

The system checks access rights for each key separately, not for the flag as a whole, so one flag can return only some of its keys. A key that you have no access right to isn’t in the response at all, not even as an empty value.

For example, the advanced properties flag 0x00000100 (256) of a unit returns the uid, uid2, hw, ph, ph2, and psw keys to the users with the View connectivity settings right, and the act, act_reason, and dactt keys to the users with only View object and its basic properties.

The keys that hold the maximum allowed number of items usually require the right to edit the collection, not to view it. For example, the geofences flag 0x00001000 (4096) of a resource returns the zl key to the users with the View geofences right, and the zlmax key only to the users with Create, edit, and delete geofences.

To check which rights you have, send the base flag 0x00000001 (1) using the core/search_item or core/search_items methods and look at the uacl parameter in the response. It shows your rights to the item, with the limits of the token already applied.

A key can also be missing for the following reasons:

• The token flag. Every session is created with a token, and its flag (fl) can limit your access rights further. An access right that the token flag doesn’t include is unavailable even if the user has it. For the rights that each token flag grants, see Tokens.

• Services and limits of the billing plan. If the billing plan of the account doesn’t include a service, or the service has reached its limit, the response contains no data for this service, even if you have all the access rights. To check the services and the access rights together, use core/check_items_billing.

• Subscription flags. Some flags return no data. Instead, they subscribe the session to events. This applies, for example, to the Messages and Tasks flags.