| Name | Type | Required | Default value | Description |
|---|
| vhost | int | Required | none | The vhost for the request. |
| filters | array | Optional | array() | Any search that you wish to perform that would result in a list of users. A list of filters is available below |
| offset | int | Optional | 0 | The offset for the result set, i.e. which user to start with (this is normally used with pagination) |
| limit | int | Optional | 50 | limits the amount of users to be returned in list |
| fields | array | Optional | array() | Specify what userinfo is to be returned. The default array that will be returned for a given search. The complete list is available below. |
| sort | string | Optional | 'created desc' | Define how you want the result set to be sorted. Use any of these fields with an 'asc' or 'desc' afterwards:
id, user, created, firstname, nickname, lastname, friends, city, country, gender, email, publicfiles, umoderatedfiles, approvedfiles, deniedfiles, active, lastlogin and distance.
NB 1: The distance refers to the distance from the deviceGeoCenter; this can be used to sort the result set only if filters[deviceGeoDistance] and filters[deviceGeoCenter] are provided.
NB 2: The distance can be used to sort the result set only in ascending order, so adding 'desc' after it will not change the order of the results. |
| getExternalIds | bool | Optional | false | DEPRECATED: Do not use; intead, set Field 'externalids'.
If getExternalIds is set to true, it will return any external id of the the users in the result set. |
| includeDeviceInfo | bool | Optional | false | DEPRECATED: Do not use; intead, set Field deviceInfo'.
If includeDeviceInfo is set to true, it will return an array of the user's devices in the result set. |
| uid | mixed | Optional | 0 | |
| followingId | int | Optional | 0 | If set to a userID, it will check if the user who is returned, is being followed or not by the user represented by followingId, will use loggedInUser if session provided |
| userId | int | Optional | 0 | Required for imFollowing or followingMe filters to work, otherwise logged in user will be used, and will enforce blocked users |
| mediaId | mixed | Optional | 0 | |
| includeChildGroups | mixed | Optional | false | |
The filters that are available for use in the getUsers service call.
| Name | Type | Description |
|---|
| firstname | STRING | The first name of users. |
| lastname | STRING | The last name of users. |
| user | STRING | User's user name. |
| city | STRING | User's city. |
| country | STRING | User's country. |
| active | BOOLEAN | Filters the userlist based on whether or not a user account is active:
Set to 'true' to return active accounts only.
Set to 'false' to return inactive accounts only.
Do not set this filter to return both kinds of user accounts. |
| disabled | BOOLEAN | Filters the userlist based on whether or not a user account is disabled:
Set to 1 or 'true' to return disabled accounts only.
Set to 0 or 'false' to return enabled accounts only.
Do not set this filter to return both kinds of user account. |
| nid | INT | A particular notification id which had been sent to these users. |
| groupid | INT/ARRAY | A particular group id or list of groups which users may be a part of. |
| eventid | INT | A particular event id which users may be a part of. |
| appcode | STRING | App code identifier |
| deviceGeoDistance | INT | Distance in meters from coordinates specified in deviceGeoCenter. |
| deviceGeoCenter | coordinates | A center point to be used with deviceGeoDistance in format of lat,long. eg 38.53,77 |
| deviceLastUpdateTime | INT or STRING | The timestamp or datetime used to filter users by showing only the users with devices that had their location updated after this date/time.
Examples: datetime '2013-04-18 12:41:38' is the same as timestamp 1366288898.
Note: If the deviceLastUpdateTime value is set to epoch ('1970-01-01 00:00:00' or 0) or NULL, then all the users will be returned, not only the ones with devices. |
| commentNotification | BOOLEAN | Whether or not a user has mobile comment notifications enabled, 0 is false, 1 is true. |
| assignmentNotification | BOOLEAN | Whether or not a user has mobile comment notifications enabled, 0 is false, 1 is true. |
| geo | STRING | Set this to 'notnull' to return only the users that have valid geo-location values, meaning ones with geo_latitude <> null and geo_longitude <> null. | empty |
| imFollowing | BOOL | Only return users who user follows, uid must be provided | empty |
| followingMe | BOOL | Only return users who follow user, uid must be provided | empty |
Below are the fields available in the returned array.
| Name | Type | Description |
|---|
| uid | INT | The users ID if they are not logged in | 0 |
| followers | INT | The number of user's following the user. |
| following | INT | The number of user's the user follows. |
| id | INT | The user id for the requested users. |
| user | STRING | The user name for the requested users. |
| firstname | STRING | The first name for the requested users. |
| lastname | STRING | The last name for the requested users. |
| avatar | INT | The media items that the users may be using as their avatar. |
| city | STRING | The city in which the requested users live. |
| country | STRING | The country in which the requested users live. |
| gender | CHAR | The gender of the requested users. M for male and F for female. |
| birthdate | DATE | The date of birth for the requested users. |
| language | STRING | The user's preferred language. A two character ISO country code will be used. |
| email | STRING | The e-mail address of the requested users. |
| phone | STRING | The users phone number. |
| cellphone | STRING | The user's cell phone number. |
| state | STRING | The state in which the requested users live. |
| lastlogin | DATETIME | The date and time that the user was last logged into the system. |
| geo_latitude | FLOAT | The geographical latitude of the requested users. |
| geo_longitude | FLOAT | The geographical longitude of the requested users. |
| publicfiles | INT | The total number of media items the user has uploaded to the system.
NOTE: You can find the value of notdeniedfiles by subtracting deniedfiles from publicfiles. |
| unmoderatedfiles | INT | The number of media items that the user has uploaded to the system that are yet to be moderated. |
| approvedfiles | INT | The number of media items the user has uploaded to the system that have been approved. |
| deniedfiles | INT | The number of media items the user has uploaded to the system that have been denied. |
| unmoderatedcomments | INT | The number of comments the user has posted that have yet to be moderated. |
| approvedcomments | INT | The number of comments the user has posted that have been approved.
NOTE: You can find the value of notdeniedcomments by calculating the sum of approvedcomments plus unmoderatedcomments. |
| deniedcomments | INT | The number of comments the user has posted that have been denied. |
| notdeniedcomments | INT | The number of comments the user has posted that have been approved or have yet to be mopderated. |
| newsletter | BOOLEAN | Whether or not the user has requested the newsletter, 0 is false, 1 is true. |
| deviceinfo | ARRAY | An array of the user's devices. The values returned are as follows: (with i being the iterator of the user's devices, should the user have more than one)
- deviceinfo[i]['id'] - (Integer) The id of the device. ie. 54321
- deviceinfo[i]['uid'] - (Integer) The id of the user.
- deviceinfo[i]['vhost'] - (Integer) The id of the vhost.
- deviceinfo[i]['device_id'] - (String) The string id of the device.
ie: 1f6d530974e0aae8d6ad52734bcead167edab73d40127f8ec762f42d674386fb - deviceinfo[i]['latitude'] - (FLoat) The latitude of the device. Ie: 43.635609
- deviceinfo[i]['longitude'] - (FLoat) The longitude of the device. Ie: -79.424858
- deviceinfo[i]['lastupdatetime'] - (Datetime) The datestamp of the last occurance that the device was used to connect to the application. Ie: 2012-12-07 11:40:56
- deviceinfo[i]['commentnotification'] - (Integer) Indicates whether the user enabled their comment notifications or not. Values: 1 (yes) or 0 (no)
- deviceinfo[i]['assignmentnotification'] - (Integer) Indicates whether the user enabled their assignment notifications or not. Values: 1 (yes) or 0 (no)
- deviceinfo[i]['settings'] - a serialized string with the user's settings: ie: a:1:{s:22:"notificationBadgeCount";s:1:"0";}
- deviceinfo[i]['distance'] - (integer) The distance in meters from the deviceGeoCenter. This is returned only if filters[deviceGeoDistance] and filters[deviceGeoCenter] are provided.
|
| externalids | ARRAY | The user's external IDs, if any. |
| created | DATETIME | The date and time that the user was created. |
| profile_complete | INT | Is the user's profile complete. 1 - yes, 0 - no. |
| disable_media_notifications | INT | Has the user disbled their media notifications: 1 - yes, 0 - no. |
| disable_thread_notifications | INT | Has the user disbled their thread notifications: 1 - yes, 0 - no. |
| occupation | STRING | The user's occupation. |
| friends | INT | The number of user's accepted friends. |
| followers | INT | The number of user's following the user. |
| following | INT | The number of user's the user follows. |
| vhost | INT | The application that the user is in. |
| meta | ARRAY | The user's meta data. |
| active | INT | Indicates whether or not a user account is active:
1 = active, 0 = inactive. |
| disabled | INT | Indicates whether or not a user account is disabled:
1 = disabled, 0 = enabled. |
| gravatarid | STRING | An md5 hash of the user's email address, which is used to confirm the user's gravatar. |
Below are the fields that you can specify to have returned by this function.
| Name | Type | Description |
|---|
| id | INT | The user id for the requested users. |
| user | STRING | The user name for the requested users. |
| firstname | STRING | The first name for the requested users. |
| lastname | STRING | The last name for the requested users. |
| avatar | INT | The media items that the users may be using as their avatar. |
| city | STRING | The city in which the requested users live. |
| country | STRING | The country in which the requested users live. |
| gender | CHAR | The gender of the requested users. M for male and F for female. |
| birthdate | DATE | The date of birth for the requested users. |
| language | STRING | The user's preferred language. A two character ISO country code will be used. |
| email | STRING | The e-mail address of the requested users. |
| phone | STRING | The users phone number. |
| cellphone | STRING | The user's cell phone number. |
| state | STRING | The state in which the requested users live. |
| geo_latitude | FLOAT | The geographical latitude of the requested users. |
| geo_longitude | FLOAT | The geographical longitude of the requested users. |
| publicfiles | INT | The number of media items the user has uploaded to the system.
NOTE: You can find the value of notdeniedfiles by subtracting deniedfiles from publicfiles. |
| unmoderatedfiles | INT | The number of media items the user has uploaded to the system that have yet to be moderated. |
| approvedfiles | INT | The number of media items the user has uploaded to the system that have been approved. |
| deniedfiles | INT | The number of media items the user has uploaded to the system that have been denied. |
| unmoderatedcomments | INT | The number of comments the user has posted that have yet to be moderated. |
| approvedcomments | INT | The number of comments the user has posted that have been approved.
NOTE: You can find the value of notdeniedcomments by calculating the sum of approvedcomments plus unmoderatedcomments. |
| deniedcomments | INT | The number of comments the user has posted that have been denied. |
| notdeniedcomments | INT | The number of comments the user has posted that have been approved or have yet to be mopderated. |
| newsletter | BOOLEAN | Whether or not the user has requested the newsletter, 0 is false, 1 is true. |
| deviceinfo | ARRAY | An array of the user's devices, returned only when deviceinfo is included in the 'fields' array. The values returned are as follows: (with i being the iterator of the user's devices, should the user have more than one)
- deviceinfo[i]['id'] - (Integer) The id of the device. ie. 54321
- deviceinfo[i]['uid'] - (Integer) The id of the user.
- deviceinfo[i]['vhost'] - (Integer) The id of the vhost.
- deviceinfo[i]['device_id'] - (String) The string id of the device.
ie: 1f6d530974e0aae8d6ad52734bcead137edab73d40127f8ec762f42d674386cb - deviceinfo[i]['latitude'] - (FLoat) The latitude of the device. ie: 43.635609
- deviceinfo[i]['longitude'] - (FLoat) The longitude of the device. ie: -79.424858
- deviceinfo[i]['lastupdatetime'] - (Datetime) The datestamp of the last occurance that the device was used to connect to the application. ie: 2012-12-07 11:40:56
- deviceinfo[i]['commentnotification'] - (Integer) Indicates whether the user enabled their comment notifications or not. Values: 1 (yes) or 0 (no)
- deviceinfo[i]['assignmentnotification'] - (Integer) Indicates whether the user enabled their assignment notifications or not. Values: 1 (yes) or 0 (no)
- deviceinfo[i]['appcode'] - (String) Associates users device with specific mobile app.
- deviceinfo[i]['settings'] - a serialized string with the user's settings: ie: a:1:{s:22:"notificationBadgeCount";s:1:"0";}
- deviceinfo[i]['distance'] - (integer) The distance in meters from the deviceGeoCenter. This is returned only if filters[deviceGeoDistance] and filters[deviceGeoCenter] are provided.
|
| externalids | INT | The user's external IDs, if any. |
| created | DATETIME | The date and time that the user was created. |
| profile_complete | INT | Is the user's profile complete. 1 - yes, 0 - no. |
| disable_media_notifications | INT | Has the user disbled their media notifications: 1 - yes, 0 - no. |
| disable_thread_notifications | INT | Has the user disbled their thread notifications: 1 - yes, 0 - no. |
| occupation | STRING | The user's occupation. |
| friends | INT | The number of user's accepted friends. |
| vhost | INT | The application that the user is in. |
| meta | ARRAY | The user's meta data. |
| active | INT | Indicates whether or not a user account is active:
1 = active, 0 = inactive. |
| disabled | INT | Indicates whether or not a user account is disabled:
1 = disabled, 0 = enabled. |
| gravatarid | STRING | An md5 hash of the user's email address, which is used to confirm the user's gravatar. |
