Home Guides API reference What's New Developer Discussion

users

The users collection represents anonymous and registered community users. Its fields provide information about registration, profile, subscriptions, ranks, roles, badges, and activity. Users exist within a single community and do not cross over between communities.

Data returned in the response is affected by:

  • Whether the user making the call is anonymous or registered
  • The role(s) of the user making the call

In the table below, an asterisk (*) indicates which fields are visible to anonymous users.

Administrators and moderators see more data about the a user's rank, such as what activity was met in order for the user to reach their current rank and what roles the user has that affect their ranking. Users must meet certain criteria before they earn a rank. Community Managers set the criteria in the Community Admin. Alternatively, they can create custom formulas. The data returned is defined Community Admin > Users > Ranking > Rankings.

Some personal profile and preference information, such as biography, is optional information provided by the user in a quilt such as the MyProfilePage quilt. If the information isn't provided by the user, the field is not returned with the response.

Each registered user (also referred to as "community member") has a unique user ID. Anonymous users have the id "-1".

See the following sections for which fields, functions, constraints, sorts, and HTTP calls this collection supports.

Open beta (subject to change)
Closed beta. If you are not in the closed beta program, do not use this field in your custom code.
 

Fields

The table below lists and describes fields in this collection. Fields in this table are supported in the SELECT statement of a LiQL query unless otherwise noted.

Field Description Datatype Released
 albums * The image albums associated with the user's profile album 14.10
 avatar * The avatar (profile image) of the user user_avatar 14.10
 banned Whether or not the user is banned. True if banned. boolean 14.10
 biography The biography provided by the user string 14.10
 bonus_points Any bonus points that an admin has assigned to this user (only viewable & setable by admins). When setting this, the value represents the number of points to add (or remove if a negative number is passed in). int 16.12
 cover_image * The user's cover image string 14.10
 deleted * Whether or not the user's account is deleted. True if deleted. boolean 14.10
 email * The email address of the user string 14.10
 email_excluded Whether or not the user has selected the "don't send me any community emails" option.
NOTE: You have to explicitly add this field to your LiQL (i.e. SELECT id, email_excluded FROM users) query to see it in the response.
boolean 14.10
 first_name The first name of the user string 14.10
 followers * The community members who follow the user. This is equivalent to "Friends" in the out-of-the-box UI. user 14.10
 following * The community members who the user follows. This is equivalent to the user's "friends" in the out-of-the-box UI. user 14.10
 href * The relative href to the user resource. This is the canonical path to the resource relative to the Community API root. string 14.10
 id * The unique ID of the user string 14.10
 images * Images uploaded by the user image 14.10
 kudos_given * The kudos given to the user by other community members. kudo 14.10
 kudos_received * The kudos received by the user from other community members. kudo 14.10
 language * The default language selected by the user string 14.10
 last_name The last name of the user string 14.10
 last_visit_time * The date/time the user was last active on the community datetime 14.10
 location The user's location string 14.10
 login * The login name of the user string 14.10
 messages * The messages (topics and replies) posted by the user message 14.10
 metrics * The metrics of the user activity user_metrics 14.10
 online_status * The status of the user: ONLINE or OFFLINE string 14.10
 personal_data The personal_data object associated with the user account. This object contains Personally Identifiable Information (PII) about the user. The personal_data object is accessed through this personal_data field on the user resource. The personal_data field must be queried specifically in a partial query on the users collection, filtered by user id or login in the WHERE clause. personal_datum 17.12
 public_images Images uploaded by the user that the user has made public. Both the image visibility level and the privacy level of the album containing the image must be public. image 14.12
 rank * The rank of the user in the community. If the users has not achieved a rank, the value is "-1". Ranks are configured in Community Admin > Users > Ranking > Rankings. rank 14.10
 registration_data * Registration information about the user registration_data 14.10
 reviews * Product reviews written by the user review 14.10
 roles * The roles that have been assigned to the user role 14.10
 settings setting 14.10
 signature_topics * Topics of interest associated with this user account that the user has selected to display to other community users. Returned only when the user has connected his or her Community profile with Profile Plus. signature_topic 17.5
 solutions_authored * The solutions authored by the user (i.e posts selected as an accepted solutions). message 14.10
 sso_id The user's SSO ID. Only administrators see this field. string 14.10
 threads_participated * The topic IDs of message threads in which the user has participated message 14.10
 topics * Topic messages (i.e the root message of a conversation) authored by the user message 14.10
 user_badges * When "Hide from user profile until earned" is unchecked/disabled in Community Admin, this field includes earned badges as well as visible but unearned badges. When "Hide from user profile until earned" is checked/enabled, this field includes only badges that the user has earned. "Hide from user profile until earned" is disabled by default. user_badge 14.10
 videos * Videos uploaded by the user video 14.10
 view_href * The fully-qualified href to the user resource in the Web UI. For example, the URI of the ViewProfile page. string 14.10
 web_page_url * The user's web page string 14.10
 

