/
Search for People

Search for People

Post /GetAllSearchAdvanced

Send a POST request to the GetAllSearchAdvanced() method on the PersonView object to return information about one or more people. The information included in the response depends on the range of Person 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/PersonView/GetAllSearchAdvanced

Header Key/Value Pairs

Key

Value

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 Person property.

Included Properties

Use IncludedProperties to return one or more Person properties. Example properties include PersonID, LastName, FirstName, and login. See Person Properties below for a fuller list of properties that can be returned.

Body Parameters

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

Active

Boolean

  • Set to true (1) to return only people with active accounts

  • Set to false (0) to return only people with disabled accounts

  • Set to null to ignore

  • Required

Company

string

  • Set to a specific company name to filter the call to only return people with a matching Company attribute

  • Set to null to ignore

  • Required

CompanyID

int

  • Set to the ID of a specific company to filter the call to only return people with a matching Company attribute

  • Set to null to ignore

  • Required

CoreIdentityID

int

  • Set to the ID of the CoreIdentity to filter the call to only return people with a matching Core Identity

  • Set to null to ignore

  • Required

Department

string

  • Set to a specific department name to filter the call to only return people with a matching Department attribute

  • Set to null to ignore

  • Required

ExternalApprovalID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

GroupID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

IsExternal

Boolean

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

ManagementRoleID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

OrgRoleID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

OrgRoleOrgZoneID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

OrgZoneID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

OwnerAssigneeID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

PersonOrganizationStatusID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

PersonUsageTypeID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

PrimaryOrgRoleOrgZoneID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • Set to null to ignore

  • Required

SetGroupID

int

  • Set to the ID of the external approval to filter the call to only return people with a matching

  • 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

textToSearch

string

  • Can be set to “*” or “AdvancedSearch”

  • Required

pageLength

int

  • Specifies the number of groups to return in the list of groups

  • Required

resourceTags

String

  • Return groups with a matching resource tag

  • Required

start

int

  • Specifies the first group in the list of groups returned by the API; set to 0 to return the first group

  • Required

textToSearch

string

  • Set to AdvancedSearch

  • Required

totalCount

int

  • This is an output parameters that returns the number of groups matching the search conditions and parameter values.

  • Set to null

  • Required

columnsToSearch

The columnsToSearch body parameter is used to return people who meet one or more conditions. Each condition specifies a property with a specific value to search for, and there can be more than one condition. For example, to return a list of people with a manager named Jorge Posada who logged in between 9/20/2021 and 9/21/2021, the parameter would be set to the value below.

"columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"PersonManagerName\" SearchValue=\"jorge posada\" Operator=\"EqualTo\" QuerySuffix=\" AND \" SearchType=\"String\"/><Condition PropertyName=\"LastLoginDate\" SearchValue=\"2022-09-21\" Operator=\"GreaterThan\" QuerySuffix=\" AND \" StartGroupString=\"\" EndGroupString=\"\" SearchType=\"DateTime\"/><Condition PropertyName=\"LastLoginDate\" SearchValue=\"2022-09-22\" Operator=\"LessThan\" QuerySuffix=\"\"   SearchType=\"DateTime\"/></Conditions>"

Remarks

In the above example, columnsToSearch contains three search conditions. The API returns people matching all three 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 following examples demonstrate using IncludedProperties and conditions in columnsToSearch to query the API for a list of people matching the search conditions. Attributes returned for each record are set by the properties specified in IncludedProperties.

Get all people with a manager named “George Smythe” who have logged in between 2022-09-21 and 2022-09-22. Note that SearchType is set to String for the first condition and DateTime for the second and third conditions.

{ "IncludedProperties": [ "PersonID", "LastName", "FirstName", "Login", "Email", "PersonManagerName" ], "Parameters": { "ExternalApprovalID": null, "GroupID": null, "Active": null, "CompanyID": null, "CoreIdentityID": null, "ManagementRoleID": null, "OrgRoleID": null, "OrgRoleOrgZoneID": null, "OrgZoneID": null, "OwnerAssigneeID": null, "PersonOrganizationStatusID": null, "PrimaryOrgRoleOrgZoneID": null, "SetGroupID": null, "IsExternal": null, "PersonUsageTypeID": null, "Department": null, "Company": null, "textToSearch": "*", "pageLength": 10, "resourceTags": null, "start": 0, "totalCount": null, "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"PersonManagerName\" SearchValue=\"George Smythe\" Operator=\"EqualTo\" QuerySuffix=\" AND \" SearchType=\"String\"/><Condition PropertyName=\"LastLoginDate\" SearchValue=\"2022-09-21\" Operator=\"GreaterThan\" QuerySuffix=\" AND \" StartGroupString=\"\" EndGroupString=\"\" SearchType=\"DateTime\"/> <Condition PropertyName=\"LastLoginDate\" SearchValue=\"2022-09-22\" Operator=\"LessThan\" QuerySuffix=\"\" SearchType=\"DateTime\"/></Conditions>" } }

 

