Search for Accounts

POST /GetAllSearchAdvanced

Send a POST request to the GetAllSearchAdvanced() method on the AccountView object to return information about one or more accounts. The information included in the response depends on the range of account properties and parameter values included in the request.

A valid OAuth 2.0 Bearer token is required.

URL

POST https://<FQDN_Of_Your_EmpowerID_Web_Server>/api/webui/v1/AccountView/GetAllSearchAdvanced

Header Key/Value Pairs

Key	Value
Authorization	Bearer <access_token>
X-EmpowerID-API-Key	The API key from the registered OAuth application
Content-Type	application/json

Request Body

The body of the request must include all parameters required by the method and the IncludedProperties object with at least one account property.

Included Properties

Use IncludedProperties to return one or more account properties. Example properties include AccountID, LastName, FirstName, and NetBiosName.

Body Parameters

The GetAllSearchAdvanced() method includes a number of parameters that must be included in the body of the request. Use parameters to filter the number of accounts returned by the endpoint.

View Parameters

Parameter	Type	Description
AccountStoreID	`int`	Return all accounts with a matching account store ID Set to `null` to ignore Required
SecurityBoundaryID	`int`	Set to the ID of the Security Boundary to return accounts with a matching Security Boundary ID Set to `null` to ignore Required
SecurityBoundaryTypeID	`int`	Set to the ID of the Security Boundary Type to return accounts with a matching Security Boundary Type ID Set to `null` to ignore Required
AccountTypeID	`int`	Return all accounts with the same Account Type Set to `null` to ignore Required
ShowSystemAccountsOnly	`Boolean`	Return system accounts only Set to `null` to ignore Required
ShowSystemBuiltinAccountsOnly	`Boolean`	Return system builtin accounts only Set to `null` to ignore Required
AccountUsageTypeID	`int`	Return all accounts with the same Account Usage Type Set to `null` to ignore Required
IsOrphan	`Boolean`	Return accounts without an EmpowerID Person Set to `null` to ignore Required
Disabled	`Boolean`	Return disabled accounts Set to `null` to ignore Required
LockedOut	`Boolean`	Return locked out accounts Set to `null` to ignore Required
NeverLoggedInOnly	`Boolean`	Return accounts that have never logged in to the system Set to `null` to ignore Required
HideInEmpowerID	`Boolean`	Return accounts that are hidden in EmpowerID Set to `null` to ignore Required
OrgZoneID	`int`	Return accounts with a matching OrgZone ID Set to `null` to ignore Required
PersonID	`int`	Return accounts owned by the person with the specified ID Set to `null` to ignore Required
ManagerPersonID	`int`	Return accounts whose manager matches the specified ID Set to `null` to ignore Required
MemberOfGroupID	`int`	Return accounts with membership in the specified group Set to `null` to ignore Required
columnsToSearch	`string`	Specifies one or more search conditions. Formatted as follows: `"%[[][[]%<Conditions><Condition PropertyName=\"Name of the property to search\" SearchValue=\"Value of the property\" Operator=\"Equality\" QuerySuffix=\" Suffix Value \"StartGroupString=\"\" EndGroupString=\"\" /></Conditions>"` Required
pageLength	`int`	Specifies the number of accounts to return in the list of accounts Set to `null` to ignore Required
resourceTags	`string`	Return accounts with a matching resource tag Required
start	`int`	Specifies the first account in the list of accounts returned by the API; set to `0` to return the first account Required
textToSearch	`string`	Set to `"AdvancedSearch"` Required
totalCount	`int`	This is an output parameter that returns the number of accounts matching the search conditions and parameter values Required

columnsToSearch

The columnsToSearch body parameter is used to return accounts meeting one or more conditions. Each condition specifies a property with a specific value to search and there can be more than one condition. For example, to return a list of accounts belonging to the "DevDomain1" domain that are currently locked out, the value for columnsToSearch would be set to that shown below.