Functions

The following table lists the different functions you can use with this collection.

Function Notes Released
 albums.count(*) The count of albums associated with the user 14.10
SELECT albums.count(*) FROM users WHERE id = '31'
 count(*) The count of users. 14.10
SELECT count(*) FROM users WHERE online_status = 'online'
 following.count(*) The count of community members the user has added as a friend in the community 14.10
SELECT following.count(*), followers.count(*) FROM users WHERE id = '31'
 followers.count(*) The count of community members who have added the user as a friend in the community 14.10
SELECT following.count(*), followers.count(*) FROM users WHERE id = '31'
 images.count(*) The count of images uploaded by the user 14.10
SELECT images.count(*) FROM users
 kudos_received.sum(weight) The count of kudos a user has received 14.10
SELECT kudos_received.sum(weight) FROM users WHERE id = '31'
 kudos_given.sum(weight) The count of kudos given by a user 14.10
SELECT kudos_given.sum(weight) FROM users WHERE id = '31'
 messages.count(*) The count of messages (topics and replies) posted by the user 14.10
SELECT messages.count(*), solutions_authored.count(*) FROM users WHERE id = '31'
 public_images.count(*) The count of public images uploaded by the user 14.10
SELECT public_images.count(*) FROM users WHERE id = '31'
 roles.count(*) The count or roles applied to the user 14.10
SELECT roles, roles.count(*) FROM users WHERE id = '31'
 solutions_authored.count(*) The count of messages created by the user that are marked as accepted solutions 14.10
SELECT solutions_authored.count(*) FROM users WHERE id = '31'
 topics.count(*) The count of topic messages posted by the user 14.10
SELECT topics.count(*) FROM users
 videos.count(*) The count of videos uploaded by the user 14.10
SELECT videos.count(*) FROM users where id = '31'
 

Constraints

The following table lists the constraints supported by this collection in the WHERE clause of a LiQL query.

Constraint Notes Operators Released
 deleted_time Filter by a datetime range between which user accounts were closed/deleted. You must have General Data Protection Regulation (GDPR) enabled on your community to constrain by deleted_time.
Operator Datatype
<= date number
> date number
< date number
>= date number
18.3
SELECT id, count(*) FROM users where deleted_time > 2017-10-07T10:04:30 and deleted_time < 2018-10-07T10:04:30
 followers.id Filter by community members who have added the user as a friend.

When using this constraint, the only other constraints you can use in the WHERE clause are login (with '=' and LIKE constraints) and online_status (with 'online' as the value).
Operator Datatype
= string
14.10
SELECT id FROM users WHERE followers.id = '1'
 following.id Filter by community members that the user has added as a friend.

When using this constraint, the only other constraints you can use in the WHERE clause are login (with '=' and LIKE constraints) and online_status (with 'online' as the value).
Operator Datatype
= string
14.10
SELECT id FROM users WHERE following.id = '1'
 id Filter by user ID (support for using '>', '<', '>=', '<=' operators added in 19.8)
Operator Datatype
IN collection
<= string
> string
< string
= string
>= string
14.10
SELECT login FROM users WHERE id = '1'
SELECT login FROM users WHERE id IN ('1', '2')
SELECT login FROM users WHERE id > '20'
SELECT login FROM users WHERE id <= '50'
 kudos_given.sum(weight) Filter by the count of kudos given by a user
Operator Datatype
<= number
> number
< number
= number
>= number
14.10
SELECT id FROM users ORDER BY kudos_given.sum(weight) ASC 
SELECT id FROM users ORDER BY kudos_given.sum(weight) DESC
SELECT id FROM users WHERE kudos_given.sum(weight) > 0
SELECT id, login FROM users WHERE kudos_given.sum(weight) > 3
 kudos_received.sum(weight) Filter by the count of kudos received by a user