Get all people with an Active status who belong to the group specified by the GroupID parameter.

{     "IncludedProperties": [         "PersonID",         "Active",         "LastName",         "FirstName",         "Login",         "RiskFactorTotal",         "LastLoginDate"             ],     "Parameters": {         "ExternalApprovalID": null,         "GroupID": 823237,         "Active": null,         "CompanyID": null,         "CoreIdentityID": null,         "ManagementRoleID": null,         "OrgRoleID": null,         "OrgRoleOrgZoneID": null,         "OrgZoneID": null,         "OwnerAssigneeID": null,         "PersonOrganizationStatusID": null,         "PrimaryOrgRoleOrgZoneID": null,         "SetGroupID": null,         "IsExternal": null,         "PersonUsageTypeID": null,         "Department": null,         "Company": null,         "textToSearch": "*", "pageLength": 10, "resourceTags": null, "start": 0, "totalCount": null,         "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"Active\" SearchValue=\"true\" Operator=\"EqualTo\" QuerySuffix=\"\"  StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"Boolean\"/></Conditions>"     } }

 

Get all people belonging to the “Sales in Dublin” Business Role and Location.

{     "IncludedProperties": [         "PersonID",         "Active",         "LastName",         "FirstName",         "Login",         "OrgRoleOrgZoneFriendlyName"             ],     "Parameters": {         "ExternalApprovalID": null,         "GroupID": null,         "Active": null,         "CompanyID": null,         "CoreIdentityID": null,         "ManagementRoleID": null,         "OrgRoleID": null,         "OrgRoleOrgZoneID": null,         "OrgZoneID": null,         "OwnerAssigneeID": null,         "PersonOrganizationStatusID": null,         "PrimaryOrgRoleOrgZoneID": null,         "SetGroupID": null,         "IsExternal": null,         "PersonUsageTypeID": null,         "Department": null,         "Company": null,         "textToSearch": "*", "pageLength": 10, "resourceTags": null, "start": 0, "totalCount": null,         "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"OrgRoleOrgZoneFriendlyName\" SearchValue=\"Sales in Dublin\"  Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" SearchType=\"String\"/></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 people, SearchTerms encompass the Name, FriendlyName, Email, FirstName, LastName, and Login properties and when used, the API returns all people where the specified search value finds a match in any of those properties. For example, if the search value is set to “Jordan”, the API would return all the following people:

  • Any person with a first name containing the string

  • Any person with a last name containing the string

  • Any person with a login containing the string

  • Any person with an email address containing the string

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

Get all people where the search value for SearchTerms is set to "jordan."

{     "IncludedProperties": [         "PersonID",         "Active",         "LastName",         "FirstName",         "Login", "Email", "RiskFactorTotal",         "LastLoginDate"             ],     "Parameters": {         "ExternalApprovalID": null,         "GroupID": null,         "Active": null,         "CompanyID": null,         "CoreIdentityID": null,         "ManagementRoleID": null,         "OrgRoleID": null,         "OrgRoleOrgZoneID": null,         "OrgZoneID": null,         "OwnerAssigneeID": null,         "PersonOrganizationStatusID": null,         "PrimaryOrgRoleOrgZoneID": null,         "SetGroupID": null,         "IsExternal": null,         "PersonUsageTypeID": null,         "Department": null,         "Company": null,         "textToSearch": "*", "pageLength": 10, "resourceTags": null, "start": 0, "totalCount": null,         "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"jordan\" Operator=\"EqualTo\"  QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" SearchType=\"String\"/></Conditions>"     } }

 

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

{ "Tags": [], "Data": [ { "PersonID": 138016, "Active": true, "LastName": "Allison", "FirstName": "Jordan", "Login": "jordanalliso", "Email": "jordana@greatskywest.com", "RiskFactorTotal": 152, "LastLoginDate": "2020-10-12T19:17:38.723" }, { "PersonID": 2234, "Active": true, "LastName": "Armitage", "FirstName": "atinder", "Login": "Jordana.Armitage@eidproducts.onmicrosoft.com", "Email": "Jordana.Armitage@phdnetwork.com", "RiskFactorTotal": 370, "LastLoginDate": "2022-09-16T18:37:35.9" }, { "PersonID": 147269, "Active": true, "LastName": "Ballesteros", "FirstName": "Jordan", "Login": "jordanballe@eidproducts.onmicrosoft.com", "Email": "jordanballe@eidproducts.onmicrosoft.com", "RiskFactorTotal": 0, "LastLoginDate": null }, { "PersonID": 131221, "Active": true, "LastName": "Jordan", "FirstName": "Danny", "Login": "dannyjordan", "Email": "jordand@djenterprises.com", "RiskFactorTotal": 0, "LastLoginDate": null }, { "PersonID": 192191, "Active": true, "LastName": "Jordan", "FirstName": "Hal", "Login": "haljordan", "Email": "hal@glcorps.com", "RiskFactorTotal": 0, "LastLoginDate": null } ], "OutParameters": [] }

 

Get all people belonging to the “Sales in Dublin” Business Role and Location with a SearchTerm match equal to "Steve"

{     "IncludedProperties": [         "PersonID",         "Active",         "LastName",         "FirstName",         "Login", "Email", "RiskFactorTotal",         "LastLoginDate"             ], "Parameters": { "ExternalApprovalID": null, "GroupID": null, "Active": null, "CompanyID": null, "CoreIdentityID": null, "ManagementRoleID": null, "OrgRoleID": null, "OrgRoleOrgZoneID": null, "OrgZoneID": null, "OwnerAssigneeID": null, "PersonOrganizationStatusID": null, "PrimaryOrgRoleOrgZoneID": null, "SetGroupID": null, "IsExternal": null, "PersonUsageTypeID": null, "Department": null, "Company": null, "textToSearch": "*", "pageLength": 10, "resourceTags": null, "start": 0, "totalCount": null, "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"OrgRoleOrgZoneFriendlyName\" SearchValue=\"Sales in Dublin\" Operator=\"EqualTo\" QuerySuffix=\" AND \" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/><Condition PropertyName=\"SearchTerms\" SearchValue=\"Steve\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/></Conditions>" } }

 

Get all people where the SearchValue of the SearchTerm is an email address containing "contractors"

{     "IncludedProperties": [         "PersonID",         "Active",         "LastName",         "FirstName",         "Login", "Email", "RiskFactorTotal",         "LastLoginDate"             ], "Parameters": { "ExternalApprovalID": null, "GroupID": null, "Active": null, "CompanyID": null, "CoreIdentityID": null, "ManagementRoleID": null, "OrgRoleID": null, "OrgRoleOrgZoneID": null, "OrgZoneID": null, "OwnerAssigneeID": null, "PersonOrganizationStatusID": null, "PrimaryOrgRoleOrgZoneID": null, "SetGroupID": null, "IsExternal": null, "PersonUsageTypeID": null, "Department": null, "Company": null, "textToSearch": "*", "pageLength": 10, "resourceTags": null, "start": 0, "totalCount": null, "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"Email_*contractors\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/></Conditions>" } }



Sample Responses

Person Properties

The below table includes Person Properties that can be added to IncludedProperties.

Property

Returns

Property

Returns

PersonID

int

The PersonID of the person

FriendlyName

string

The Friendly Name of the person

 

Name

string

The full name of the person

Login

string

The EmpowerID login for the person

Email

string

The email address of the person

null if empty

EmailAlias

string

The email alias of the person

null if empty

PersonalEmail

string

The personal email address of the person

null if empty

ResourceID

int

The ResourceID of the person

PrimaryOrgRoleOrgZoneID

int

The ID of the person’s primary Business Role and Location

PersonGUID

string

The unique identifier for the person

Active

Boolean

True or False

PersonalTitle

string

The personal title

null if empty

FirstName

string

The person’s first name

MiddleName

string

The person’s middle name

null if empty

LastName

string

The person’s last name

SecondLastName

string

The person’s second last name

null if empty

GenerationalSuffix

string

The person’s generational suffix

null if empty

BirthName

string

The person’s birth name

null if empty

Initials

string

The person’s initials

null if empty

Title

string

The person’s title

null if empty

AboutMe

string

The information in the AboutMe field of a person

null if empty

StreetAddress

string

The person’s street address

null if empty

StreetAddress2

string

The second line of street address

null if empty

City

string

The person’s city

null if empty

State

string

The person’s state

null if empty

PostalCode

string

The person’s postal code

null if empty

Country

string

The person’s country

null if empty

Province

string

The person’s province

null if empty

Company

string

The person’s company

null if empty

Division

string

The person’s division

null if empty

Department

string

The person’s department

null if empty

DepartmentNumber

string

The person’s department number

null if empty

Office

string

The person’s office

null if empty

POBox

string