API Documentation

In-depth reference documentation for iQmetrix API's.

NAV

OVERVIEW

The User Manager API allows you to manage User accounts for your Company.

To learn more about User Manager, see User Manager.

BASE URLS

Demo: https://usermanagerdemo.iqmetrix.net/v1
Production: https://usermanager.iqmetrix.net/v1

RESOURCES

User

A User represents an account that can be used to perform actions on your data within iQmetrix APIs.

{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "john@kentel.com",
    "Email": "john@kentel.com",
    "ParentEntityId": 17,
    "ParentEntityName": "Kentel",
    "CorrelationId": "SM175",
    "JobTitle": "Sales Clerk",
    "Picture": {
        "Id": "1fa5ae34-1578-44a0-9b21-b9be14559b9f",
        "Href": "https://ams.blob.core.windows.net/assets/1fa5ae34-1578-44a0-9b21-b9be14559b9f.jpg",
        "Height": 480,
        "Width": 640,
        "Md5Checksum": "d3fc6e526f00a56c9dacd503eff5fc93",
        "Name": "sample.jpg",
        "MimeType": "image/jpeg"
    },
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
   "Attributes": {
        "Department": "Sales",
        "BadgeId": 894523
    },
    "Version": 1
}
Name Description
Id (Integer) The identifier of the user.
UserName (String) The unique name for identifying this user.
Email (String) The user’s email address. Must be unique. (No notifications are sent to this address.)
FirstName (String) The first name of the user.
LastName (String) The last name of the user.
ParentEntityId (Integer) The identifier of the company to which the user belongs.
ParentEntityName (String) Read-only. The name of the company corresponding to the parent entity identifier.
CorrelationId (String) For internal use. Used internally to correlate the record with other records in RQ.
ClientUserId (String) The identifier of the user in the client’s external system.
Picture (Picture) A reference to a media asset that is a photo of the user.
JobTitle (String) The job title of the user.
Address (Address) The address of the user.
PhoneNumbers (Array[PhoneNumber]) The phone numbers for the user.
Attributes (Key-Value Pairs) A property for storing additional information about a user; for example, badge number or department. Information is stored as an array of key-value pairs.
Version (Integer) Read-only. The latest revision number of this resource. This field is used to prevent collisions in updating the resource.
IsActive (Boolean) Read-only. Indicates whether the user’s account is enabled (true) or disabled (false)). Disabled users cannot log on or obtain access tokens, and do not appear in searches.

Address

{
    "AddressLine1": "1432 Merry View Road",
    "AddressLine2": "",
    "City": "Big Windy",
    "StateCode": "ON",
    "CountryCode": "CA",
    "Zip": "A1A2B2"
}
Name Description
AddressLine1 (String) Line 1 of the street address.
AddressLine2 (String) Line 2 of the street address.
City (String) The city for this address.
StateCode (String) The ISO 3166-2 alpha-2 Region code for the state or province where this address resides. To see a list of these codes, see Getting All Countries.
CountryCode (String) The ISO 3166-2 alpha-2 code for the country where this address is located. To see the list of these codes, see Getting All Countries.
Zip (String) The postal code/zip code for this address.

LockReason

On occasion, you might need to lock a user. The LockReason resource lets you configure a set of reasons why you might do so. Each client can define their own set of lock reasons: you assign an identifier, a name and a description for the reason. The description is then displayed to the user when the attempt to log on. Examples are:

{
    "Id": 14,
    "Name": "PaperworkNotDone",
    "Description": "Your account has been locked because the paperwork has not been completed. Please contact your supervisor."
}
Name Description
Id (Integer) An identifier for the lock reason.
Name (String) A name for lock reason.
Description (String) The message that will be displayed to the user when they are locked out.

PhoneNumber

{
    "Number": "6135550127",
    "Extension": "5532",
    "Type": "Work"
}
Name Description
Number (String) The user’s phone number. Minimum 7 characters.
Extension (String) The user’s extension.
Type (String) The type of phone number; for example, work, home, mobile, etc.

Picture

A Picture resource describes a media asset used to store a user’s photograph.