Operator Datatype
<= number
> number
< number
= number
>= number
14.10
SELECT id FROM users ORDER BY kudos_received.sum(weight) ASC 
SELECT id FROM users ORDER BY kudos_received.sum(weight) DESC
SELECT id FROM users WHERE kudos_received.sum(weight) > 0
SELECT id, login FROM users WHERE kudos_received.sum(weight) > 3
 last_visit_time Filter users by when they last visited the community.
Operator Datatype
<= date number
> date number
< date number
>= date number
19.8
ISO8601 format
SELECT id, login FROM users WHERE last_visit_time > 2019-08-19T16:23:23.000-07:00

milliseconds since epoch format
SELECT id, login FROM users WHERE last_visit_time > 1566239058288
 login Filter by user login name
Operator Datatype
IN collection
LIKE string
MATCHES collection string
= string
14.10
SELECT id FROM users WHERE login = 'admin'
SELECT email, id FROM users WHERE login = 'admin'
SELECT id FROM users WHERE login IN ('admin', 'SuzieH')
SELECT login FROM users ORDER BY login DESC
SELECT login FROM users WHERE login MATCHES 'john'
SELECT login FROM users WHERE login LIKE '%jane%'
 messages_contributed.id Filter by users who contributed to a message with the specified message ID.
Operator Datatype
= string
14.10
SELECT id FROM users WHERE messages_contributed.id = '315'
 online_status Supported for getting the count of user's online. Querying for offline users is not supported. This constraint cannot be combined with other constraints in the WHERE clause.
Operator Datatype
= string
15.11
SELECT count(*) FROM users WHERE online_status = 'online'
 rank.id Filter users by rank ID
Operator Datatype
IN collection
= string
14.10
SELECT login, rank.name, view_href FROM users WHERE rank.id = '2'
 rank.name Filter users by rank name
Operator Datatype
IN collection
= string
14.10
SELECT id, login FROM users WHERE rank.name = 'Community Manager' 
SELECT id FROM users WHERE rank.name IN ('Community Manager', 'Moderator')
 registration_data.registration_time Filter by the time a user registered as a Community member
Operator Datatype
<= date number
> date number
< date number
>= date number
19.8
ISO8601 format
SELECT id, login FROM users WHERE registration_data.registration_time > 2019-08-19T16:23:23.000-07:00

milliseconds since epoch format
SELECT id, login FROM users WHERE registration_data.registration_time > 1566239058288
 reviews.count(*) Filter by count of reviews posted by a user
Operator Datatype
<= number
> number
< number
= number
>= number
14.10
SELECT id, login FROM users WHERE reviews.count(*) > 0
 roles.id Filter by role(s) by role ID assigned
Operator Datatype
IN collection
= string
14.10
SELECT id, login FROM users WHERE roles.id='t:Administrator' 
SELECT id, roles FROM users WHERE roles.id IN ('c:Support:Category Admin', 't:Administrator')
 roles.name Filter by role(s) by role name assigned to a user
Operator Datatype
IN collection
= string
14.10
SELECT id, login FROM users WHERE roles.name='Administrator' 
SELECT id FROM users WHERE roles.name IN ('Administrator', 'Community Manager')
 signature_topics.id Filter by users with a specific signature_topic ID. Only supported when a user has his or her Community profile connected to Profile Plus.
Operator Datatype
IN collection
= string
17.5
SELECT id, login, view_href, href FROM users WHERe signature_topics.id = '640'
SELECT id, login, view_href, href FROM users WHERe signature_topics.id IN ('640', '33')
 sso_id Filter by user SSO ID (if the caller is allowed to see SSO IDs)
Operator Datatype
IN collection
= string
18.4
SELECT id, sso_id, login FROM users WHERE sso_id = '173463657'
SELECT id, sso_id, login FROM users WHERE sso_id IN ('173463657', '174343638')
 

Sorts

The following table lists the sorts supported by this collection in the ORDER BY clause of a LiQL query.

Sort Notes Released
 id Sort users by ID 14.10
SELECT id FROM users WHERE id < 1050 ORDER BY id DESC
 kudos_given.sum(weight) 14.10
SELECT id FROM users ORDER BY kudos_given.sum(weight) ASC 
SELECT id FROM users ORDER BY kudos_given.sum(weight) DESC
SELECT id FROM users WHERE kudos_given.sum(weight) > 0
SELECT id, login FROM users WHERE kudos_given.sum(weight) > 3
 kudos_received.sum(weight) 14.10
