Read User

Resource: user

Reads all specified fields from user records. Most user fields are valid here and are passed as elements of an array in the parameter data. You cannot read the user password via API.

If you specify a user ID as resourceid, only data for this user will be read. If you need to retrieve the user IDs, then query all users first with parameter data and without a filter. The response includes the user IDs.

Each field is returned with the appropriate value of the record.

In enterprise, user data is found under “Extras->Settings->User” / “Extras->Einstellungen->Benutzer”.

You need read permission to query user data via API. This can be set under “Extras->Einstellungen->Benutzer” / “Extras->Settings->User”. Choose the tab “API user”, then the tab “Rights” with the setting “Benutzerdaten über API auslesen” / “Read out user data via API”. Only API users can see this setting.

Your own user can be queried via resourceid even without the right “Benutzerdaten über API auslesen / Read out user data via API”.

Parameters:

  • data
    ARRAY. The following fields can be queried: Anrede, Titel, Kuerzel, Vorname, Nachname, Firma, PLZ, Ort, Strasse, Hausnummer, Land, province, Mobil, Telefon, Fax, Url, UstID, taxNumber, Gerichtsstand, imprintFurthermore (Weiteres), Firmazusatz1, PositionUnternehmen, Namezusatz1, Namezusatz2, Bank, IBAN, BIC, Finanzamt, Hinweis, Sonstiges, Nr, Name (user name), email, Emailname, adrId:adressen.ID (linked user address), anbieter, Prefix, usesAccount:account.id (Account approved or blocked), Sprache, meetingUrl (user link for video conference), online (status of the user, see values below), type (user type, see values below), userCreationDate
  • filter
    OBJECT. Key: field, value: array of objects with filter expressions in the format "Nr": [{"op": "=", "val": 1}]. With op you specify the operator. Possible values for op are the following SQL operators:

    is or =, >, <, >=, <=, != or <>, between, like, not like, in, not in

    For the operator like the value % can be specified as a placeholder.

    With val you specify the value which should be applied to the filtering. The individual filter expressions are linked with the AND operation. All fields of parameter data can be specified for the filter. See also the examples below.

  • sortby
    OBJECT. Fields to sort by. The field name is used as the key, and the type of sorting as the value. Notation: {"Nachname": "ASC", "Vorname": "ASC"}
    Possible values for sorting are ASC for ascending, DESC for descending.
  • listlimit
    INTEGER. Maximum number of users in the list. Default value: 20, maximum: 500.
  • listoffset
    INTEGER. Offset of the list, that means from which data record onwards the list should be output.

Values of the field type: (several types can be combined with the operator in)

  • user: regular user
  • apiuser: API user
  • template: user template, not a real user

Values of the field online:

  • offline: active user, currently not logged in
  • online: active user, currently logged in
  • gesperrt Falscheingabe Passwort: locked after incorrect password entries
  • permanent deaktiviert: permanently deactivated
  • gesperrt Benutzerverwaltung: locked in the user administration
  • gesperrt Mandantenverwaltung: locked in the client administration
Request: Read first name, last name and email name from users 17, 19 and 21 
{
	"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
	"resourceid": "",
	"identifier": "",
	"resourcetype": "user",
	"parameters": {
		"data": ["Vorname", "Nachname", "type", "online"],
		"filter": {"Nr": [{"op": "in", "val": [17, 19, 21]}], "type": [{"op": "in", "val": ["user", "apiuser"]}]},
		"sortby": {"Nr": "DESC"},
		"listlimit": 10
	}
}
Response 
{
	"status": {
		"code": 200,
		"errorcode": 0,
		"message": "OK"
	},
	"response": {
		"results": [
			{
				"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
				"resourceid": "",
				"resourcetype": "user",
				"cacheable": true,
				"identifier": "",
				"data": {
					"meta": {
						"cntabsolute": 1
					},
					"records": [
						{
							"id": 19,
							"type": "user",
							"elements": {
								"Vorname": "Theo",
								"Nachname": "Test",
								"type": "user",
								"online": "offline"
							}
						}
					]
				},
				"status": {
					"errorcode": 0,
					"message": "OK"
				}
			}
		]
	}
}