{
    "Id": "1fa5ae34-1578-44a0-9b21-b9be14559b9f",
    "Href": "https://ams.blob.core.windows.net/assets/1fa5ae34-1578-44a0-9b21-b9be14559b9f.jpg",
    "Height": 480,
    "Width": 640,
    "Md5Checksum": "d3fc6e526f00a56c9dacd503eff5fc93",
    "Name": "sample.jpg",
    "MimeType": "image/jpeg"
}
Name Description
Id (GUID) System-generated. The identifier of the asset.
Href (String) The absolute path to the resource.
Height (String) The height of the image, in pixels.
Width (String) The width of the image, in pixels.
Md5Checksum (String) The generated checksum for the asset.
Name (String) The name of the asset.
MimeType (String) The mime type of the asset.

REQUESTS

Add a User

Use this request to create a user.

Email notifications are sent to the email specified for the user account when the account is created.

Request

POST /users

Example Request

POST /users
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

{
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "Picture": {
        "Id": "1fa5ae34-1578-44a0-9b21-b9be14559b9f",
        "Href": "https://ams.blob.core.windows.net/assets/1fa5ae34-1578-44a0-9b21-b9be14559b9f.jpg",
        "Height": 480,
        "Width": 640,
        "Md5Checksum": "d3fc6e526f00a56c9dacd503eff5fc93",
        "Name": "sample.jpg",
        "MimeType": "image/jpeg"
    },
    "ClientUserId": "132",
    "Email": "johnb@kentel.com",
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 17,
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Version": 1
}

Path Parameters

None.

Request Parameters

Name Description
UserName (String) Required. The unique name for identifying this user.
Email (String) Required. The user’s email address. Must be unique. A notification is sent to this account when the account is created.
FirstName (String) Required. The first name of the user.
LastName (String) Required. The last name of the user.
ParentEntityId (Integer) Required. The identifier of the company to which the user belongs.
ClientUserId (String) Optional. The identifier of the user in the client’s Retail Management System.
JobTitle (String) Optional. The job title of the user.
Address (Address) Optional. The address of the user.
PhoneNumbers (Array[PhoneNumber]) Optional. The phone numbers for the user.
Attributes (Key-Value Pairs) Optional. A property for storing additional information about a user; for example, badge number or department. Information is stored as an array of key-value pairs.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "ClientUserId": "132",
    "CorrelationId": "SM175",
    "Email": "johnb@kentel.com",
    "IsActive": true,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 17,
    "ParentEntityName": "Kentel",
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": null,
    "Version": 1
}

A successful request returns a 200 (OK) response with the updated user record represented as User resource. For a description of parameters defined for the User resource, see User.

Import a User from Another System

Use this request to import a user from an external system; for example, an identity management system.

Note that email notifications are NOT sent to user accounts when users are imported.

If no password is supplied, the user will not have a password configured. As a result, the user will be unable to log on or obtain an access token, and will be unable to set their password themselves. Note that the system does NOT allow a user with no configured password to specify it at first login. As good practice, provide at least a temporary password

Request

POST /users/importExisting

Example Request

POST /users/importExisting
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

{
    "UserName": "johnb@kentel",
    "Password": "samplepassword",
    "Email": "johnb@kentel.com",
    "FirstName": "John",
    "LastName": "Bates",
    "ParentEntityId": 1,
    "ClientUserId": "132",
    "CorrelationId": "SM175",
    "JobTitle": "Sales Clerk",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ]
}

Path Parameters

None.

Request Parameters

Name Description
UserName (String) Required. The unique name for identifying this user.
Password (String) Optional, but strongly recommended. If password is not supplied, the user will be unable to log on or obtain an access token, and will be unable to set their password themselves. Note that the system does NOT allow a user with no configured password to specify it at first login.
Email (String) Optional. The user’s email address. Must be unique.
FirstName (String) Optional. The first name of the user.
LastName (String) Optional. The last name of the user.
ParentEntityId (Integer) Required. The identifier of the company to which the user belongs.
ClientUserId (String) Optional. The identifier of the user in the client’s system.
JobTitle (String) Optional. The job title of the user.
Address (Address) Optional. The address of the user.
PhoneNumbers (Array[PhoneNumber]) Optional. The phone numbers for the user.
Attributes (Key-Value Pairs) Optional. A property for storing additional information about a user; for example, badge number or department. Information is stored as an array of key-value pairs.

Response

Example Response

HTTP 201 Content-Type: application/json
{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "ClientUserId": "132",
    "Email": "johnb@kentel.com",
    "IsActive": true,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 17,
    "ParentEntityName": "Kentel",
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": null,
    "Version": 1
}