"%[[][[]%<Conditions><Condition PropertyName=\"NetBiosName\" SearchValue=\"Docs-tracking\" Operator=\"EqualTo\" QuerySuffix=\" AND \" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/><Condition PropertyName=\"LockedOut\" SearchValue=\"true\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"1\" SearchType=\"Boolean\"/></Conditions>"

Remarks

In the above example, columnsToSearch contains two search conditions. The API returns accounts matching both conditions. Each condition includes the PropertyName to search, the SearchValue to search for, an Equality Operator, a QuerySuffix and a SearchType for the relevant data type.

Search Examples

The below examples demonstrate how to use IncludedProperties, parameters, and conditions in columnsToSearch to query the API for a list of accounts matching the search conditions. Attributes returned for each record are set by the properties specified in IncludedProperties.

Set the `ShowSystemAccountsOnly` parameter to `1` to return a list of system accounts

{
    "IncludedProperties": [        
        "LogonName",
        "NetBiosName",
        "FriendlyName",      
        "AccountOrganizationStatusFriendlyName",
        "AccountUsageTypeFriendlyName",       
        "ResourceID",
        "AccountID",
        "Name",
        "Description",
        "CreatedDate",
        "ExpiresOn",       
        "AccountStoreFriendlyName"
    ],
    "Parameters": {
        "AccountTypeID": null,
        "AccountUsageTypeID": null,
        "Disabled": null,
        "HideInEmpowerID": null,
        "IsOrphan": null,
        "LockedOut": null,
        "NeverLoggedInOnly": null,        
        "OrgZoneID": null,
        "SecurityBoundaryID": null,
        "SecurityBoundaryTypeID": null,
        "ShowSystemAccountsOnly": 1,
        "ShowSystemBuiltInAccountsOnly": null,
        "accountStoreID": null,        
        "textToSearch": null,
        "columnsToSearch": "%[[][[]%<Conditions/>",
        "pageLength": 5,
        "resourceTags": null,
        "start": 0,
        "totalCount": null
    }
}

Get all personal privileged accounts that have never logged in to the system

Set the AccountUsageTypeID parameter to 2 and the NeverLoggedInOnly parameter to 1

{
    "IncludedProperties": [        
        "LogonName",
        "NetBiosName",
        "FriendlyName",
        "PersonID",
        "EmpowerIDLogon",
        "AccountOrganizationStatusFriendlyName",
        "AccountUsageTypeFriendlyName",
        "DistinguishedName",
        "LastLogonTime",
        "ValidUntil",
        "ResourceID",
        "AccountID",
        "Name",
        "Description",
        "CreatedDate",
        "ExpiresOn",
        "MustChangePasswordAtNextLogin",
        "LockedOut",
        "CannotChangePassword",
        "PasswordExpires",
        "PasswordLastChanged",
        "PasswordNeverExpires",
        "FirstName",
        "LastName",
        "Officelocation",
        "Location",
        "AccountStoreFriendlyName",
        "Email",
        "StreetAddress",
        "City",
        "State",
        "ZipCode",
        "Country",
        "Company",
        "JobTitle",
        "Department",
        "Telephone",
        "MobileNumber",
        "AccountManagerFriendlyName",
        "PersonOwnerLastAttestationDate",
        "PersonOwnerLastResourceAttestationSnapshotID"
    ],
    "Parameters": {
        "AccountStoreID": null,
        "SecurityBoundaryID": null,
        "SecurityBoundaryTypeID": null,         
        "AccountTypeID": null,
        "ShowSystemAccountsOnly": null,
        "ShowSystemBuiltInAccountsOnly": null,
        "AccountUsageTypeID": 2,
        "IsOrphan": null,
        "Disabled": null,        
        "LockedOut": null,
        "NeverLoggedInOnly": 1, 
        "HideInEmpowerID": null,
        "OrgZoneID": null,
        "PersonID": null,
        "ManagerPersonID": null,
        "MemberOfGroupID": null,
        "columnsToSearch": "%[[][[]%<Conditions/>",
        "textToSearch": "AdvancedSearch",
        "pageLength": 5,
        "resourceTags": null,
        "start": 0,
        "totalCount": null
    }
}

