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