A successful request returns a 200 (OK) response with the imported user information represented as User resource. For a description of parameters defined for the User resource, see User.

Bulk Create Users

Use this request to create multiple users, with security roles, from an Excel spreadsheet.

Request

POST /users/companies({CompanyId})/bulkCreateUsers

Example Request

PUT /users/companies(41426)/bulkCreateUsers
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=""; filename="BulkCreateUsers.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Path Parameters

None.

Excel Sheet Schema

An Excel file (.xlsx or .xls) with a worksheet named Users and the columns listed below, ordered as given.

Name Description
UserName (String) Required. The unique name for identifying this user.
Email (String) Required. The user’s email address. Must be unique.
FirstName (String) Optional. The first name of the user.
LastName (String) Optional. The last name of the user.
JobTitle (String) Optional. The job title of the user.
HomePhoneNumber (PhoneNumber) Optional. The home phone number for the user.
CellPhoneNumber (PhoneNumber) Optional. The mobile phone number for the user.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "ClientUserId": "132",
    "CorrelationId": "SM175",
    "Email": "johnb@kentel.com",
    "IsActive": true,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 17,
    "ParentEntityName": "Kentel",
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": null,
    "Version": 1
}

A successful request returns a 200 (OK) response with an array of user records for the newly created users, represented as User resources. For a description of parameters defined for the User resource, see User.

If Excel file validation fails, a collection of details is returned containing details about errors that occurred, giving the row number and column name for each error, as in the following example.

HTTP 400 - Bad Request
{
	"Message": "Import Failed",
	"Description": "",
	"Details": [
		{
			"RowNumber": 2,
			"ColumnName": "User Name",
			"Message": "Username already exists"
		},
		{
			"RowNumber": 2,
			"ColumnName": "Email Address",
			"Message": "Email already exists"
		}
	]
}

Update a User Record

Use this request to update a user’s record.

A great many fields in the user record are optional when initially creating the record. These fields are naturally also optional in PUT requests, but the behavior in a PUT request is quite different. In PUT requests, any fields CURRENTLY POPULATED in the user’s record MUST ALSO BE INCLUDED in the update request; otherwise, those fields are deleted from the user record. In other words, omitting a currently populated field in a PUT request amounts to deleting that information from the user’s record.

At the same time, if you want to remove information for a specific field in a user record, you can do this using a PUT request that includes ALL the necessary information EXCEPT the field you want to delete. Just be careful to include all information you want to retain in the record.

Note that you cannot disable a user by using a PUT request to set the IsActive property to false. If the IsActive property is included in a PUT request, it is ignored.

Request

PUT /users({UserId})

Example Request

PUT /users(2576)
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

{
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "ClientUserId": "132",
    "CorrelationId": "SM175",
    "Email": "johnb@kentel.com",
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 17,
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": null,
    "Version": 1
}

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

Name Description
UserName (String) Required. The unique name for identifying this user.
Email (String) Optional. The user’s email address. Must be unique.
FirstName (String) Required. The first name of the user.
LastName (String) Required. The last name of the user.
ParentEntityId (Integer) Ignored in PUT. The identifier of the company to which the user belongs.
ClientUserId (String) Optional. The identifier of the user in the client’s Retail Management System.
Picture (Picture) Optional. A reference to a media asset that is a photo of the user.
JobTitle (String) Optional. The job title of the user.
Address (Address) Optional. The address of the user.
PhoneNumbers (Array[PhoneNumber]) Optional. The phone numbers for the user.
Attributes (Key-Value Pairs) Optional. A property for storing additional information about a user; for example, badge number or department. Information is stored as an array of key-value pairs.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "ClientUserId": "132",
    "CorrelationId": "SM175",
    "Email": "johnb@kentel.com",
    "IsActive": true,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 17,
    "ParentEntityName": "Kentel",
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": null,
    "Version": 1
}

A successful request returns a 200 (OK) response with the updated user record represented as User resource. For a description of parameters defined for the User resource, see User.

GET a Single User

Request

GET /Users({UserId})

Example Request