Get all locked out accounts

Note the PropertyName for the search condition is set to LockedOut, SearchValue is set to True, the Operator is set to EqualTo and the SearchType is Boolean.

{
    "IncludedProperties": [        
        "AccountID",
        "FriendlyName",
        "FirstName",
        "LastName",
        "LogonName",
        "EmpowerIDLogon",
        "NetBiosName",       
        "AccountStoreFriendlyName"
    ],
    "Parameters": {
        "AccountStoreID": null,
        "SecurityBoundaryID": null,
        "SecurityBoundaryTypeID": null,         
        "AccountTypeID": null,
        "ShowSystemAccountsOnly": null,
        "ShowSystemBuiltInAccountsOnly": null,
        "AccountUsageTypeID": null,
        "IsOrphan": null,
        "Disabled": null,        
        "LockedOut": null,
        "NeverLoggedInOnly": null, 
        "HideInEmpowerID": null,
        "OrgZoneID": null,
        "PersonID": null,
        "ManagerPersonID": null,
        "MemberOfGroupID": null,
        "textToSearch": "AdvancedSearch",
        "pageLength": 5,
        "resourceTags": null,
        "start": 0,
        "totalCount": null,
        "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"LockedOut\" SearchValue=\"true\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"Boolean\"/></Conditions>"
    }
}

Get all accounts that are members of a specific group

Set the MemberOfGroupID parameter to the GUID of the target group

{
    "IncludedProperties": [        
        "LogonName",
        "NetBiosName",
        "FriendlyName",      
        "AccountOrganizationStatusFriendlyName",
        "AccountUsageTypeFriendlyName",       
        "ResourceID",
        "AccountID",
        "Name",
        "Description",
        "CreatedDate",
        "ExpiresOn",       
        "AccountStoreFriendlyName"
    ],
    "Parameters": {
        "AccountStoreID": null,
        "SecurityBoundaryID": null,
        "SecurityBoundaryTypeID": null,         
        "AccountTypeID": null,
        "ShowSystemAccountsOnly": null,
        "ShowSystemBuiltInAccountsOnly": null,
        "AccountUsageTypeID": null,
        "IsOrphan": null,
        "Disabled": null,        
        "LockedOut": null,
        "NeverLoggedInOnly": null, 
        "HideInEmpowerID": null,
        "OrgZoneID": null,
        "PersonID": null,
        "ManagerPersonID": null,
        "MemberOfGroupID": "4E375004-5E6F-415D-B049-4A112C100D12",      
        "textToSearch": null,
        "pageLength": 5,
        "resourceTags": null,
        "start": 0,
        "totalCount": null,
        "columnsToSearch": "%[[][[]%<Conditions/>"
    }
}

SearchTerms

Each identity object in the EmpowerID Identity Warehouse has a SearchTerms property with a specific set of search values that can be used to return all objects matching those values. For accounts, SearchTerms encompass the Name, FriendlyName, Email, FirstName, LastName, LogonName, and UserPrincipalName properties. When used, the API returns all accounts where the specified search value finds a match in any of those properties. For example, if the search value is set to "Rogers", the API would return all the following accounts:

Any account with a match in the name
Any account with a match in the friendly name
Any account with a match in the first name
Any account with a match in the last name
Any account with a match in the logon name
Any account with a match in the email address
Any account with a match in the User Principal Name

The following examples illustrate how to use SearchTerms to return a subset of accounts:

Get all accounts where the search value for `SearchTerms` is set to "Rogers"

Use SearchTerms to return the Account ID, friendly name, first name, last name, Logon name, EmpowerID Logon, NetBiosName, email address and account manager friendly name for all accounts where the search value is set to "rogers"

