Search Agent

The Search Agent is used when creating rules for sending alerts to candidates.

 

Typical workflow

 

Use Case

The Search Agent API is used to create a Search Agent (Job Alerts) for job postings which may be of interest to Candidates. Candidates can select from a variety of search criteria and also define the validity period.

Pre-condition - The Talent Portal and Search Agent must be activated for the site in order to use the service.

Scenario

  1. START. The Candidate must provide an email address if one does not already exist.
  2. The Candidate sets up the Search criteria. If the Candidate has come from the List page, the Search criteria are pre-filled with the criteria from the List.
  3. The Candidate can setup the frequency of notifications (daily or weekly) and the validity period (2 weeks, 1 month, 3 months, 6 months).
  4. The Candidate is notified about the Search Agent creation. The notification can contain a link to update or remove the Search Agent.
  5. Either daily or weekly, depending on the frequency previously selected, the Candidate is notified of any relevant jobs posted on the careers site. The notification contains links to the job descriptions, and also contains a link to either update or remove the Search Agent.
  6. If the Candidate updates the Search Agent criteria, frequency of notifications or validity period, the criteria and settings are saved immediately; notifications are then generated based on the new criteria.
  7. If the Candidate removes the Search Agent, notifications are no longer received. END

Please note: Maximum 20 search agents can be created for one email address.

Response Format

XML

SOAP METHODS

The method creates a new search agent and returns a unique token ID.
It can be called with anonymous access or using candidate credentials.

For anonymous access (candidate does not have TalentPortal created)
The user name must be set to the following format: TechnicalID:guest:FO.
The password must be set to "guest".


Candidate credentials (candidate portal is created and active):
The user name must be set to the following format for example: TechnicalID:saif:FO
The password must be the candidates password used for example: "Saif123!"

When candidate credentials are used then the email address is not required to be provided as request parameter.
System uses the email assigned to candidate in such case.

Post Parameter

 
Parameter Data Type Description
searchAgentDto
SearchAgentDto [mandatory]
  expirationDate
Date [mandatory] The date on which to stop sending matching jobs. Example: 2030-11-23T00:00:00+01:00
  deliveryFrequency
SearchAgentDto.DeliveryFrequency [mandatory] Can be "ONCE_A_WEEK" or "ONCE_A_DAY"
  searchCriteria
SearchCriteriaDto [mandatory] A complex type containing the search criteria to apply. Note: none of the child elements are mandatory, although a minimum empty tag is required.
    categoryLists
List Specifies list of categoryLists. This can be used to filter applications by category criterion. e.g. <categoryLists> <categoryList> <categoryIds> <categoryId>41</categoryId> <categoryId>42</categoryId> </categoryIds> </categoryList> <categoryList> <categoryIds> <categoryId>89</categoryId> </categoryIds> </categoryList> </categoryLists>
      categoryList
CategoryNameDto List of categories for the search criteria
        categoryIds
List Specifies list of category criterion IDs. More than one category criterion ID can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped.
          categoryId
Long Value of the categorylist ID
        order
Integer Order of the list
    contractTypes
List Specifies list of contractType IDs. This can be used to filter applications by contractType. More than one contractType can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <contractTypes> <contractType>107</contractType> <contractType>107</contractType> </contractTypes>
      contractType
Long Provide value Id
    regions
List Specifies list of region IDs. This can be used to filter applications by region. More than one region id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <regions> <region>251</region> <region>252</region> </regions>
      region
Long Please use the region ID
    postedSince
Integer Specifies days since application post date search criterion. For example: 7
    generalApplication
Boolean Specifies is application a General Application search criterion. Values to be used "TRUE" or "FALSE"
    customLovs
List Specifies list of Custom LOV groups. This can be used to filter applications by Custom LOV. More than one Custom LOV group can be added. Depending on how the payload is formed, search logic applied will change. e.g. e.g.: Logic applied: 123 OR 124 <customLovs> <customLovGroup> <customLov>123</customLov> <customLov>124</customLov> </customLovGroup> </customLovs> e.g.: Logic applied: 123 AND 124 123 124
      customLovGroup
CustomLovGroup Can add more than one customLovGRoup which consists of customLov
        customLov
Long Custom LOV's ID. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped.
    scheduleTypes
List Specifies list of scheduleType IDs. This can be used to filter applications by scheduleType. More than one scheduleType id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <scheduleTypes> <scheduleType>341</scheduleType> <scheduleType>342</scheduleType> </scheduleTypes>
      scheduleType
Long Please use scheduleType ID
    jobNumber
String Specifies position ref number search criterion. For example: TEST00032
    organizationIds