GET /Users(2576)
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "ClientUserId": "132",
    "CorrelationId": "SM175",
    "Email": "johnb@kentel.com",
    "IsActive": true,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 17,
    "ParentEntityName": "Kentel",
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
     "Picture": {
        "Id": "1fa5ae34-1578-44a0-9b21-b9be14559b9f",
        "Href": "https://ams.blob.core.windows.net/assets/1fa5ae34-1578-44a0-9b21-b9be14559b9f.jpg",
        "Height": 480,
        "Width": 640,
        "Md5Checksum": "d3fc6e526f00a56c9dacd503eff5fc93",
        "Name": "sample.jpg",
        "MimeType": "image/jpeg"
    },
    "Version": 2
}

A successful request returns a 200 (OK) response with the requested user record represented as User resource. For a description of parameters defined for the User resource, see User.

GET Users by ClientUserId or CorrelationId

You can filter active users for a company by ClientUserId or CorrelationId.

To control how many user records the API returns, or to navigate using HAL, use pagination controls.

Request (ClientUserId)

GET /Entities({EntityId})/Users?$filter=ClientUserId eq '{ClientUserId}'

Request (CorrelationId)

GET /Entities({EntityId})/Users?$filter=CorrelationId eq '{CorrelationId}'

Example Request

GET /Entities(14146)/Users?$filter=ClientUserId eq '132'
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
EntityId (Integer) The identifier of the company.

Request Parameters

None.

Query Parameters

Use either (but not both) of these properties as a filter in the query.

Name Description
ClientUserId (Integer) The identifier of the user in the client’s external system.
CorrelationId (String) An identifier for the user in the client’s Retail Management System (for example, RQ).

Response

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "Id": 2576,
        "FirstName": "John",
        "LastName": "Bates",
        "UserName": "johnb@kentel.com",
        "Address": {
            "AddressLine1": "1432 Merry View Road",
            "AddressLine2": "",
            "City": "Big Windy",
            "StateCode": "ON",
            "CountryCode": "CA",
            "Zip": "A1A2B2"
        },
        "ClientUserId": "132",
        "CorrelationId": "SM175",
        "Email": "johnb@kentel.com",
        "IsActive": true,
        "JobTitle": "Sales Clerk",
        "ParentEntityId": 17,
        "ParentEntityName": "Kentel",
        "PhoneNumbers": [
            {
                "Number": "6135550127",
                "Extension": "5532",
                "Type": "Work"
            }
        ],
        "Picture": null,
        "Version": 1
    }
]

A successful request returns a 200 (Ok) response along with an array listing users matching the query, represented as User resources. For a description of the parameters defined for the User resource, see User.

Set a Temporary Password for a User

When the administrator creates the user account, she should create a temporary password for the user. The user’s password is set to the provided value and marked in the system as temporary.

When the temporary password is created, for example when a user has forgotten their password, a notification is sent to the email address specified for the user account. For notification to succeed, the user must have a working email configured for the account. (Email is a required field in user accounts, but might be missing for some users synced from RQ.)

When a user has a temporary password, the system forces the user to change the password on first login. Users change their passwords using the Change Your Password request.

Request

POST /users({UserId})/temporaryPassword

Example Request

POST /users(2576)/temporaryPassword
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

{
    "Password": "newpa55word"
}

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

Name Description
Password (String) Required. A non-empty string of at least 6 characters.

Response

Example Response

HTTP 204 Content-Type: application/json

A successful request returns a 204 (No Content) response.

Change Your Password

Use this request to change the password on your user account.

When an administrator creates your user account, you are provided with a temporary password. The first time you log on, the system will require you to change this password; use this request to do so.

Note that all passwords must meet the defined in the client’s password strength rules.

Request

POST /users({UserId})/changePassword

Example Request

POST /users(2576)/changePassword
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

{
    "CurrentPassword": "0ldPa55word",
    "NewPassword": "n3wPa55word"
}

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

Name Description
CurrentPassword (String) Required. The current (old) password for the user.
NewPassword (String) Required. The desired (new) password for the user.

Response

Example Response

HTTP 204 Content-Type: application/json

A successful request returns a 204 (No Content) response.

In the event that password strength rules are not satisfied, the system will return a 400 (Bad Request) response with an error message that explains why the attempt to change the password failed, as in the following example:

HTTP 400 Content-Type: application/json

{
    "Message": "Unable to change password. See Details for the list of reasons.",
    "Details":
    [
        "The current password is incorrect.",
        "The new password cannot be the same as the temporary password."
    ]
}

Assign a User to a Location

Use this request to assign a user to a location. Users can be assigned to multiple locations.

Request