{    
    "IncludedProperties": [
        "AccountID",
        "FriendlyName",
        "FirstName",
        "LastName",
        "LogonName",
        "EmpowerIDLogon",
        "NetBiosName",
        "Email",
        "AccountManagerFriendlyName"       
    ],
    "Parameters": {
        "AccountTypeID": null,
        "AccountUsageTypeID": null,
        "Disabled": null,
        "HideInEmpowerID": null,
        "IsOrphan": null,
        "LockedOut": null,
        "NeverLoggedInOnly": null,        
        "OrgZoneID": null,
        "SecurityBoundaryID": null,
        "SecurityBoundaryTypeID": null,
        "ShowSystemAccountsOnly": null,
        "ShowSystemBuiltInAccountsOnly": null,
        "accountStoreID": null,        
        "textToSearch": "AdvancedSearch",
        "pageLength": 5,
        "resourceTags": null,
        "start": 0,
        "totalCount": null,
        "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"rogers\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/></Conditions>"
    }
}

The response includes all accounts matching the search value. Note the properties where the match occurs.

{
    "Tags": [],
    "Data": [
        {
            "AccountID": 7598177,
            "FriendlyName": "Steve Rogers",
            "FirstName": null,
            "LastName": null,
            "LogonName": "steve.rogers",
            "EmpowerIDLogon": null,
            "NetBiosName": "CALDAP-NEW2",
            "Email": null,
            "AccountManagerFriendlyName": null
        },
        {
            "AccountID": 474585,
            "FriendlyName": "RDice",
            "FirstName": "Robert",
            "LastName": "Dice",
            "LogonName": "0xbb25b643614a1b40b1d63f935aa08c62",
            "EmpowerIDLogon": null,
            "NetBiosName": "DEVDOMAIN1",
            "Email": "bdice@rogers.com",
            "AccountManagerFriendlyName": null
        },
        {
            "AccountID": 478601,
            "FriendlyName": "RDice",
            "FirstName": "Robert",
            "LastName": "Dice",
            "LogonName": "0xe419fc6d9da1b24a98d112175396ac6b",
            "EmpowerIDLogon": null,
            "NetBiosName": "DEVDOMAIN1",
            "Email": "bdice@rogers.com",
            "AccountManagerFriendlyName": null
        },
        {
            "AccountID": 490102,
            "FriendlyName": "RDice",
            "FirstName": "Robert",
            "LastName": "Dice",
            "LogonName": "0x658a5369fba3d249ace199425fd428e9",
            "EmpowerIDLogon": null,
            "NetBiosName": "DEVDOMAIN1",
            "Email": "bdice@rogers.com",
            "AccountManagerFriendlyName": null
        },
        {
            "AccountID": 484459,
            "FriendlyName": "Mindi Idell Rogers",
            "FirstName": "atinder",
            "LastName": "IdellRogers",
            "LogonName": "Mindi.IdellRogers",
            "EmpowerIDLogon": "Mindi.IdellRogers",
            "NetBiosName": "DEVDOMAIN1",
            "Email": "Mindi.IdellRogers@omd.com",
            "AccountManagerFriendlyName": null
        }
    ],
    "OutParameters": [
        {
            "Name": "totalCount",
            "Value": 1150
        }
    ]
}

Get all accounts that belong to the "CALDAP-NEW2" domain where the search value for `SearchTerms` is set to "Steve"

