CHAPTER 7
Users
Use the Users endpoint to manage basic aspects of Social Studio user accounts.
In this chapter ...
•
Retrieve Users
•
Retrieve User
•
Create User
•
Update User
•
Reset Password
•
Modify Password
Retrieve a User
GET /v3/users/{id}
cURL Example
curl -X GET -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e"
'https://api.socialstudio.radian6.com/v3/users/me'
Create a User
POST /v3/users
cURL Example
curl -X POST -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e"
-H "Content-Type: application/json" -d ' {
"title": "API User",
"username": "APIUser",
"displayName": "API User",
"email": "[email protected]",
"timeZone": "Europe/London",
"enabled": true,
"avatarURL": null,
"userRoleId": 6,
"orgRoleId": 1,
"languageId": 1,
"clientId": 1
}' 'https://api.socialstudio.radian6.com/v3/users'
38
Users Retrieve Users
Retrieve Users
This method retrieves information for all users within an account
/v3/users
HTTP Method
GET
Request Parameters
None
Query Parameters
*q* - string value including characters to search for in title (minimum of 3 characters)
*enabled* - boolean value indicating whether to retrieve only active users
*true* - string value indicating return only active users
*false* - string value indicating return all users
*limit* - integer value indicating number of results to return (defaults to 100,000)
*offset* - integer value indicating result to start with (defaults to 0)
Sample Request
GET /v3/users
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "3339",
"title": "Admin",
"username": "admin",
"displayName": "Admin",
"email": "[email protected]",
"timeZone": "America/Goose_Bay",
"enabled": true,
"orgRoleId": 1,
"languageId": 1,
"createdDate": "2014-05-09T03:00:00Z",
"internalUserAvatarUrl": null,
"userAvatarUrl": null,
"clientId": 1
},
…
39
Users Retrieve User
}
],
"meta": {
"totalCount" : 52
}
*id* - integer value indicating unique ID for user
*title* - string value including name fo users
*username* - string value including network username for user
*email* - string value including email address for user
*timeZone* - string value indicating location for user
*enabled* - boolean value indicating user status
*true* - string value indicating enabled
*false* - string value indicating disabled user
*orgRoleId* - integer value indicating role for user within organization
*languageId* - integer value indicating language used by user
*createdDate* - timestamp value indicating when system created user
*internalUserAvatarUrl* - string value indicating location of avatar image file for internal use
*userAvatarUrl* - string value indicating location of avatar image file
*clientId* - integer value indicating client ID for specific user
Retrieve User
This method retrieves information for a specified user within an account
/v3/users/{id}
HTTP Method
GET
Request Parameters
*id* - integer value indicating unique ID for user (you may also use the *me* shorthand in place of this value)
Sample Request
GET /v3/users/{id}
Sample Response
A successful call returns the following response:
{
"data": [
{
40
Users Create User
}
"id": "3339",
"title": "Admin",
"username": "admin",
"displayName": "Admin",
"email": "[email protected]",
"timeZone": "America/Goose_Bay",
"enabled": true,
"orgRoleId": 1,
"languageId": 1,
"createdDate": "2014-05-09T03:00:00Z",
"internalUserAvatarUrl": null,
"userAvatarUrl": null,
"clientId": 1
},
…
],
"meta": {
"totalCount" : 1
}
*id* - integer value indicating unique ID for user
*title* - string value including name fo users
*username* - string value including network username for user
*email* - string value including email address for user
*timeZone* - string value indicating location for user
*enabled* - boolean value indicating user status
*true* - string value indicating enabled
*false* - string value indicating disabled user
*orgRoleId* - integer value indicating role for user within organization
*languageId* - integer value indicating language used by user
*createdDate* - timestamp value indicating when system created user
*internalUserAvatarUrl* - string value indicating location of avatar image file for internal use
*userAvatarUrl* - string value indicating location of avatar image file
*clientId* - integer value indicating client ID for specific user
Create User
This method creates a new user within a Social Studio tenant.
/v3/users
HTTP Method
POST
Request Parameters
None
41
Users Create User
JSON Parameters
*username* - string value including network username for user (required)
*displayName* - string value displaying user name (required)
*email* - string value indicating email address for user (required)
*timeZone* - string value indicating location for user (required)
*enabled* - boolean value indicating user status (required)
*true* - string value indicating enabled (required)
*false* - string value indicating disabled user (required)
*orgRoleId* - integer value indicating role for user within organization (required)
*1* - org_super_user
*2* - org_full_user
*3* - org_basic_user
*7* - org_admin_only
*internalUserAvatarUrl* - string value indicating location of avatar image file for internal use
*userAvatarUrl* - string value indicating location of avatar image file
*languageId* - integer value indicating language used by user
Request Parameter Example
POST /v3/users
Sample Request
POST /v3/users
{
"username": "[email protected]",
"displayName": "Matt Jones",
"email": "[email protected]",
"timeZone": "Europe/London",
"enabled": true,
"avatarURL":
"http://a0.twimg.com/profile_images/1284202467/laptop-vector-model-122171296611479Nq0_normal.png",
"languageId": 1,
"internalUserAvatarUrl":
"http://socialstudio.s3.amazonaws.com/avatars/ad816b59936d93dc3ec36a43e15cbb8c"
}
Sample Response
A successful call returns a 201 code, indicating a successful creation.
A internal server error occuring during the call returns a 500 code. Try your call again later.
42
Users Update User
Update User
This method retrieves information for a specified user within a Social Studio tenant.
/v3/users/{id}
HTTP Method
PUT
Request Parameters
*id* - integer value indicating unique ID for user (you may also use the *me* shorthand in place of this value)
JSON Parameters
*username* - string value including network username for user (required)
*displayName* - string value displaying user name (required)
*email* - string value indicating email address for user (required)
*timeZone* - string value indicating location for user (required)
*enabled* - boolean value indicating user status (required)
*true* - string value indicating enabled (required)
*false* - string value indicating disabled user (required)
*orgRoleId* - integer value indicating role for user within organization (required)
*1* - org_super_user
*2* - org_full_user
*3* - org_basic_user
*7* - org_admin_only
*internalUserAvatarUrl* - string value indicating location of avatar image file for internal use
*userAvatarUrl* - string value indicating location of avatar image file
*languageId* - integer value indicating language used by user
Request Parameter Example
PUT /v3/users/{id}
Sample Request
PUT /v3/users/{id}
{
"username": "[email protected]",
"displayName": "Matt Jones",
"email": "[email protected]",
"timeZone": "Europe/London",
43
Users Reset Password
"enabled": true,
"avatarURL":
"http://a0.twimg.com/profile_images/1284202467/laptop-vector-model-122171296611479Nq0_normal.png",
"languageId": 1,
"internalUserAvatarUrl":
"http://socialstudio.s3.amazonaws.com/avatars/ad816b59936d93dc3ec36a43e15cbb8c"
}
Sample Response
A successful call returns a 204 No Content code, indicating a successful update.
A call referencing an invalid ID returns a 404 Not Found code. Ensure your call uses the correct ID.
A internal server error occuring during the call returns a 500 code. Try your call again later.
Reset Password
This method resets the password for an internal user account. A successful call also sends an email message (from [email protected]) containing a link the user can click to set a new password value. This call requires administrative privileges.
/v3/users/{userId}/password?action=reset
HTTP Method
POST
Request Parameters
*userId* - integer value indicating unique ID for user (also accepts me shorthard)
Request Parameters Example
POST /v3/users/{id}/password?action=reset
Sample Request
POST /v3/users/12345/password?action=reset
Sample Response
A successful call returns a 204 No Content code, indicating a successful update.
A call referencing an invalid ID returns a 404 Not Found code. Ensure your call uses the correct ID.
A internal server error occurring during the call returns a 500 code. Try your call again later.
44
Users
Modify Password
This method triggers a password reset operation for a user
/users/{id}/password
HTTP Method
POST
Request Parameters
None
Sample Request
POST /users/1/password?action=change
Modify Password
45