PUT /users({UserId})/locations({LocationId})

Example Request

PUT /users(2576)/Locations(2562)
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

Path Parameters

Name Description
UserId (Integer) The identifier of the user.
LocationId (Integer) The identifier of the location (entity) to which the user is being assigned. A user can be assigned to mutliple locations.

Request Parameters

None.

Response

Example Response

HTTP 204 Content-Type: application/json

A successful request returns a 204 (No Content) response.

Unassign a User from a Location

Use this request to unassign a user from a currently assigned location.

Request

DELETE /users({UserId})/locations({LocationId})

Example Request

DELETE /users(2576)/locations(2)
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
UserId (Integer) The identifier of the user.
LocationId (Integer) The identifier of the location from which the user is being unassigned.

Request Parameters

None.

Response Parameters

Example Response

HTTP 204 Content-Type: application/json

A successful request returns a 204 (No Content) response.

GET a User’s Assigned Locations

Use this request to see what locations have been assigned to a user.

Request

GET /users({UserId})/locations

Example Request

GET /users(2576)/locations
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "UserID": 2576,
    "LocationIDs": [
        14202,
        14234
   ]
}

A successful request returns 200 (Ok) response with an object listing all the locations assigned to that user.

Name Description
UserId (Integer) The identifier of the user.
LocationIDs (Array[Integer]) A collection of entity identifiers representing the locations to which the user has been assigned.

Lock a User

Use this request to lock a user.

Locking a user is different from disabling a user. A disabled user is inactive, and the user record is not returned in searches. A locked user is still active, but will be prevented from logging on or obtaining an access token until the account is unlocked again.

When you lock a user, you can optionally provide a reason for having locked them.

Request

POST /users({UserId})/lock

Example Request

POST /users(2576)/lock
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

{
  "LockReasonId": 14
}

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

Name Description
LockReasonId (Integer) Optional. The identifier of a defined LockReason.

Response

Example Response

HTTP 204 Content-Type: application/json

A successful request returns a 204 (No Content) response.

Unlock a User

A user can be unlocked if the parent entity is using WS-Trust Third Party Authentication (WS-Trust 3PA) AND the parent entity has explicitly opted in with iQmetrix to using the lock feature:

To determine a user’s lock status, see GET the Lock Status of a User.

Once a user has been unlocked they will usually be able to log on to the system with their old credentials, will be able to obtain an access token, and will be able to reset their password. Users who are using WS-Trust 3PA.

Request

POST /users({UserId})/unlock

Example Request

POST /users(2576)/unlock
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

None.

Response

Example Response

HTTP 204 Content-Type: application/json

A successful request returns a 204 (No Content) response.

GET the Lock Status of a User

Use this request to determine the lock status of a particular user.

Request

GET /users({UserId})/unlock

Example Request

GET /users(2576)/unlock
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "CanUnlockUser": true,
    "LockReasonId": 14
}

A successful response returns a 200 (Ok) response and an object with the specified user’s lock status.

Name Description
CanUnlockUser (Boolean) The user’s lock status; true if the user is currently locked, and false if the user is currently unlocked.
LockReasonId (Integer) The identifier of a configured LockReason; null if no reason was configured.

Disable a User

Use this request to disable a user completely.

Note that you cannot completely delete a user record. “Deleting” a user record disables the user, setting the IsActive property to false. (Note that this is the only way to set IsActive to false; this property cannot be set directly.)

When disabled, the user will no longer be able to log on to the system and the user is not returned in searches (except searches for disabled users).

To free up an email address or username, you must PUT an update to the user record. Use the update request to change email or username of the original user to something else.

Request

DELETE /users({UserId})

Example Request

DELETE /users(2576)
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "ClientUserId": "132",
    "Email": "johnb@kentel.com",
    "IsActive": false,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 17,
    "ParentEntityName": "Kentel",
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": null,
    "Attributes": [],
    "Version": 2
}

A successful request returns a 200 (OK) response with the revised user record represented as User resource. For a description of parameters defined for the User resource, see User.

Re-Enable a User

Use this request to re-enable a user in the system, making the user active again. The IsActive property will be set to true and the user will be able to log on and obtain an access token.

Request

POST /users({UserId})/enable

Example Request

POST /users(2576)/enable
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

Path Parameters

Name Description
UserId (Integer) The identifier of the user.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "ClientUserId": "132",
    "Email": "johnb@kentel.com",
    "IsActive": true,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 1,
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": null,
    "Version": 1
}