{    
    "IncludedProperties": [
        "AccountID",
        "FriendlyName",
        "FirstName",
        "LastName",
        "LogonName",
        "EmpowerIDLogon",
        "NetBiosName",
        "Email",
        "AccountManagerFriendlyName"       
    ],
    "Parameters": {
        "AccountTypeID": null,
        "AccountUsageTypeID": null,
        "Disabled": null,
        "HideInEmpowerID": null,
        "IsOrphan": null,
        "LockedOut": null,
        "NeverLoggedInOnly": null,        
        "OrgZoneID": null,
        "SecurityBoundaryID": null,
        "SecurityBoundaryTypeID": null,
        "ShowSystemAccountsOnly": null,
        "ShowSystemBuiltInAccountsOnly": null,
        "accountStoreID": null,        
        "textToSearch": "AdvancedSearch",
        "pageLength": 5,
        "resourceTags": null,
        "start": 0,
        "totalCount": null,
        "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"rogers\" Operator=\"EqualTo\" QuerySuffix=\" AND \" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/><Condition PropertyName=\"NetBiosName\" SearchValue=\"CALDAP-NEW2\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"1\" SearchType=\"String\"/></Conditions>"
    }
}  

Get all accounts where the `SearchValue` of the `SearchTerm` is an email address containing "microsoft"

info

When using SearchTerms, results can be filtered to specific text within supported properties. For example, the condition below returns accounts where Email contains microsoft.

{    
    "IncludedProperties": [
        "AccountID",
        "FriendlyName",
        "FirstName",
        "LastName",
        "LogonName",
        "EmpowerIDLogon",
        "NetBiosName",
        "Email",
        "AccountManagerFriendlyName"       
    ],
    "Parameters": {
        "AccountStoreID": null,
        "SecurityBoundaryID": null,
        "SecurityBoundaryTypeID": null,         
        "AccountTypeID": null,
        "ShowSystemAccountsOnly": null,
        "ShowSystemBuiltInAccountsOnly": null,
        "AccountUsageTypeID": null,
        "IsOrphan": null,
        "Disabled": null,
        "LockedOut": null,
        "NeverLoggedInOnly": null, 
        "HideInEmpowerID": null,
        "OrgZoneID": null,
        "PersonID": null,
        "ManagerPersonID": null,
        "MemberOfGroupID": null,
        "textToSearch": "AdvancedSearch",
        "pageLength": 5,
        "resourceTags": null,
        "start": 0,
        "totalCount": null,
        "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"Email_*microsoft\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/></Conditions>"
    }
}

Sample Responses

200 OK
Error

{
    "Tags": [],
    "Data": [
        {
            "LogonName": "F6C48859-944D-4681-84ED-0102E04A5A7E",
            "NetBiosName": "EIDApTenant",
            "FriendlyName": "Microsoft Cloud App Security",
            "AccountOrganizationStatusFriendlyName": "Active",
            "AccountUsageTypeFriendlyName": "Personal Standard",
            "ResourceID": 1475848,
            "AccountID": 1770969,
            "Name": "Microsoft Cloud App Security",
            "Description": "Microsoft Cloud App Security",
            "CreatedDate": "2021-08-02T11:31:56.043",
            "ExpiresOn": "1900-01-01T00:00:00",
            "AccountStoreFriendlyName": "EIDApTenant"
        }
    ],
    "OutParameters": [
        {
            "Name": "totalCount",
            "Value": 2924
        }
    ]
}

{
    "Success": false,
    "Error": {
        "Code": 400,
        "Message": "Invalid request: columnsToSearch is required"
    }
}

POST /GetAllSearchAdvanced​

URL​

Header Key/Value Pairs​

Request Body​

Included Properties​

Body Parameters​

columnsToSearch​

Remarks​

Search Examples​

Set the ShowSystemAccountsOnly parameter to 1 to return a list of system accounts​

Get all personal privileged accounts that have never logged in to the system​

Get all locked out accounts​

Get all accounts that are members of a specific group​

SearchTerms​

Get all accounts where the search value for SearchTerms is set to "Rogers"​

Get all accounts that belong to the "CALDAP-NEW2" domain where the search value for SearchTerms is set to "Steve"​

Get all accounts where the SearchValue of the SearchTerm is an email address containing "microsoft"​

Sample Responses​