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 |
---|---|
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.
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 |
---|---|
PersonID
| The PersonID of the person |
FriendlyName
| The Friendly Name of the person
|
Name
| The full name of the person |
Login
| The EmpowerID login for the person |
| The email address of the person
|
EmailAlias
| The email alias of the person
|
PersonalEmail
| The personal email address of the person
|
ResourceID
| The ResourceID of the person |
PrimaryOrgRoleOrgZoneID
| The ID of the person’s primary Business Role and Location |
PersonGUID
| The unique identifier for the person |
Active
|
|
PersonalTitle
| The personal title
|
FirstName
| The person’s first name |
MiddleName
| The person’s middle name
|
LastName
| The person’s last name |
SecondLastName
| The person’s second last name
|
GenerationalSuffix
| The person’s generational suffix
|
BirthName
| The person’s birth name
|
Initials
| The person’s initials
|
Title
| The person’s title
|
AboutMe
| The information in the
|
StreetAddress
| The person’s street address
|
StreetAddress2
| The second line of street address
|
City
| The person’s city
|
State
| The person’s state
|
PostalCode
| The person’s postal code
|
Country
| The person’s country
|
Province
| The person’s province
|
Company
| The person’s company
|
Division
| The person’s division
|
Department
| The person’s department
|
DepartmentNumber
| The person’s department number
|
Office
| The person’s office
|
POBox
| The person’s Post Office Box
|
Location
| The person’s location
|
SocialSecurityNumber
| The person’s Social Security Number
|
NationalIdentificationNumber
| The person’s National Identification Number
|
CarLicense
| The person’s vehicle license plate number
|
DriversLicenseNumber
| The person’s driver’s license number
|
Ethnicity
| The person’s ethnicity
|
Gender
| The person’s gender
|
District
| The District for the person
|
Assistant
| The name of the assistant for the person
|
PhotoURL
| The Photo URL for the person
|
IMAddress
| The IM address for the person
|
SIPAddress
| The SIP address for the person
|
IdentityURL
| The Identity URL for a person
|
URLPersonal
| The Personal URL for a person
|
URLBusiness
| The Business URL for a person
|
URLOWA
| The OWA URL for a person
|
Telephone
| The telephone number for the person
|
MobilePhone
| The mobile phone number for the person
|
BusinessPhone
| The business phone number for the person
|
Pager
| The pager number for the person
|
HomeTelephone
| The home telephone number for the person
|
FAX
| The fax number of a person
|
Notes
| Notes about a person
|
MustChangePasswordOnNextLogin
| Specifies whether the person must change their password on their next login
|
LastLoginDate
| Date the person last logged in |
LastPasswordChangedDate
| Date the person’s password was changed |
FirstLoginFailedAttempt
| Date of the first logn failure for the person
|
FailedLoginAttemptsCount
| Number of failed lgoin attempts for the person
|
DisableSSOLogin
| Specifies whether the person can login via SSO
|
LockedUntil
| Date the person is locked out of the system due to login failures
|
Description
| Description of the person
|
ValidFrom
| Date the person account became valid
|
ValidUntil
| Date the person account becomes invalid
|
DateOfBirth
| Birth date of the person
|
CityOfBirth
| Birth city of the person
|
CountryOfBirth
| Birth country of the person
|
NationID
| Nation ID of the person
|
IsOutOfOffice
| Specifies the Out Of Office status of the person
|
EmployeeID
| Employee ID of the person
|
EmployeeIDOther
| Secondary Employee ID of tjhe person
|
ManagerPersonID
| PersonID of the person’s manager
|
EmployeeType
| The person’s Employee type
|
EmployeeTypeOther
| The person’s Secondary Employee type
|
MobilePhoneProviderID
| The ID of the person’s mobile phone provider
|
Status
| The person’s account status
|
LocaleID
| LocaleID of the person’s Locale
|
ProfileManagerLastUpdated
| The date the person’s profile was last updated
|
OrgRoleOrgZoneFriendlyName
| The Friendly Name of the person’s Business Role and Location |
CoreIdentityID
| The ID of the Core Identity linked to the person |
PersonProofingStatusFriendlyName
| The status of the person’s proofing status |
PersonManagerName
| The name of the person’s manager |
TimeConstrain
| Time constraint data for the person XML format |
TimeConstraintActive
| Specifies whether an active time constraint exists for the person
|
AllowLogin
| Specifies whether the person can log in
|
AllowPasswordOperations
| Specifies whether the person can update their passwords
|
AllowAttributeSync
| Specifies whether attribute sync is allowed between the person account and any owned external user accounts
|
AllowOrgRoleOrgZoneReEval
| Specifies whether the Business Role and Location of the person can be re-evaluated
|
LogonNameBeforeDeleted
| The logon name before the person account was deleted
|
Deleted
| Specifies whether the person account has been deleted
|
DeletedDate
| The date the person account was deleted
|
SessionDirtyDate
| The date of the person’s last session
|
RiskFactorTotal
| The total risk factor score associated with the person
|
RiskFactorTotalCalculated
| The date the person’s total risk factor score was calculated |
CreatedDate
| The date and time the person account was created in the system |
ModifiedDate
| The date and time any person attributes were modified for the person |
DisableNotifications
| Specifies whether system notifications are disabled for the person
|
DisableAsApprover
| Specifies whether approval notifications are disabled for the person
|
PreferredFirstName
| The preferred first name of the person
|
PreferredLastName
| The preferred last name of the person
|
ExpectedHireDate
| The expected hire date for the person
|
OriginalHireDate
| The person’s original hire date
|
TerminationDate
| The date the person was terminated from the company
|
OrganizationID
| The ID of the person’s organization |
LoginRequireDeviceRegistration
| Specifies whether the person’s devices must be registered to log in to the Web app
|
RequireSecondFactor
| Specifies whether second factor authentication is required for the person to log in
|
RequireSecondFactorForLDAP
| Specifies whether second factor authentication is required for the person to log in via LDAP
|
RequireSecondFactorForRadius
| Specifies whether second factor authentication is required for the person to log in via RADIUS
|
LastChatStatus
| The last chat status of the person
|
JobCode
| The peson's job code
|
PositionCode
| The person’s position code
|
DefaultHomePage
| The default home page of the Web application for the person
|
RoomNumber
| The person’s room number
|
BusinessCategory
| The business category for the person
|
OrgUnit
| The person’s org unit
|
SearchTerms
| Search terms used to return the person in the search fields of the Web application |
DistinguishedName
| Distinguished name of the person account |
CoreIdentityID
| ID of the person’s Core Identity object
|
ProcessStatus
| Process status for the person’s account
|
ProcessTime
| The date and time the system processed the person’s account |
DisabledDate
| The date the person’s account was disabled
|
OwnerAssigneeID
| Unique identifier of the owner of the person’s account
|
IsExternal
| Specifies whether the person is external to the organization
|
HRNumber
| The person’s HR Number
|
DepartmentType
| The person’s Department Type
|
DepartmentCode
| The person’s Department Code
|
CompanyType
| The person’s company type
|
CompanyCode
| The company code for the person
|
CostCenter
| The cost center for the person
|
BusinessUnit
| The person’s business unit
|
PositionID
| The ID of the person’s position
|
SiteCode
| The Site Code for the person’s site
|
SiteName
| The Site Name for the person’s site
|
WorkingCompany
| The Working Company of the person
|
PreferredLanguage
| The person’s preferred language
|
SuspensionStartDate
| The suspension start date for the person
|
SuspensionEndDate
| The suspension end date for the person
|
IsContingentWorker
| Specifies whether the person is a contingent worker
|
IsFullTimeEmployee
| Specifies whether the person is a full-time employee
|
WorkingDaysPerWeek
| The number of days per week the person works
|
StandardHours
| The standard hours for the person
|
WorkLocation
| The person’s work location
|
BusinessTitle
| The person’s Business Title
|
Region
| The person’s region
|
IsEmailAcountRequired
| Specifies whether an email account is required for the person
|
JobCodeDescription
| The person’s Department Code
|
JobLocationName
| The person’s Department Code
|
County
| The person’s county
|
StreetAddress3
| The third line of the person’s Street Address
|
PreferredState
| The person’s preferred state
|
ThirdName
| The person’s third name
|
CostCenterDescription
| The cost center description for the person
|
CompanyDescription
| The person’s company description
|
LeaveOfAbsenseActualReturnDate
| The date the person returned from a leave of absence
|
LeaveOfAbsenseExpectedReturnDate
| The date the person is expected to return from a leave of absence
|
LeaveOfAbsenseStartDate
| The date the person starts a leave of absense
|
LeaveOfAbsenseEndDate
| The date the person’s leave of absence ends
|
WorkOrderStartDate
| The work order start date for a person
|
WorkOrderEndDate
| The work order end date for a person
|
WorkOrderId
| The work order ID for a person
|
EffectiveStartDate
| The effective start date for a person
|
EffectiveEndDate
| The effective end date for a person
|
IsPrimary
| Specifies whether the account is the primary person
|
ExcludeFromResourceEntitlement
| Specifies whether the person is excluded from recieving any resource entitlements granted by provisioning policies.
|
IsSaaS
| Specifies whether the person is a SaaS account |
SendEmailAsEncrypted
| Specifies whether email is to be sent encrypted
|
PreferredDataLocation
| The preferred data location for a p
|
ChangeTS
| The date and time a change occured on the person |
OofEndDate
| Date and time a person’s Out of Office status ends
|
OofInternalMsg
| Out of Office message sent to internal users
|
OofExternalMsg
| Out of Office message sent to external users
|
OofAudience
| Out of Office audience
|
OofStatus
| Out of Office status
|
OofStartDate
| Date and time the person’s Out of Office status begins
|
BotConversationReferenceID
| Unique identifier of the person’s BOT conversation
|
CitizenNationID
| Nation ID for the person
|
Currency
| Currency used by the person
|
DefaultCurrency
| Default currency for the person
|