5.14.5 api dir get

The /api/dir/get function retrieves an array of entries in the directory and their specified fields.

Methods

POST

Request

The request contains parameters in the application/json format. Go to the topic api/dir/template to get more information on various parameters of an entry in the directory and their object representation.

Table 1. Request JSON Keys

Key Name	Mandatory	Expected Values	Default Value	Description
fields	No	array of strings	all fields with non-default values	Specify the names of the required fields in the response, if the key is not specified, all fields with non-default values are returned, if an empty array is submitted, all available fields are returned. Go to the topic api/dir/template to get an overview of all available keys in the JSON definition of an entry in the directory. Unknown field names are ignored.
users	No	array of JSON objects defining uuids	-	The array has to contain at least one object with the key uuid, which defines the entry whose fields are to be returned. If the key is missing or an empty array is submitted, an empty array is returned.

Example of Request

URL: https://192.168.1.1/api/dir/get JSON { "fields": [ "name", "email", "callPos.peer", "callPos[1].grouped" ], "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF" }, { "uuid": "76543210-68FF-18CA-3210-FEDCBA987654" }, { "uuid": "76543210-68FF-18-3210-FEDCBA987654" } ] }

If there is no entry in the directory with uuid 01234567-89AB-CDEF-0123-456789ABCDEF, the device will respond with an error code (see below). Similarly for the second uuid 76543210-68FF-18CA-3210-FEDCBA987654.

If the entry with uuid 01234567-89AB-CDEF-0123-456789ABCDEF is present, its specified fields (in the example name, email, phone numbers of all calling destinations and for the second calling destination also grouped) will be returned. Similarly for the second uuid 76543210-68FF-18CA-3210-FEDCBA987654.

The uuid 76543210-68FF-18-3210-FEDCBA987654 is in a wrong format.

Response

The response is in the application/json format. The result object contains the keys series and users.

Go to the topic api/dir/query to get more information on the use of the object series.

The key users contains array of objects that contain keys and values of the result of the request (see the table below).

Tip

You can get better acquinted with the structure of the JSON response in the example at the end of this topic.

Table 2. Response JSON Keys in the users array

Key Name	Typical Returned Values	Description
uuid	uuid	Unique User Identifier of a found entry.
Various keys	various	Specified fields of an entry in the directory that are returned. See the api/dir/template.
timestamp	integer	A timestamp of the last performed changes for each returned entry in the directory. Go to the topic api/dir/query to get more information on the use of the timestamp. The timestamp is present only when an entry in the directory is returned.
errors	array of error objects	An error object containing an array of all errors that occured. errors object is present only when a change in the directory failed. It contains an error code in the key code showing a reason for the failure of a change in the directory. The following error codes may be returned in a response: `EDIR_UUID_DOES_NOT_EXIST` - entry with the given uuid does not exist (i.e. cannot be updated). `EDIR_UUID_INVALID_FORMAT` - uuid is not in the valid format which is "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", where X can be any hexadecimal digit. All zeroes are reserved as an empty uuid.

Example of Response

{ "success": true, "result": { "series": "6423407687606431951", "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD", "email": "abcd@abcd.cz", "callPos": [ { "peer": "" }, { "peer": "", "grouped": "false" }, { "peer": "" } ], "timestamp": 39 }, { "uuid": "76543210-68FF-18CA-3210-FEDCBA987654", "errors": [ { "code": "EDIR_UUID_DOES_NOT_EXIST" } ] }, { "uuid": "76543210-68FF-18-3210-FEDCBA987654", "errors": [ { "code": "EDIR_UUID_INVALID_FORMAT" } ] } ] } }

The first entry in the directory is returned successfully, its uuid and timestamp are returned.

The second entry does not exist (no entry with such uuid).

The third object has a wrong format of uuid.