REST API:user Resource

Performs actions on User records via the REST API

Access Permissions

Users that have the Access Control/User Management permission can use this Resource.

Determine if a Valid Session is in Progress

Determine if the current session is valid.

Method: GET

URI: https://{yourDomain}/networking/rest/user/isSessionValid

Response

:

<platform>
    <user>
        <is_session_valid>true</is_session_valid>
    </user>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Get Information about the Logged-In User

Gets information about the logged in user.

Method: GET

URI: https://{yourDomain}/networking/rest/user/info

Response: The same information returned by the query to Get a User Record: first name, last name, employee number, and so on.

Get a User Record

Retrieves data for the specified user.

Method

GET

URI

https://{domain}/networking/rest/user/{user_id}

Response

<platform>
    <user>
        <phone/>
        <street/>
        <city/>
        <first_name>John</first_name>
        <username>userA@gmail.com</username>
        <single_sign_on>0</single_sign_on>
        <community_user_id/>
        <auto_generated_community_user_record>0</auto_generated_community_user_record>
        <employee_number/>
        <fax/>
        <user_type>P</user_type>
        <country/>
        <last_login>1236041001000</last_login>
        <time_zone>12</time_zone>
        <email>userA@gmail.com</email>
        <company>CompanyA</company>
        <last_name>Smith</last_name>
        <date_last_password_change>2010-11-12T13:14:15Z</date_last_password_change>
        <active>1</active>
        <language>en</language>
        <mobile/>
        <state/>
        <date_created>2010-11-12T13:14:15Z</date_created>
        <id>16016a880c064ad1ba92115424851462</id>
        <title/>
        <reports_to type="" 
           uri="https://{domain}/rest/user/123qwe456rty"
           displayValue="John Smith">123qwe456rty</reports_to>
        <zip/>
        <alias/>
        <date_modified>2010-11-12T13:14:15Z</date_modified>
        <object_id>USER</object_id>
        <customer_language>en</customer_language>
        <customerId>123223323</customerId>
        <created_id type="" 
          uri="https://{domain}/networking/rest/user/1524089492" 
          displayValue="Peter Parker">1424089492</created_id>
        <modified_id type="" 
          uri="https://{domain}/networking/rest/user/1524089492" 
          displayValue="Peter Parker">1424089492</modified_id>
        <full_name>John Smith</full_name>
    </user>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Dynamic Search

Returns the fields requested by a dynamic search based on number of records, offset, sort column, sort order, and specified criteria.

Method

GET

URI

https://{domain}/networking/rest/user?{query_parameters}

Sample Search: ?fieldList=name,id & filter=name contains 'smith' & sortby='id'; (Field names are in the Fields section.)

Query Parameters

fieldList - A comma-separated list of field names to retrieve

The asterisk (*) wildcard specifies all fields
{fieldname} specifies an individual field (e.g. name)

(Use the REST API:field Resource to get a complete list of fields.)

For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
alias.* specifies all fields in the aliased object.

filter - Filtering criteria to filter the records

For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

pageSize - Number of records to retrieve from the result set in order to make a "page".
page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

getTotalRecordCount returns the number of total records.
Causes the following structure to be returned, where N is the total number of records:

<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>

sortBy - Field name for primary sort
Ex: &sortBy=name
sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
Ex: &sortOrder=desc
sortBy2 - Field name for secondary sort
sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs

Response