A successful request returns a 200 (OK) response with the requested user record represented as User resource. For a description of parameters defined for the User resource, see User.

POST a Lock Reason

Use this request to define a reason why a user might be locked. The names and descriptions for lock reasons are completely configurable to accommodate your company’s business practices. The system generates numeric identifiers in the order in which the reason is defined.

Request

POST /entities({CompanyId})/lockReasons

Example Request

POST /entities(14146)/lockReasons
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

{
    "Name": "PaperworkNotDone",
    "Description": "Your account has been locked because the paperwork hasn't been done. Please contact your supervisor."
}

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company.

Request Parameters

Name Description
Name (String) Required. A name for the reason. Must be unique within a company.
Description (String) Required. A description of the reason for locking the user out. This description is displayed to the user when they attempt to log on.

Response

Example Response

HTTP 201 Content-Type: application/json
{
    "Id": 14,
    "Name": "PaperworkNotDone",
    "Description": "Your account has been locked because the paperwork hasn't been done. Please contact your supervisor."
}

A successful request returns a 201 (Created) response with the new lock reason, including the system-assigned identifier. For a description of parameters defined for the LockReason resource, see LockReason].

Update a Lock Reason

Use this request to change the name or description of a configured lock reason.

Request

PUT /entities({CompanyId})/lockReasons({LockReasonId})

Example Request

PUT /entities(14146)/lockReasons(14)
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json
Content-Type: application/json

{
    "Id": 14,
    "Name": "PaperworkNotDone",
    "Description": "Your account has been locked because the paperwork hasn't been done. Please contact your supervisor."
}

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company.
LockReasonId (Integer) The identifier of the lock reason you want to update.

Request Parameters

Name Description
Name (String) Required. A name for the reason. Must be unique within a company.
Description (String) Required. A description of the reason for locking the user out. This description is displayed to the user when they attempt to log on.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 14,
    "Name": "PaperworkNotDone",
    "Description": "Your account has been locked because the paperwork hasn't been done. Please contact your supervisor."
}

A successful request returns a 200 (OK) response with the updated lock reason, represented as a LockReason resource. For a description of parameters defined for the LockReason resource, see LockReason].

DELETE a Lock Reason

Use this request to delete a lock reason from the configured reasons for locking users out of the system.

Request

DELETE /entities({CompanyId})/lockReasons({LockReasonId})

Example Request

DELETE /entities(14146)/lockReasons(1)
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company.
LockReasonId (Integer) The identifier of the lock reason you want to update.

Request Parameters

None.

Response

Example Response

HTTP 204 Content-Type: application/json

A successful request returns a 204 (No Content) response.

GET a Lock Reason

Use this request to view information configured as a reason for locking users out of the system.

Request

GET /entities({CompanyId})/lockReasons({LockReasonId})

Example Request

GET /entities(14146)/lockReasons(14)
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company.
LockReasonId (Integer) The identifier of the lock reason you want to view.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": 14,
    "Name": "PaperworkNotDone",
    "Description": "Your account has been locked because the paperwork hasn't been done. Please contact your supervisor."
}

A successful request returns a 200 (OK) response with the specified lock reason, represented as a LockReason resource. For a description of parameters defined for the LockReason resource, see LockReason].

GET All Lock Reasons

Use this request to see the list of reasons for locking a user that have been configured for a company.

Request

GET /entities({CompanyId})/lockReasons

Example Request

GET /entities(14146)/lockReasons
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
[
        {
        "Id": 2,
        "Name": "FailedLoginsExceeded",
        "Description": "Your account has been locked because you exceeded the number of failed login attempts. It will automatically unlock in 24 hours. Otherwise, see your system administrator."
    },
    {
        "Id": 14,
        "Name": "PaperworkNotDone",
        "Description": "Your account has been locked because the paperwork hasn't been done. Please contact your supervisor."
    }
]

A successful request returns a 200 (OK) response with the configured list of lock reasons, represented as an array of LockReason resources. For a description of parameters defined for the LockReason resource, see LockReason].

GET All Users for an Entity

Use this request to obtain a list of users that exist for the specified entity. Note that requesting for a company will return all users for that company. Requesting for a sub-node will return users that are assigned to the specified location plus any sub-nodes. Requesting for a location will return all users assigned to the location.

