Career Portal Match Integration Guide

This guide explains how you can offer relevant job suggestions from open vacancies to job seekers, who can then easily apply to one or multiple jobs.

Use case: Match & Apply

A visitor of your Career Portal (the user) is interested in your jobs and wants to know which open positions best match their profile. The user provides CV/résumé via an upload button, and relevant information from their profile is parsed. The system compares the profile with open positions to provide the user with the best matching jobs. Finally, the user can apply with one click.

Recommendations

This guide describes calls to Textkernel web services, which should always be done from the server side. We recommend developing a wrapper or proxy API to handle the requests from the client.

Integration recipe

Textkernel SOAP services and credentials

For the 'match' part of this use case, four Textkernel services and two sets of credentials are needed. All calls are HTTP GET or POST and SOAP is used.

Component	Namespace
Search!	https://home.textkernel.nl/match-SearchBox3/soap/
Extract!	https://home.textkernel.nl/match/soap/extract/

Note: The URL domain (e.g. https://home.textkernel.nl/) may be different for your installation. Please check with your Textkernel consultant.

Furthermore, for the 'apply' part of this use case, there is a need for custom development on the integrating party or customer side for getting the candidate information into the receiving ATS or other system.

Endpoints overview

	Component	Service	Endpoint	Credentials
1	Search!	Authentication	/authentication	vacancy environment name and password
2	Search!	Match! Query extraction	/queryextraction	access token
3	Search!	Search	/v5/search	access token
4	Search!	Search using queryParts	/v5/search	access token
5	Extract!	CV/resume parsing	/extract	candidate account, user name and password

1. Search! - Authentication

Request an authentication token for Search!. When Search! returns an error because of an expired access token, it is recommended to first request a new token and then rerun the original search request.

Request

Endpoint: /authentication

Method: authenticate

Parameter name	Type	Description
environment	string	identifier of a Search environment
password	string	password for the Search environment
accessRoles	list of strings	the access roles to be granted to the user of the token. For this use case, use 'all'

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://home.textkernel.nl/search">
   <soapenv:Header/>
   <soapenv:Body>
      <sear:authenticate>
         <environment>environment-name</environment>
         <password>password</password>
         <accessRoles>all</accessRoles>
      </sear:authenticate>
   </soapenv:Body>
</soapenv:Envelope>

Response

The response only contains the token to access the Search! operations.

Example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:authenticateResponse xmlns:ns2="http://home.textkernel.nl/search">
         <return>ad13a9c8-3d11-4dca-b4e6-2df758ff485f</return>
      </ns2:authenticateResponse>
   </soap:Body>
</soap:Envelope>

2. Search! - Get Match! Query

Request

Endpoint: /queryextraction

Method: extractFromFileWithToken

Parameter name	Type	Description
accessToken	string	access token obtained in step #1
filename	string	Filename of the document to process
fileContent	byte array	Binary file content of the document to process encoded in base64

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://home.textkernel.nl/search">
   <soapenv:Header/>
   <soapenv:Body>
      <sear:extractFromFileWithToken>
         <accessToken>accesstoken</accessToken>
         <filename>filename</filename>
         <fileContent>base64encoded-file</fileContent>
      </sear:extractFromFileWithToken>
   </soapenv:Body>
</soapenv:Envelope>

Response

The response contains Match! query to be used in the next step.

Example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:extractFromFileWithTokenResponse xmlns:ns2="http://home.textkernel.nl/search">
         <return>^vacancytitle:[Credit Analyst] %jobgroupidsonlyrecent:"254" ^city:"US 22201"+50 %langskills:"EN" %langskills:"ES" %experienceyears:>10 %educationlevel_international:"4" %compskills:"Microsoft Word" %compskills:"Power Point" %compskills:"Excel"</return>
      </ns2:extractFromFileWithTokenResponse>
   </soap:Body>
</soap:Envelope>

3. Search! - Search for relevant jobs

Once a Match! query has been obtained, it is possible to retrieve jobs that are relevant to the profile of the candidate.

Request

Endpoint: /search

Method: searchWithToken

Parameter name	Type	Description
accessToken	string	access token obtained in step #1
Search! request	string	Search Request object

Search! Request object

Parameter name	Type	Description	Value for this use case
query	string	search query	Match! query obtained in step #2
searchEngine	string	Name of the Search repository to use. If empty, the default will be used	Your Textkernel consultant will provide you with the right values
resultFields	string	fields to be returned in the response	Your Textkernel consultant will provide you with the right values
suppressFacetCounts	boolean	When facets are not needed, this field can be false

Note: For more options regarding the Search! Request object options, refer to the Search! documentation.

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://home.textkernel.nl/search">
   <soapenv:Header/>
   <soapenv:Body>
      <sear:searchWithToken>
         <accessToken>ad13a9c8-3d11-4dca-b4e6-2df758ff485f</accessToken>
         <request>
            <query>^vacancytitle:[Credit Analyst] %jobgroupidsonlyrecent:"254" ^city:"US 22201"+50 %langskills:"EN" %langskills:"ES" %experienceyears:>10 %educationlevel_international:"4" %compskills:"Microsoft Word" %compskills:"Power Point" %compskills:"Excel" %"Value Added Resellers" %"financials" %"maintaining those accounts" %"retail" %"setting credit lines" %"Sales and Commerce" %[Sales] %[Commerce]</query>
            <searchEngine>vacancies</searchEngine>
            <resultFields>documentdate</resultFields>
            <resultFields>employer</resultFields>
            <resultFields>city</resultFields>
            <resultFields>contracttype</resultFields>
            <resultFields>vacsnippet</resultFields>
            <suppressFacetCounts>false</suppressFacetCounts>
         </request>
      </sear:searchWithToken>
   </soapenv:Body>
</soapenv:Envelope>

Response

For details on the response, refer to the Search! documentation, section: Object structures, Search Result.

Searching for a specific document

It is also possible to send a document ID to retrieve a specific job. This is helpful when wanting to display the details of a job instead of only a snippet. The structure of the search request is the same, and the document ID can be sent like so:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://home.textkernel.nl/search">
  <soapenv:Header/>
  <soapenv:Body>
     <sear:searchWithToken>
        <accessToken>ad13a9c8-3d11-4dca-b4e6-2df758ff485f</accessToken>
        <request>
            <query>docid:2d243fe59ff14e2e8d9fa348c90ff515</query>
            <searchEngine>vacancies</searchEngine>
            <resultOffset>0</resultOffset>
        </request>
     </sear:searchWithToken>
  </soapenv:Body>
</soapenv:Envelope>

4. Search! - Modify the query to refine the search

Once a Search! result has been obtained, it is possible to modify individual query parts in order to refine the search and retrieve jobs that are relevant to the profile of the candidate.

Request

Endpoint: /search

Method: searchWithToken

Parameter name	Type	Description
accessToken	string	access token obtained in step #1
Search! request	string	Search Request object

Search! Request object

Parameter name	Type	Description	Value for this use case
queryParts	list of QueryPart	search query	(modified) QueryParts obtained in the response from step #3
searchEngine	string	Name of the Search repository to use. If empty, the default will be used	Your Textkernel consultant will provide you with the right values
resultFields	string	fields to be returned in the response	Your Textkernel consultant will provide you with the right values
suppressFacetCounts	boolean	When facets are not needed, this field can be false

Note: For more options regarding the Search! Request object options, refer to the Search! documentation.

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://home.textkernel.nl/search">
   <soapenv:Header/>
   <soapenv:Body>
      <sear:searchWithToken>
         <accessToken>ad13a9c8-3d11-4dca-b4e6-2df758ff485f</accessToken>
         <request>
            <queryParts>
               <field>vacancytitle</field>
               <fieldLabel>vacancytitle</fieldLabel>
               <condition>STRONGLY_FAVORED</condition>
               <weight>1.0</weight>
               <items>
                  <value>[Credit Analyst]</value>
                  <label>[Credit Analyst]</label>
               </items>
            </queryParts>
            <queryParts>
               <field>city</field>
               <condition>STRONGLY_FAVORED</condition>
               <weight>1.0</weight>
               <items>
                  <value>US 85483</value>
                  <label>US 85483</label>
               </items>
               <fieldLabel>city</fieldLabel>
            </queryParts>
            <queryParts>
               <field>langskills</field>
               <condition>FAVORED</condition>
               <weight>1.0</weight>
               <items>
                  <value>EN</value>
                  <label>EN</label>
               </items>
               <fieldLabel>langskills</fieldLabel>
            </queryParts>
            <queryParts>
               <field>experienceyears</field>
               <fieldLabel>experienceyears</fieldLabel>
               <condition>FAVORED</condition>
               <weight>1.0</weight>
               <items>
                  <value>>10</value>
                  <label>>10</label>
               </items>
            </queryParts>
            <searchEngine>vacancies</searchEngine>
            <resultFields>documentdate</resultFields>
            <resultFields>employer</resultFields>
            <resultFields>city</resultFields>
            <resultFields>contracttype</resultFields>
            <resultFields>vacsnippet</resultFields>
            <suppressFacetCounts>false</suppressFacetCounts>
            <resultOffset>0</resultOffset>
         </request>
      </sear:searchWithToken>
   </soapenv:Body>
</soapenv:Envelope>

Response

For details on the response, refer to the Search! documentation, sections: Object structures:

• Search Result

• QueryPart

• QueryPartItem

5. Extract! - Parse a CV/resume

Finally, the document that the candidate uploaded can be sent to the Extract! service in order to get structured information from it. This information can then be sent to an ATS or other system. It is the responsibility of the integrating party to handle this part of the workflow.

Request

Endpoint: /extract

Method: extract

Parameter	Description	Content type
account	Extract! account	string
username	Extract! username	string
password	Extract! password	string
filename	The name of the file to be processed	string
fileContent	The uploaded file encoded in base64	binary

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ext="http://home.textkernel.nl/sourcebox/soap/extract">
   <soapenv:Header/>
   <soapenv:Body>
      <ext:extract>
         <account>accountname</account>
         <username>username</username>
         <password>password</password>
         <fileName>filename</fileName>
         <fileContent>base64content</fileContent>
      </ext:extract>
   </soapenv:Body>
</soapenv:Envelope>

Response

Example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:extractResponse xmlns:ns2="http://home.textkernel.nl/sourcebox/soap/extract">
         <return><![CDATA[{
             "lang": "english",
             "file": "filename",
             "lastModified": "yyyy-MM-DDTHH:mm",
             "personal": {
              "firstName": "candidatesfirstName",
              "middleName": "candidatesmiddleName",
              "lastName": "candidateslastName",
              "dateOfBirth": "yyyy-MM-DD", 
              [...]
         }]]> 
        </return>
      </ns2:extractResponse>
   </S:Body>
</S:Envelope>

Note: Check with your Textkernel consultant to learn more about the full response format.