List Specifies list of Organization IDs. This can be used to filter applications by organization. More than one organization id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <organizationIds> <organizationId>102</organizationId> <organizationId>103</organizationId> </organizationIds>
      organizationId
Long Use the organization ID related to the position
    countries
List Specifies list of country IDs. This can be used to filter applications by country. More than one country can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <countries> <country>1121</country> <country>1122</country> </countries>
      country
Long Provide country ID
    keywords
String Specifies keywords to be found in advertisement.
    adLanguages
List Specifies list of languages of advertisements. e.g.: <adLanguages> <language>UK</language> <language>DE</language> </adLanguages>
      language
String specific language possible values: Click to see possible values
  email
String [mandatory] Email of the user in the Lumesse BackOffice
sendEmail
boolean TRUE or FALSE - In order to send out a Welcome email please set to TRUE
language
LangCode [mandatory] possible values: Click to see possible values

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
string
String Unique token identifying newly created search agent
Marks for deletion Search Agent for given token. This method changes Search Agent status to "Suspended". Actual removal is performed by a batch.

Method can be called with anonymous access or using candidate credentials.
In both cases parameters and outcome is the same though.

Post Parameter

 
Parameter Data Type Description
token
String Example: 55a16187-8cca-4f5b-a622-510ba2756f15

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
void
void
The method getActiveSearchAgents returns list of all active search agents for given FO user.

If method is called with guest credentials then token is required and only search agent for given token is returned.

If method is called with candidate credentials then token is not used and response displays ALL active search agents related to the candidate.

Method returns empty list if:
- logged FO user does not have any search agent defined
- search agent feature is deactivated for a site
- token is invalid

Post Parameter

 
Parameter Data Type Description
token
String Example: 55a16187-8cca-4f5b-a622-510ba2756f15

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
searchAgentDetails
List
  expirationDate
Date [mandatory] The date on which to stop sending matching jobs. Example: 2030-11-23T00:00:00+01:00
  deliveryFrequency
SearchAgentDto.DeliveryFrequency [mandatory] Can be "ONCE_A_WEEK" or "ONCE_A_DAY"
  searchCriteria
SearchCriteriaDto [mandatory] A complex type containing the search criteria to apply. Note: none of the child elements are mandatory, although a minimum empty tag is required.
    categoryLists
List Specifies list of categoryLists. This can be used to filter applications by category criterion. e.g. <categoryLists> <categoryList> <categoryIds> <categoryId>41</categoryId> <categoryId>42</categoryId> </categoryIds> </categoryList> <categoryList> <categoryIds> <categoryId>89</categoryId> </categoryIds> </categoryList> </categoryLists>
      categoryList
CategoryNameDto List of categories for the search criteria
        categoryIds
List Specifies list of category criterion IDs. More than one category criterion ID can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped.
          categoryId
Long Value of the categorylist ID
        order
Integer Order of the list
    contractTypes
List Specifies list of contractType IDs. This can be used to filter applications by contractType. More than one contractType can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <contractTypes> <contractType>107</contractType> <contractType>107</contractType> </contractTypes>
      contractType
Long Provide value Id
    regions
List Specifies list of region IDs. This can be used to filter applications by region. More than one region id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <regions> <region>251</region> <region>252</region> </regions>
      region
Long Please use the region ID
    postedSince
Integer Specifies days since application post date search criterion. For example: 7
    generalApplication
Boolean Specifies is application a General Application search criterion. Values to be used "TRUE" or "FALSE"
    customLovs
List Specifies list of Custom LOV groups. This can be used to filter applications by Custom LOV. More than one Custom LOV group can be added. Depending on how the payload is formed, search logic applied will change. e.g. e.g.: Logic applied: 123 OR 124 <customLovs> <customLovGroup> <customLov>123</customLov> <customLov>124</customLov> </customLovGroup> </customLovs> e.g.: Logic applied: 123 AND 124 123 124
      customLovGroup
CustomLovGroup Can add more than one customLovGRoup which consists of customLov
        customLov
Long Custom LOV's ID. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped.
    scheduleTypes
List Specifies list of scheduleType IDs. This can be used to filter applications by scheduleType. More than one scheduleType id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <scheduleTypes> <scheduleType>341</scheduleType> <scheduleType>342</scheduleType> </scheduleTypes>
      scheduleType
Long Please use scheduleType ID
    jobNumber
String Specifies position ref number search criterion. For example: TEST00032
    organizationIds
List Specifies list of Organization IDs. This can be used to filter applications by organization. More than one organization id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <organizationIds> <organizationId>102</organizationId> <organizationId>103</organizationId> </organizationIds>
      organizationId
