API Reference

Users.getUsers

Returns an array of users with standard information and metadata. Also returns userCount - the number of users found in the search.


Syntax

mixed users.getUsers ( int vhost, array filters = array(), int offset = 0, int limit = 50, array fields = array(), string sort = 'created desc', bool getExternalIds = false, bool includeDeviceInfo = false, mixed uid = 0, int followingId = 0, int userId = 0, mixed mediaId = 0, mixed includeChildGroups = false )

Arguments

NameTypeRequiredDefault valueDescription
vhostintRequirednoneThe vhost for the request.
filtersarrayOptionalarray()Any search that you wish to perform that would result in a list of users. A list of filters is available below
offsetintOptional0The offset for the result set, i.e. which user to start with (this is normally used with pagination)
limitintOptional50limits the amount of users to be returned in list
fieldsarrayOptionalarray()Specify what userinfo is to be returned. The default array that will be returned for a given search. The complete list is available below.
sortstringOptional'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.
getExternalIdsboolOptionalfalseDEPRECATED: 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.
includeDeviceInfoboolOptionalfalseDEPRECATED: 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.
uidmixedOptional0
followingIdintOptional0If 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
userIdintOptional0Required for imFollowing or followingMe filters to work, otherwise logged in user will be used, and will enforce blocked users
mediaIdmixedOptional0
includeChildGroupsmixedOptionalfalse

Filters

The filters that are available for use in the getUsers service call.

NameTypeDescription
firstnameSTRINGThe first name of users.
lastnameSTRINGThe last name of users.
userSTRINGUser's user name.
citySTRINGUser's city.
countrySTRINGUser's country.
activeBOOLEANFilters 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.
disabledBOOLEANFilters 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.
nidINTA particular notification id which had been sent to these users.
groupidINT/ARRAYA particular group id or list of groups which users may be a part of.
eventidINTA particular event id which users may be a part of.
appcodeSTRINGApp code identifier
deviceGeoDistanceINTDistance in meters from coordinates specified in deviceGeoCenter.
deviceGeoCentercoordinatesA center point to be used with deviceGeoDistance in format of lat,long. eg 38.53,77
deviceLastUpdateTimeINT or STRINGThe 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.
commentNotificationBOOLEANWhether or not a user has mobile comment notifications enabled, 0 is false, 1 is true.
assignmentNotificationBOOLEAN Whether or not a user has mobile comment notifications enabled, 0 is false, 1 is true.
geoSTRINGSet 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
imFollowingBOOLOnly return users who user follows, uid must be provided empty
followingMeBOOLOnly return users who follow user, uid must be provided empty

Response

Below are the fields available in the returned array.

NameTypeDescription
uidINTThe users ID if they are not logged in0
followersINTThe number of user's following the user.
followingINTThe number of user's the user follows.
idINTThe user id for the requested users.
userSTRINGThe user name for the requested users.
firstnameSTRINGThe first name for the requested users.
lastnameSTRINGThe last name for the requested users.
avatarINTThe media items that the users may be using as their avatar.
citySTRINGThe city in which the requested users live.
countrySTRINGThe country in which the requested users live.
genderCHARThe gender of the requested users. M for male and F for female.
birthdateDATEThe date of birth for the requested users.
languageSTRINGThe user's preferred language. A two character ISO country code will be used.
emailSTRINGThe e-mail address of the requested users.
phoneSTRINGThe users phone number.
cellphoneSTRINGThe user's cell phone number.
stateSTRINGThe state in which the requested users live.
lastloginDATETIMEThe date and time that the user was last logged into the system.
geo_latitudeFLOATThe geographical latitude of the requested users.
geo_longitudeFLOATThe geographical longitude of the requested users.
publicfilesINTThe 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.
unmoderatedfilesINTThe number of media items that the user has uploaded to the system that are yet to be moderated.
approvedfilesINTThe number of media items the user has uploaded to the system that have been approved.
deniedfilesINTThe number of media items the user has uploaded to the system that have been denied.
unmoderatedcommentsINTThe number of comments the user has posted that have yet to be moderated.
approvedcommentsINTThe 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.
deniedcommentsINTThe number of comments the user has posted that have been denied.
notdeniedcommentsINTThe number of comments the user has posted that have been approved or have yet to be mopderated.
newsletterBOOLEANWhether or not the user has requested the newsletter, 0 is false, 1 is true.
deviceinfoARRAYAn 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.
externalidsARRAYThe user's external IDs, if any.
createdDATETIMEThe date and time that the user was created.
profile_completeINTIs the user's profile complete. 1 - yes, 0 - no.
disable_media_notificationsINTHas the user disbled their media notifications: 1 - yes, 0 - no.
disable_thread_notificationsINTHas the user disbled their thread notifications: 1 - yes, 0 - no.
occupationSTRINGThe user's occupation.
friendsINTThe number of user's accepted friends.
followersINTThe number of user's following the user.
followingINTThe number of user's the user follows.
vhostINTThe application that the user is in.
metaARRAYThe user's meta data.
activeINTIndicates whether or not a user account is active:
1 = active, 0 = inactive.
disabledINTIndicates whether or not a user account is disabled:
1 = disabled, 0 = enabled.
gravataridSTRINGAn md5 hash of the user's email address, which is used to confirm the user's gravatar.