<platform>
    <record>
        <phone/>
        <street/>
        <state/>
        <date_created>2010-11-12T13:14:15Z</date_created>
        <city/>
        <id>1424089492</id>
        <first_name>Admin</first_name>
        <username>admin@longjump.com</username>
        <title/>
        <primary_team>1</primary_team>
        <reports_to type="" uri="" displayValue=""/>
        <zip/>
        <employee_number/>
        <date_modified>2010-11-12T13:14:15Z</date_modified>
        <object_id>USER</object_id>
        <last_login>1267756624000</last_login>
        <country/>
        <created_id type="" 
	    uri="https://{domain}/networking/rest/user/5" 
	    displayValue="LongJump Admin">5</created_id>
        <time_zone>12</time_zone>
        <modified_id type=""
  	    uri="https://{domain}/networking/rest/user/16016a880c064ad1ba92115424851462" 
	    displayValue="Sheela Sarva">16016a880c064ad1ba92115424851462</modified_id>
        <email>demo@longjump.com</email>
        <last_name>LongJump</last_name>
        <active>1</active>
        <role_in_primary_team>1</role_in_primary_team>
    </record>

    <record>
        <phone/>
        <street/>
        <state/>
        <date_created>2010-11-12T13:14:15Z</date_created>
        <city/>
        <id>151b28b700dc45abbb12b65ea451fc97</id>
        <first_name>Me</first_name>
        <username>myusername</username>
        <title/>
        <primary_team>1</primary_team>
        <reports_to type="" uri="" displayValue=""/>
        <zip/>
        <employee_number/>
        <date_modified>2010-11-12T13:14:15Z</date_modified>
        <object_id>USER</object_id>
        <last_login/>
        <country/>
        <created_id type="" 
	    uri="https://{domain}/networking/rest/user/123223323" 
	    displayValue="Admin LongJump">123223323</created_id>
        <time_zone>12</time_zone>
        <modified_id type="" 
	    uri="https://{domain}/networking/rest/user/123223323" 
	    displayValue="Admin LongJump">123223323</modified_id>
        <email>myusernamecp@gmail.com</email>
        <last_name>Mostly</last_name>
        <active>1</active>
        <role_in_primary_team>1</role_in_primary_team>
    </record>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
    <recordCount>2</recordCount>
</platform>

See also: REST API:Error Codes

Add a User Record

Adds a user record

Method

POST

URI

https://{domain}/networking/rest/user/

Request

<platform>
    <user>
        <phone/>
        <street/>
        <city/>
        <first_name>John</first_name>
        <username>userA@gmail.com</username>
        <single_sign_on>0</single_sign_on>
        <employee_number/>
        <fax/>
        <country/>
        <time_zone>12</time_zone>
        <email>userA@gmail.com</email>
        <company>CompanyA</company>
        <last_name>Smith</last_name>
        <active>1</active>
        <language>en</language>
        <mobile/>
        <state/>
        <title/>
        <notify_by_email>1</notify_by_email>
        <reports_to>151b28b700dc45abbb12b65ea451fc97</reports_to><zip/>
        <alias/>
        <customer_language>en</customer_language>
        <team_id>1</team_id>  // only required on add 
        <role_id>3</role_id>  // only required on add
    </user>
</platform>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>1818437421</id>      // id of the user that was added
    </message>
</platform>

See also: REST API:Error Codes

Update a User Record

Updates data for the User specified in the URI.

Method: PUT

URI: https://{domain}/networking/rest/user/{recordId}
Request: Field elements are optional. If a field is missing, existing data in that field is unaffected. If a field is specified, but empty, any existing data in that field is deleted.

<platform>
    <user>
        <phone/>
        <street/>
        <city/>
        <first_name>John</first_name>
        <username>userA@gmail.com</username>
        <single_sign_on>0</single_sign_on>
        <employee_number/>
        <fax/>
        <country/>
        <time_zone>12</time_zone>
        <email>userA@gmail.com</email>
        <company>CompanyA</company>
        <last_name>Smith</last_name>
        <active>1</active>
        <language>en</language>
        <mobile/>
        <state/>
        <title/>
        <reports_to>151b28b700dc45abbb12b65ea451fc97</reports_to>
	<zip/>
        <alias/>
        <customer_language>en</customer_language>        
    </user>
</platform>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>1818437421</id>      // id of the user that was updated
    </message>
</platform>

See also: REST API:Error Codes

Update (Reset) Password for a User

Change the password to a new or existing user.

Method

POST

Example

URI

https://{domain}/networking/rest/user/operation/updatePassword

Request

<platform>
    <user>
        <id>da80488c7e8d4f5a83c66a3bb2590295</id>
        <password>abc</password>
        <longjump_reset_user>1</longjump_reset_user>
        <skip_email>1</skip_email>
    </user>
</platform>

longjump_reset_user

0 = Password field is required. User is not required to change it at next log in. (default)
1 = Password field does not have to be specified. System automatically generates a new, random password. User is required to change it at next log in.

skip_email

This field is only used for a new user.

0 = Send the Reset Password Email Message notification. (default)
1 = No message is sent.

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>        
    </message>
</platform>

See also: REST API:Error Codes

Change Password for the Current User

Change the password for the current user.

