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 a number of 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 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 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 below value.

"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 below examples demonstrate how to use 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 that 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.

 

SearchTerms

Each identity object in the EmpowerID Identity Warehouse has a SearchTerms property with a specific set of search values that can 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 to return a subset of people:

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

 

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

 

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

 

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



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

The person’s Post Office Box

null if empty

Location

string

The person’s location

null if empty

SocialSecurityNumber

string

The person’s Social Security Number

null if empty

NationalIdentificationNumber

string

The person’s National Identification Number

null if empty

CarLicense

string

The person’s vehicle license plate number

null if empty

DriversLicenseNumber

string

The person’s driver’s license number

null if empty

Ethnicity

string

The person’s ethnicity

null if empty

Gender

string

The person’s gender

null if empty

District

string

The District for the person

null if empty

Assistant

string

The name of the assistant for the person

null if empty

PhotoURL

string

The Photo URL for the person

null if empty

IMAddress

string

The IM address for the person

null if empty

SIPAddress

string

The SIP address for the person

null if empty

IdentityURL

string

The Identity URL for a person

null if empty

URLPersonal

string

The Personal URL for a person

null if empty

URLBusiness

string

The Business URL for a person

null if empty

URLOWA

string

The OWA URL for a person

null if empty

Telephone

string

The telephone number for the person

null if empty

MobilePhone

string

The mobile phone number for the person

null if empty

BusinessPhone

string

The business phone number for the person

null if empty

Pager

string

The pager number for the person

null if empty

HomeTelephone

string

The home telephone number for the person

null if empty

FAX

string

The fax number of a person

null if empty

Notes

string

Notes about a person

null if empty

MustChangePasswordOnNextLogin

Boolean

Specifies whether the person must change their password on their next login

True or False

LastLoginDate

DateTime

Date the person last logged in

LastPasswordChangedDate

DateTime

Date the person’s password was changed

FirstLoginFailedAttempt

DateTime

Date of the first logn failure for the person

null if empty

FailedLoginAttemptsCount

int

Number of failed lgoin attempts for the person

0 if no failed attempts

DisableSSOLogin

Boolean

Specifies whether the person can login via SSO

True or False

LockedUntil

DateTime

Date the person is locked out of the system due to login failures

null if empty

Description

string

Description of the person

null if empty

ValidFrom

DateTime

Date the person account became valid

null if empty

ValidUntil

DateTime

Date the person account becomes invalid

null if empty

DateOfBirth

DateTime

Birth date of the person

null if empty

CityOfBirth

string

Birth city of the person

null if empty

CountryOfBirth

string

Birth country of the person

null if empty

NationID

int

Nation ID of the person

null if empty

IsOutOfOffice

Boolean

Specifies the Out Of Office status of the person

True or False

EmployeeID

string

Employee ID of the person

null if empty

EmployeeIDOther

string

Secondary Employee ID of tjhe person

null if empty

ManagerPersonID

int

PersonID of the person’s manager

null if empty

EmployeeType

string

The person’s Employee type

null if empty

EmployeeTypeOther

string

The person’s Secondary Employee type

null if empty

MobilePhoneProviderID

int

The ID of the person’s mobile phone provider

null if empty

Status

string

The person’s account status

Active or Disabled

LocaleID

int

LocaleID of the person’s Locale

null if empty

ProfileManagerLastUpdated

DateTime

The date the person’s profile was last updated

null if empty

OrgRoleOrgZoneFriendlyName

string

The Friendly Name of the person’s Business Role and Location

CoreIdentityID

int

The ID of the Core Identity linked to the person

PersonProofingStatusFriendlyName

string

The status of the person’s proofing status

PersonManagerName

string

The name of the person’s manager

TimeConstrain

XML

Time constraint data for the person

XML format

TimeConstraintActive

Boolean

Specifies whether an active time constraint exists for the person

True or False

AllowLogin

Boolean

Specifies whether the person can log in

True or False

AllowPasswordOperations

Boolean

Specifies whether the person can update their passwords

True or False

AllowAttributeSync

Boolean

Specifies whether attribute sync is allowed between the person account and any owned external user accounts

True or False

AllowOrgRoleOrgZoneReEval

Boolean

Specifies whether the Business Role and Location of the person can be re-evaluated

True or False

LogonNameBeforeDeleted

string

The logon name before the person account was deleted

null if the person has not been deleted

Deleted

Boolean

Specifies whether the person account has been deleted

True or False

DeletedDate

DateTime

The date the person account was deleted

null if the person has not been deleted

SessionDirtyDate

DateTime

The date of the person’s last session

null if empty

RiskFactorTotal

int

The total risk factor score associated with the person

null if empty

RiskFactorTotalCalculated

DateTime

The date the person’s total risk factor score was calculated

CreatedDate

DateTime

The date and time the person account was created in the system

ModifiedDate

DateTime

The date and time any person attributes were modified for the person

DisableNotifications

Boolean

Specifies whether system notifications are disabled for the person

True or False

DisableAsApprover

Boolean

Specifies whether approval notifications are disabled for the person

True or False

PreferredFirstName

string

The preferred first name of the person

null if empty

PreferredLastName

string

The preferred last name of the person

null if empty

ExpectedHireDate

DateTime

The expected hire date for the person

null if empty

OriginalHireDate

DateTime

The person’s original hire date

null if empty

TerminationDate

DateTime

The date the person was terminated from the company

