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
- START. The Candidate must provide an email address if one does not already exist.
- 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.
- The Candidate can setup the frequency of notifications (daily or weekly) and the validity period (2 weeks, 1 month, 3 months, 6 months).
- The Candidate is notified about the Search Agent creation. The notification can contain a link to update or remove the Search Agent.
- 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.
- 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.
- 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
https://api3.lumesse-talenthub.com/CareerPortal/SOAP/SearchAgent?wsdl
create
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.
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 |
| 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
Response Parameter
| Parameter | Data Type | Description |
|---|---|---|
| string |
String | Unique token identifying newly created search agent |
delete
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.
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
Response Parameter
| Parameter | Data Type | Description |
|---|---|---|
| void |
void |
getActiveSearchAgents
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
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
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 |
| 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 |
update
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.
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 |
| 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
Response Parameter
| Parameter | Data Type | Description |
|---|---|---|
| void |
void |