Note that only active (that is non-disabled) users are returned. You can use the entity identifier of the entire company or for a location or sub-entity of the company.

To control how many user records the API returns, or to navigate using HAL, use pagination controls.

Request

GET /entities({CompanyId})/users

Example Request

GET /entities(14146)/users?$skip=1&$top=10
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "Id": 2576,
        "FirstName": "John",
        "LastName": "Bates",
        "UserName": "johnb@kentel.com",
        "Address": {
            "AddressLine1": "1432 Merry View Road",
            "AddressLine2": "",
            "City": "Big Windy",
            "StateCode": "ON",
            "CountryCode": "CA",
            "Zip": "A1A2B2"
            },
        "ClientUserId": "132",
        "CorrelationId": "SM175",
        "Email": "johnb@kentel.com",
        "IsActive": true,
        "JobTitle": "Sales Clerk",
        "ParentEntityId": 17,
        "ParentEntityName": "Kentel",
        "PhoneNumbers": [
            {
                "Number": "6135550127",
                "Extension": "5532",
                "Type": "Work"
            }
        ],
        "Picture": null,
        "Version": 1
    }
]

A successful request returns a 200 (Ok) response with an array of user records, represented as User resources. For a description of parameters defined for the User resource, see User].

To control how many user records the API returns, or to navigate using HAL, use pagination controls.

GET the Number of Users for an Entity

Use this request to determine the number of users associated with the specified entity.

This request produces different results depending on which Entity Role is called.

Request

GET /entities({EntityId})/users/getCount

Example Request

GET /entities(41426)/users/getCount
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
EntityId (Integer) The identifier of the entity.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
	"Count": 54
}

A successful request returns a 200 (OK) response with the requested user count for the specified entity.

Name Description
Count The number of users associated with the specified entity.

GET a List of Disabled Users

Use this request to retrieve a list of users who have been disabled (deleted).

Note: This request uses v2 of the User Manager API (https://usermanager.iqmetrix.net/v2)

To control how many user records the API returns, or to navigate using HAL, use pagination controls.

Request

GET /entities({entityId})/users?$filter=isactive eq '{value}'

Example Request

GET https://usermanager.iqmetrix.net/v2/entities(94146)/users?$filter=isActive eq 'false'
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q
Accept: application/json

Path Parameters

Name Description
EntityId (Integer) The identifier of the entity.

Request Parameters

None.

Query Parameters

$filter=isActive eq ‘{value} Queries for the value of the isActive parameter. {value} can be true (the user is enabled) or false (the user is disabled).

Response

Example Response

HTTP 200 Content-Type: application/json
{
  "_links": {
    "prev": null,
    "self": "/v2/entities(13167)/users?$skip=0&$top=30",
    "next": null
  },
  "_metadata": {
    "count": 1,
    "skip": 0,
    "top": 30
  },
  "items": [
    {
      "Id": 92,
      "CorrelationId": null,
      "ClientUserId": null,
      "FirstName": "Test1",
      "LastName": "Test",
      "UserName": "Test1@test.com",
      "Email": "Test1@test.com",
      "IsActive": true,
      "ParentEntityId": 13167,
      "ParentEntityName": "test",
      "Profiles": [],
      "Picture": null,
      "Address": {
        "AddressLine1": null,
        "AddressLine2": null,
        "City": null,
        "StateCode": null,
        "CountryCode": null,
        "Zip": null
      },
      "PhoneNumbers": [],
      "JobTitle": null,
      "Attributes": {},
      "Version": 1
    }
  ]
}

A successful request returns a 200 (OK) response with an array of user records, represented as a User resource. For a description of parameters in the User resource, see User.

Name Description
Count The number of users associated with the specified entity.

SEARCHING

You can search for users within a company using the special /search endpoint.

Note that this request will only return users for whom IsActive is set to true.

To control how many user records the API returns, or to navigate using HAL, use pagination controls.

Request

GET /entities({CompanyId})/users/Search?terms={Terms}

Example Request

GET /entities(14146)/users/Search?terms=Sam+Smith&$skip=1&$top=10
Authorization: Bearer d24zZnduM2Z2NjNmd_0DZndvQCxBLFwrJhx6FgY7QzIRCAcpBiJrKyElXRAwDXdROAJ-FDUgSTc_PmorRyZUBy8PclQNNgMxDz5q

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company.

Query Parameters

Name Description
Terms (List[terms]) A list of search terms, where terms are separated by an encoded whitespace (“+”). User properties must contain or start with the term to be matched. Search terms are case-insensitive.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "_links": {
        "prev": "null",
        "self": "/v1/entities(14146)/users?$skip=0&$top=30",
        "next": "null"
    },
    "_metadata": {
        "count": 1,
        "skip": 0,
        "top": 30
    },
    "items": [
        {
            "Id": 2576,
            "FirstName": "John",
            "LastName": "Bates",
            "UserName": "johnb@kentel.com",
            "Address": {
                "AddressLine1": "1432 Merry View Road",
                "AddressLine2": "",
                "City": "Big Windy",
                "StateCode": "ON",
                "CountryCode": "CA",
                "Zip": "A1A2B2"
            },
            "ClientUserId": "132",
            "Email": "johnb@kentel.com",
            "IsActive": true,
            "JobTitle": "Sales Clerk",
            "ParentEntityId": 1,
            "PhoneNumbers": [
                {
                    "Number": "6135550127",
                    "Extension": "5532",
                    "Type": "Work"
                }
            ],
            "Picture": null,
            "Version": 1
        }
    ]
}