SELECT id FROM users ORDER BY kudos_received.sum(weight) ASC 
SELECT id FROM users ORDER BY kudos_received.sum(weight) DESC
SELECT id FROM users WHERE kudos_received.sum(weight) > 0
SELECT id, login FROM users WHERE kudos_received.sum(weight) > 3
 last_visit_time Sort users by date/time of last community visit 14.10
SELECT id FROM users WHERE last_visit_time > 1566239058288 ORDER BY last_visit_time DESC, id DESC
 login 15.5
SELECT id FROM users WHERE login = 'admin' 
SELECT email, id FROM users WHERE login = 'admin'
SELECT id FROM users WHERE login IN ('admin', 'SuzieH')
SELECT login FROM users ORDER BY login DESC
 public_images.count(*) 14.12
SELECT id, login, public_images.count(*) FROM users ORDER BY public_images.count(*) DESC
 registration_data.registration_time 14.10
SELECT id FROM users ORDER BY registration_data.registration_time ASC 
SELECT id, registration_data.registration_time FROM users ORDER BY registration_data.registration_time DESC
 reviews.count(*) 14.10
SELECT id, reviews FROM users ORDER BY reviews.count(*) DESC
 

Create (HTTP POST)

Create a user by issuing an HTTP POST to the /users collection.

Fields that are highlighted in grey and have an * after the field name are required

Field Notes Datatype Released
 avatar user_avatar 14.10
 biography string 14.10
 cover_image string 14.10
 email* string 14.10
 first_name string 14.10
 followers user 14.10
 following user 14.10
 last_name string 14.10
 login* string 14.10
 password string 14.10
 rank rank 14.10
 roles role 14.10
 sso_id string 14.10
 user_badges user_badge 14.10
 web_page_url string 14.10

Example POST:

Session Key
curl -X POST \ https://[COMMUNITY DOMAIN]/api/2.0/users \ -H 'content-type: application/json' \ -H 'li-api-session-key: [SESSION KEY]' \ -d '{ "data":{ "type":"user", "first_name":"samantha", "last_name":"pantha", "login":"sampantha", "email":"sampan@email.com", "password":"Pa55word!" } }'

OAuth
curl -X POST \ https://[COMMUNITY DOMAIN]/api/2.0/users \ -H 'content-type: application/json' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]' \ -d '{ "data":{ "type":"user", "first_name":"samantha", "last_name":"pantha", "login":"sampantha", "email":"sampan@email.com", "password":"Pa55word!" } }'

If you want to find out if a caller is allowed to make this call, you can call the /allowed endpoint for this resource.

Example /allowed call:

Session Key
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/allowed?method=post&path=%2Fusers' \ -H 'li-api-session-key: [SESSION KEY]'

OAuth
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/allowed?method=post&path=%2Fusers' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

 

Update (HTTP PUT)

Edit an existing user by issuing an HTTP PUT to the user you want to edit.

Field Notes Datatype Released
 avatar user_avatar 14.10
 biography string 14.10
 bonus_points int 16.12
 cover_image string 14.10
 email string 14.10
 email_excluded boolean 14.10
 first_name string 14.10
 last_name string 14.10
 login string 14.10
 personal_data personal_datum 17.12
 rank rank 14.10
 web_page_url string 14.10

Example PUT:

Session Key
curl -X PUT \ https://[COMMUNITY DOMAIN/api/2.0/users/42 \ -H 'content-type: application/json' \ -H 'li-api-session-key: [SESSION KEY]' \ -d '{ "data": { "type": "user", "biography": "I am the walrus.", "bonus_points": 5, "rank": { "id": "4" } } }'

OAuth
curl -X PUT \ https://[COMMUNITY DOMAIN]/api/2.0/users/42 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]' \ -d '{ "data": { "type": "user", "biography": "I am the walrus.", "bonus_points": 5, "rank": { "id": "4" } } }'

If you want to find out if a caller is allowed to make this call, you can call the /allowed endpoint for this resource.

Example /allowed call:

Session Key
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/allowed?method=put&path=%2Fusers/42' \ -H 'li-api-session-key: [SESSION KEY]'

OAuth
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/allowed?method=put&path=%2Fusers/42' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

 