Method: POST
URI: https://{domain}/networking/rest/user/operation/changePassword

Request

<platform>
    <user>
        <old_password>world44</old_password>
        <password>pass123</password>
    </user>
</platform>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>        
    </message>
</platform>

See also: REST API:Error Codes

Delete a User Record

Deletes a User record

Method

DELETE

URI

https://{domain}/networking/rest/user/{recordId}

Response

<platform>
    <message>
	<code>0</code>
	<description>Success</description>		
    </message>
</platform>

See also: REST API:Error Codes

Fields

Note: In this object, Boolean fields accept either 1/0 or TRUE/FALSE

Name	Type	Attribute	Description	Additional Information
id	String	Read Only	Record Identifier
first_name	String	Editable on Add/Update
last_name	String	Editable on Add/Update
company	String	Editable on Add/Update
title	String	Editable on Add/Update
time_zone	Integer	Editable on Add/Update		See: Time Zone Codes
date_format	String	Editable on Add/Update		See: Date/Time Formats
reports_to	String	Editable on Add/Update
employee_number		Editable on Add/Update
language	String	Editable on Add/Update		Two letter language code that is available to tenant (ex: 'en', 'es', 'hi')
email	String	Editable on Add/Update
username	String	Editable on Add/Update
password	String	Editable on Add/Update	Password used to login	Password is required for Login Password is optional when creating a new user via REST API (Add a User) If password is not provided, a temporary password is generated and sent to the user/tenant via email Learn more: Manage Email Templates - Forgot Reset Password Email
active	Boolean	Editable on Add/Update
single_sign_on	Boolean	Editable on Add/Update
team_id	Integer	Writable on Add only
role_id	Integer	Writable on Add only
phone	String	Editable on Add/Update
mobile	String	Editable on Add/Update
fax	String	Editable on Add/Update
street	String	Editable on Add/Update
city	String	Editable on Add/Update
state	String	Editable on Add/Update
zip	String	Editable on Add/Update
country	String	Editable on Add/Update
notify_by_email	Boolean	Can be specified on Add/Update	Send the Welcome email message	When enabled, a notification email is sent (containing the username, welcome and login information) when a new user is added. Default is 1 (email is sent automatically on new user creation) This value is not stored in the database, and is not returned by a GET.
federation_id	String	Read Only	Used in SAML authentication, if SAML is enabled
force_password_change_on_login	Boolean	Editable on Add/Update	Force a password change action on first-time login	When enabled, the User is prompted to change the password when logging in for the first time Default is 1 (new user is forced to change password on first login)
last_login	Date	Read Only	Date and time of last login	UTC Format
date_last_password_change	date	Read Only	Date and time of last password change	UTC Format
customer_language	String	Read Only	Default Language, specified in My Information
full_name	String	Read Only	Full name of the user
date_created	Date	Read Only		UTC Format
created_id	Lookup	Read Only
date_modified	Date	Read Only		UTC Format
modified_id	Lookup	Read Only
role		Read Only
community_user_id	String	Read Only	User's ID in the community
auto_generated_community_user_record	Boolean	Read Only	<true> for the initial admin user and any other user IDs automatically generated for the community
user_type	String	Read Only	User type: Platform user (P) or Site User (S)	Platform Users are licensed Users who have a Login (to a Tenant, which is provided by an ISV or MSP Platform Users can be automatically included as Site Users (Learn More: Configure a Community Tenancy) Site Users are registered through a Site
alias	String	Editable on Add/Update	User's alias in the community
sso_type	Integer	Read Only	Type of single sign on: 1 - Delegated Authentication 2 - SAML	See: Single Sign On
tenant_id	String	Read Only		Blank when logged in as normal user in a non-community tenant. The ID of the host tenant, when logged in as a community user.
tenant_user_id	String	Read Only
customerId	String	Read Only	Customer ID	The ID of the tenant where the user is logged in: The host tenant ID, when logged in as a user for a normal (non-community) tenant. The ID of the the community tenant, when logged in as a community user.
custom field			User Fields	User can add fields of various type, including text, date, time, etc.

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools

REST API:user Resource

Contents

Access Permissions

Determine if a Valid Session is in Progress

Get Information about the Logged-In User

Get a User Record

Dynamic Search

Add a User Record

Update a User Record

Update (Reset) Password for a User

Change Password for the Current User

Delete a User Record

Fields