A successful request returns a 200 (Ok) response containing the list of records matching the search criteria, represented as an array of User resources. The metadata for the response includes the number of matched records. For a description of parameters defined for the User resource, see User.

PAGINATION

Pagination Controls

Pagination in the User Manager API is controlled by the $skip and $top query string parameters.

HAL Metadata and Navigation Control

The User Manager API supports Hypermedia Application Language (HAL) in responses. HAL returns pagination links for self, prev, and next. To use this feature, you must have HAL enabled (Accept: application/hal+json) in your request; HAL is enabled by default.

Name Description
_links  
prev The route to use to fetch the previous page of results; null if this is the first page.
self The route to use to fetch these results. If the request including the $top or $skip pagination controls, the values specified for these controls will be reported here; for instance, as GET /v1/entities(3)/users?$skip=0&$top=30.
next The route to use to fetch the next page of results; null if this is the last page.
_metadata  
count The total number of items. Note: If skip is greater or equal to the total number of items, count shows 0.
skip The nmber of items skipped in the current request.
top Number of items requested.

Note that HAL pagination links are relative; that is, they do not include the base endpoint. It is the responsibility of the client to prepend the link appropriately, as in the following example.

ERRORS

HTTP Status Code Description How to Resolve
HTTP 400 The temporary password must be at least 6 characters long Ensure the provided password is at least 6 characters long and not an empty string
HTTP 400 Bad Request Ensure all of the required fields are provided and formatted accurately, for more details see error message
HTTP 400 No search terms provided Ensure search terms are provided in URI
HTTP 400 Query string parameter '$top'
should be within 1 to 100 range but was {x}
Ensure $skip is in the range [0-100]
HTTP 400 Query string parameter '$skip'
should be non-negative but was -1
Ensure $top is non-negative
HTTP 404 User not found Ensure UserId is valid
HTTP 404 Entity not found Ensure LocationId is valid
HTTP 409 Username and email already exist Ensure the email chosen does not already belong to a User.
If the email address belongs to a disabled User, change the email for the disabled User before creating a new User with the original email
HTTP 409 User version mismatch Ensure the Version value provided in the request data matches the Version for the User in the database

The User Manager API supports pagination of collections of resources for some requests.

Query Parameters

Pagination is done through the use of $skip and $top query string parameters.

$skip denotes the number of items to skip from the entire set of results. This value defaults to 0 if no $skip value is specified. If a value less than 0 is specified, the URI is considered malformed.

$top denotes the maximum number of items to include in the response. This value defaults to 30 if no $top value is specified. Acceptable values are in the range [0-100].

Pagination-enabled requests include links for ‘self’, ‘prev’ and ‘next’ in the response data.

These links are relative, they do not include the base endpoint. It is the responsibility of the client to prepend the appropriate endpoint.

Example
{
    "_links": {
        "prev": null,
        "self": "/v1/Entities(14146)/Users?$skip=0&$top=5",
        "next": "/v1/Entities(14146)/Users?$skip=5&$top=5"
    },
    "_metadata": {
        "count": 15,
        "skip": 0,
        "top": 5
    }
}

In the example above:

Was this page helpful?