Fields

Below are the fields that you can specify to have returned by this function.

NameTypeDescription
idINTThe user id for the requested users.
userSTRINGThe user name for the requested users.
firstnameSTRINGThe first name for the requested users.
lastnameSTRINGThe last name for the requested users.
avatarINTThe media items that the users may be using as their avatar.
citySTRINGThe city in which the requested users live.
countrySTRINGThe country in which the requested users live.
genderCHARThe gender of the requested users. M for male and F for female.
birthdateDATEThe date of birth for the requested users.
languageSTRINGThe user's preferred language. A two character ISO country code will be used.
emailSTRINGThe e-mail address of the requested users.
phoneSTRINGThe users phone number.
cellphoneSTRINGThe user's cell phone number.
stateSTRINGThe state in which the requested users live.
geo_latitudeFLOATThe geographical latitude of the requested users.
geo_longitudeFLOATThe geographical longitude of the requested users.
publicfilesINTThe number of media items the user has uploaded to the system.
NOTE: You can find the value of notdeniedfiles by subtracting deniedfiles from publicfiles.
unmoderatedfilesINTThe number of media items the user has uploaded to the system that have yet to be moderated.
approvedfilesINTThe number of media items the user has uploaded to the system that have been approved.
deniedfilesINTThe number of media items the user has uploaded to the system that have been denied.
unmoderatedcommentsINTThe number of comments the user has posted that have yet to be moderated.
approvedcommentsINTThe 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.
deniedcommentsINTThe number of comments the user has posted that have been denied.
notdeniedcommentsINTThe number of comments the user has posted that have been approved or have yet to be mopderated.
newsletterBOOLEANWhether or not the user has requested the newsletter, 0 is false, 1 is true.
deviceinfoARRAYAn 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.
externalidsINTThe user's external IDs, if any.
createdDATETIMEThe date and time that the user was created.
profile_completeINTIs the user's profile complete. 1 - yes, 0 - no.
disable_media_notificationsINTHas the user disbled their media notifications: 1 - yes, 0 - no.
disable_thread_notificationsINTHas the user disbled their thread notifications: 1 - yes, 0 - no.
occupationSTRINGThe user's occupation.
friendsINTThe number of user's accepted friends.
vhostINTThe application that the user is in.
metaARRAYThe user's meta data.
activeINTIndicates whether or not a user account is active:
1 = active, 0 = inactive.
disabledINTIndicates whether or not a user account is disabled:
1 = disabled, 0 = enabled.
gravataridSTRINGAn md5 hash of the user's email address, which is used to confirm the user's gravatar.

Sample Response