Delete (HTTP DELETE)

You can delete this resource by making an HTTP DELETE call to the collection.

Example DELETE:

Session Key
curl -X DELETE \ https://[COMMUNITY DOMAIN]/api/2.0/users/63 \ -H 'li-api-session-key: [SESSION KEY]'

OAuth
curl -X DELETE \ https://[COMMUNITY DOMAIN]/api/2.0/users/63 \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

 

Subcollections

This collection contains the subcollections described below.

 

badges

This subcollection supports the HTTP actions described below.

 

Read (HTTP GET)

Released
19.6

To read this resources, make an HTTP GET call to the collection followed by a slash ("/") and the ID of the resource.

Example GET:

Session Key
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/13/badges/' \ -H 'li-api-session-key: [SESSION KEY]'

OAuth
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/13/badges/' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

 

Create (HTTP POST)

Released
19.6

Reassign a badge to a user with a POST call to the /users/:userId/badges sub-collection.

Example POST:

Session Key
curl -X POST \ https://[COMMUNITY DOMAIN]/api/2.0/users/13/badges \ -H 'Content-Type: application/json' \ -H 'li-api-session-key: [SESSION KEY]' \ -d '{ "data" : { "type": "badge", "id": "1" } }'

OAuth
curl -X POST \ https://[COMMUNITY DOMAIN]/api/2.0/users/13/badges \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]' \ -d '{ "data" : { "type": "badge", "id": "1" } }'

 

Delete (HTTP DELETE)

Released
19.6

You can delete this resource by making an HTTP DELETE call to the collection.

Example DELETE:

Session Key
curl -X DELETE \ https://[COMMUNITY DOMAIN]/api/2.0/users/13/badges/1 \ -H 'Content-Type: application/json' \ -H 'li-api-session-key: [SESSION KEY].'

OAuth
curl -X DELETE \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/13/badges/1' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

 

inbox_notes

This subcollection supports the HTTP actions described below.

 

Read (HTTP GET)

Released
16.5

To read this resources, make an HTTP GET call to the collection followed by a slash ("/") and the ID of the resource.

Example GET:

Session Key
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/31/inbox_notes/8' \ -H 'li-api-session-key: [SESSION KEY]'

OAuth
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/31/inbox_notes/8' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

 

Update (HTTP PUT)

Released
16.5

Mark an inbox note read or unread by issuing an HTTP PUT to the /users/:userId/inbox_notes sub-collection.

Field Notes Datatype Released
 is_read Whether or not the note has been read. boolean 16.5
Example PUT:

Session Key
curl -X PUT \ https://[COMMUNITY DOMAIN/api/2.0/users/5652/inbox_notes \ -H 'content-type: application/json' \ -H 'li-api-session-key: [SESSION KEY]' \ -d '{ "data": { "type": "inbox_note", "is_read": true } }'

OAuth
curl -X PUT \ https://[COMMUNITY DOMAIN]/api/2.0/users/5652/inbox_notes \ -H 'content-type: application/json' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]' \ -d '{ "data": { "type": "inbox_note", "is_read": true } }'

 

Delete (HTTP DELETE)

Released
16.5

You can delete this resource by making an HTTP DELETE call to the collection.

Example DELETE:

Session Key
curl -X DELETE \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/32/inbox_notes/12' \ -H 'li-api-session-key: [SESSION KEY]'

OAuth
curl -X DELETE \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/32/inbox_notes/12' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

 

outbox_notes

This subcollection supports the HTTP actions described below.

 

Read (HTTP GET)

Released
16.5

To read this resources, make an HTTP GET call to the collection followed by a slash ("/") and the ID of the resource.

Example GET:

Session Key
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/31/outbox_notes/19' \ -H 'li-api-session-key: [SESSION KEY]'

OAuth
curl -X GET \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/31/outbox_notes/19' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

 

Delete (HTTP DELETE)

Released
16.5

You can delete this resource by making an HTTP DELETE call to the collection.

Example DELETE:

Session Key
curl -X DELETE \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/32/outbox_notes/12' \ -H 'li-api-session-key: [SESSION KEY]'

OAuth
curl -X DELETE \ 'https://[COMMUNITY DOMAIN]/api/2.0/users/32/outbox_notes/12' \ -H 'Authorization: Bearer [TOKEN]' \ -H 'client-id: [CLIENT ID]'

Top