Long Use the organization ID related to the position
    countries
List Specifies list of country IDs. This can be used to filter applications by country. More than one country can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <countries> <country>1121</country> <country>1122</country> </countries>
      country
Long Provide country ID
    keywords
String Specifies keywords to be found in advertisement.
    adLanguages
List Specifies list of languages of advertisements. e.g.: <adLanguages> <language>UK</language> <language>DE</language> </adLanguages>
      language
String specific language possible values: Click to see possible values
  id
Long
  email
String [mandatory] Email of the user in the Lumesse BackOffice
  token
String Example: 55a16187-8cca-4f5b-a622-510ba2756f15
Allows updating Search Agent.
Method can be called with anonymous access or using candidate credentials.

When candidate credentials are used then the email address is not required to be provided as request parameter.
System uses the email assigned to candidate in such case.

Post Parameter

 
Parameter Data Type Description
searchAgentDto
SearchAgentDto [mandatory]
  expirationDate
Date [mandatory] The date on which to stop sending matching jobs. Example: 2030-11-23T00:00:00+01:00
  deliveryFrequency
SearchAgentDto.DeliveryFrequency [mandatory] Can be "ONCE_A_WEEK" or "ONCE_A_DAY"
  searchCriteria
SearchCriteriaDto [mandatory] A complex type containing the search criteria to apply. Note: none of the child elements are mandatory, although a minimum empty tag is required.
    categoryLists
List Specifies list of categoryLists. This can be used to filter applications by category criterion. e.g. <categoryLists> <categoryList> <categoryIds> <categoryId>41</categoryId> <categoryId>42</categoryId> </categoryIds> </categoryList> <categoryList> <categoryIds> <categoryId>89</categoryId> </categoryIds> </categoryList> </categoryLists>
      categoryList
CategoryNameDto List of categories for the search criteria
        categoryIds
List Specifies list of category criterion IDs. More than one category criterion ID can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped.
          categoryId
Long Value of the categorylist ID
        order
Integer Order of the list
    contractTypes
List Specifies list of contractType IDs. This can be used to filter applications by contractType. More than one contractType can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <contractTypes> <contractType>107</contractType> <contractType>107</contractType> </contractTypes>
      contractType
Long Provide value Id
    regions
List Specifies list of region IDs. This can be used to filter applications by region. More than one region id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <regions> <region>251</region> <region>252</region> </regions>
      region
Long Please use the region ID
    postedSince
Integer Specifies days since application post date search criterion. For example: 7
    generalApplication
Boolean Specifies is application a General Application search criterion. Values to be used "TRUE" or "FALSE"
    customLovs
List Specifies list of Custom LOV groups. This can be used to filter applications by Custom LOV. More than one Custom LOV group can be added. Depending on how the payload is formed, search logic applied will change. e.g. e.g.: Logic applied: 123 OR 124 <customLovs> <customLovGroup> <customLov>123</customLov> <customLov>124</customLov> </customLovGroup> </customLovs> e.g.: Logic applied: 123 AND 124 123 124
      customLovGroup
CustomLovGroup Can add more than one customLovGRoup which consists of customLov
        customLov
Long Custom LOV's ID. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped.
    scheduleTypes
List Specifies list of scheduleType IDs. This can be used to filter applications by scheduleType. More than one scheduleType id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <scheduleTypes> <scheduleType>341</scheduleType> <scheduleType>342</scheduleType> </scheduleTypes>
      scheduleType
Long Please use scheduleType ID
    jobNumber
String Specifies position ref number search criterion. For example: TEST00032
    organizationIds
List Specifies list of Organization IDs. This can be used to filter applications by organization. More than one organization id can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <organizationIds> <organizationId>102</organizationId> <organizationId>103</organizationId> </organizationIds>
      organizationId
Long Use the organization ID related to the position
    countries
List Specifies list of country IDs. This can be used to filter applications by country. More than one country can be added. To obtain possible IDs use FoAdvert.getCriteria or FoAdvert.getStandardCriteria. Invalid values will be skipped. e.g. <countries> <country>1121</country> <country>1122</country> </countries>
      country
Long Provide country ID
    keywords
String Specifies keywords to be found in advertisement.
    adLanguages
List Specifies list of languages of advertisements. e.g.: <adLanguages> <language>UK</language> <language>DE</language> </adLanguages>
      language
String specific language possible values: Click to see possible values
  email
String [mandatory] Email of the user in the Lumesse BackOffice
token
String Example: 55a16187-8cca-4f5b-a622-510ba2756f15
language
LangCode This is the overall language of the SearchAgent create method: specific language possible values: Click to see possible values

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
void
void