Sample REST Response
http://api.newspark.ca/services/rest/users/getUsers?vhost=[VHOST_ID]&filters[city]=FILTER_CITY&fields[]=firstname&fields[]=lastname&fields[]=email&fields[]=city&sort=created%20DESC&fields[]=externalids&APIKEY=[APIKEY]
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <totalCount>2</totalCount>
  <data>
    <item>
      <id>USER_ID</id>
      <firstname>USER_FIRSTNAME</firstname>
      <lastname>USER_LASTNAME</lastname>
      <city>Toronto</city>
      <country>CA</country>
      <avatar>0</avatar>
      <email>USER_EMAIL_ADDRESS</email>
      <user>USERNAME</user>
      <gender>M</gender>
      <offset>0</offset>
    </item>
    <item>
      <id>USER_ID</id>
      <firstname>USER_FIRSTNAME</firstname>
      <lastname>USER_LASTNAME</lastname>
      <city>toronto</city>
      <country>CA</country>
      <avatar>0</avatar>
      <email>USER_EMAIL</email>
      <user>USERNAME</user>
      <gender>M</gender>
      <offset>1</offset>
    </item>
  </data>
</result>

Sample JSON Response
{
    "status": true,
    "result": {
        "id": USER_ID,
        "user": "USER_NAME",
        "password": "HASHED_USER_PASSWORD",
        "email": "USER_EMAIL",
        "firstname": "USER_FIRSTNAME",
        "lastname": "USER_LASTNAME",
        "city": "Toronto",
        "gender": "M",
        "birthdate": "2011-02-01",
        "cellphone": "4162222222",
        "phone": "4162222222",
        "website": "",
        "occupation": "",
        "address1": "1 Toronto Road",
        "address2": null,
        "postalcode": "M1M1M1",
        "state": "ON",
        "language": "",
        "country": "CA",
        "description": "",
        "storage": 0,
        "avatar": 0,
        "created": "2012-02-03 14:48:50",
        "lastlogin": "2012-02-03 16:30:11",
        "random1": 5045,
        "random2": 151285996,
        "accounttype": 0,
        "active": "1",
        "disabled": "0",
        "newsletter": "0",
        "openidurl": "",
        "nickname": "",
        "attempts": 0,
        "mobileblog": 0,
        "publicfiles": 0,
        "unmoderatedfiles": 0,
        "approvedfiles": 0,
        "deniedfiles": 0,
        "friends": 1,
        "friends_notconfirmed": 0,
        "geo_latitude": "41.83209336689739",
        "geo_longitude": "-84.44921875",
        "vhost": 231,
        "meta": {
            "lang": "en",
            "twitterUserName": "",
            "rules": "1"
        },
        "no_comment_notifications": 0,
        "profile_complete": 1,
        "externalids": {},
	"deviceInfo": 
            "0":  {
                    "id" : DEVICE_ID,
                    "uid" : USER_ID,
                    "vhost" : 239,
                    "device_id" : "04dbc117fbe284db71d3be1f37fe2e00fa13176da87f4e66de376606fdf05558",
                    "latitude" : "43.635872",
                    "longitude" : "-79.424721",
                    "lastupdatetime" : "2012-11-23 12:33:19",
                    "commentnotification" : 0,
                    "assignmentnotification" : 0,
                    "settings] : "a:1:{s:22:"notificationBadgeCount";s:1:"0";}"
                },
	    "1":  {
                    "id" : DEVICE_ID,
                    "uid" : USER_ID,
                    "vhost" : 239,
                    "device_id" : "14dbc117fbe284db71d3be1f37fe2e00fa13176da87f4e66de376606fdf05558",
                    "latitude" : "45.635872",
                    "longitude" : "-78.424721",
                    "lastupdatetime" : "2012-11-24 12:33:19",
                    "commentnotification" : 0,
                    "assignmentnotification" : 0,
                    "settings] : "a:1:{s:22:"notificationBadgeCount";s:1:"0";}"
                }
    }
}

Code examples

0 comments

Be the first to comment on getUsers.

Add a Comment

  • captcha