null if empty

OrganizationID

string

 

The ID of the person’s organization

LoginRequireDeviceRegistration

Boolean

Specifies whether the person’s devices must be registered to log in to the Web app

True or False

RequireSecondFactor

Boolean

Specifies whether second factor authentication is required for the person to log in

True or False

RequireSecondFactorForLDAP

Boolean

Specifies whether second factor authentication is required for the person to log in via LDAP

True or False

RequireSecondFactorForRadius

Boolean

Specifies whether second factor authentication is required for the person to log in via RADIUS

True or False

LastChatStatus

string

The last chat status of the person

null if empty

JobCode

string

The peson's job code

null if empty

PositionCode

string

The person’s position code

null if empty

DefaultHomePage

string

The default home page of the Web application for the person

null if empty

RoomNumber

string

The person’s room number

null if empty

BusinessCategory

string

The business category for the person

null if empty

OrgUnit

string

The person’s org unit

null if empty

SearchTerms

string

Search terms used to return the person in the search fields of the Web application

DistinguishedName

strimng

Distinguished name of the person account

CoreIdentityID

string

ID of the person’s Core Identity object

null if empty

ProcessStatus

int

Process status for the person’s account

2 for provisioned

ProcessTime

DateTime

The date and time the system processed the person’s account

DisabledDate

DateTime

The date the person’s account was disabled

null if empty

OwnerAssigneeID

string

Unique identifier of the owner of the person’s account

null if empty

IsExternal

Boolean

Specifies whether the person is external to the organization

True or False

HRNumber

string

The person’s HR Number

null if empty

DepartmentType

string

The person’s Department Type

null if empty

DepartmentCode

string

The person’s Department Code

null if empty

CompanyType

string

The person’s company type

null if empty

CompanyCode

string

The company code for the person

null if empty

CostCenter

string

The cost center for the person

null if empty

BusinessUnit

string

The person’s business unit

null if empty

PositionID

string

The ID of the person’s position

null if empty

SiteCode

string

The Site Code for the person’s site

null if empty

SiteName

string

The Site Name for the person’s site

null if empty

WorkingCompany

string

The Working Company of the person

null if empty

PreferredLanguage

string

The person’s preferred language

null if empty

SuspensionStartDate

DateTime

The suspension start date for the person

null if empty

SuspensionEndDate

DateTime

The suspension end date for the person

null if empty

IsContingentWorker

Boolean (nullable)

Specifies whether the person is a contingent worker

null if not set

IsFullTimeEmployee

Boolean (nullable)

Specifies whether the person is a full-time employee

null if not set

WorkingDaysPerWeek

int

The number of days per week the person works

null if empty

StandardHours

int

The standard hours for the person

null if empty

WorkLocation

string

The person’s work location

null if empty

BusinessTitle

string

The person’s Business Title

null if empty

Region

string

The person’s region

null if empty

IsEmailAcountRequired

Boolean (nullble)

Specifies whether an email account is required for the person

null if not set

JobCodeDescription

string

The person’s Department Code

null if empty

JobLocationName

string

The person’s Department Code

null if empty

County

string

The person’s county

null if empty

StreetAddress3

string

 

The third line of the person’s Street Address

null if empty

PreferredState

string

The person’s preferred state

null if empty

ThirdName

string

The person’s third name

null if empty

CostCenterDescription

string

The cost center description for the person

null if empty

CompanyDescription

string

The person’s company description

null if empty

LeaveOfAbsenseActualReturnDate

DateTime

The date the person returned from a leave of absence

null if empty

LeaveOfAbsenseExpectedReturnDate

DateTime

The date the person is expected to return from a leave of absence

null if empty

LeaveOfAbsenseStartDate

DateTime

The date the person starts a leave of absense

null if empty

LeaveOfAbsenseEndDate

DateTime

The date the person’s leave of absence ends

null if empty

WorkOrderStartDate

DateTime

The work order start date for a person

null if empty

WorkOrderEndDate

DzateTime

The work order end date for a person

null if empty

WorkOrderId

String

The work order ID for a person

null if empty

EffectiveStartDate

DateTime

The effective start date for a person

null if empty

EffectiveEndDate

DateTime

The effective end date for a person

null if empty

IsPrimary

Boolean

Specifies whether the account is the primary person

True or False

ExcludeFromResourceEntitlement

Boolean

Specifies whether the person is excluded from recieving any resource entitlements granted by provisioning policies.

True or False

IsSaaS

Boolean

Specifies whether the person is a SaaS account
True or False

SendEmailAsEncrypted

Boolean

Specifies whether email is to be sent encrypted

True or False

PreferredDataLocation

string

The preferred data location for a p

null if empty

ChangeTS

DateTime

The date and time a change occured on the person

OofEndDate

DateTime

Date and time a person’s Out of Office status ends

null if empty

OofInternalMsg

string

Out of Office message sent to internal users

null if empty

OofExternalMsg

string

Out of Office message sent to external users

null if empty

OofAudience

string

Out of Office audience

null if empty

OofStatus

string

Out of Office status

null if empty

OofStartDate

DateTime

Date and time the person’s Out of Office status begins

null if empty

BotConversationReferenceID

string

Unique identifier of the person’s BOT conversation

null if empty

CitizenNationID

int

Nation ID for the person

null if empty

Currency

string

Currency used by the person

null if empty

DefaultCurrency

string

Default currency for the person

null if empty