Candidate PIF Webservice

Please Note: this webservice is to be used with Old Appliciation Forms and is NOT to be used with RAC - Responsible Application Component.

The Candidate PIF Webservice (Simplified ApplicationProcess WS) gives a customer the possibility to create a flexible and bespoke one-page application process and implement it on their career site.

Using the Methods available within that web service it is possible to create candidates with their applications within TalentLink as well as adding their attachments.

This Web service includes three new methods:

  • getPifStructure – this method is used to get the most recent structure of Personal Information Form (PIF) assigned to the  relevant posting
  • submitApplication - this method is used to create the candidate’s application in TalentLink based on provided filled forms.
  • savePif – this method creates the candidate’s application in TalentLink with correctly structured PIF
  • addAttachment – this method adds attachment/s to the candidate’s application created by savePif method

Typical workflow

Use Case

This new Web service supports customers in the creation of a simple application process which allows candidates to put all their data onto a single page and submit this application without going through a more complex application process extended over several pages as traditional with TalentLink.

Customers can build a custom one page application process based on the structure of the assigned PIF. Customers may then build their career site with no lay-out and style constraints.

Pre-requisites:

A candidate’s application will be created against relevant postings which first have to be fetched using dedicated web service methods available in different bundles/projects.

The structure of the PIF has to be defined in TalentLink back office and assigned to relevant application process and to relevant advertisements (known as postings). Advertisement should be posted to career site (technical ID) from where candidates will be created.

 

An example scenario

   Building one page application process

  1. A configurable PIF is created in TalentLink and set as career site PIF or defined in standard /default application process for the specific organization (it is also possible to link one page application process with customized application process but then if different application processes take advantage of different PIFs, one page application process has to be created per posting, which is less stable but flexible solution)
  2. To retrieve the structure of the PIF assigned to relevant career site or standard application process an advertisement (or example advertisement) has to be published on that site and the interface has to call getPifStructure method.
  3. Based on the structure provided in the response a one page application process can be built.

   Creating Candidates

  1. The one page application process is built.
  2. A job is created in TalentLink and posted to a relevant career site where a one page application process is implemented.
  3. The candidate completes the form (PIF) and submits their application. 
  4. To create the candidate’s application in TalentLink against the relevant job the interface has to call the savePif method and then it passes the relevant data provided by the candidate as well as data related to posting (postingTargetID) and form (formID) 
  5. If the candidate added attachment/s, the interface has to fetch a token from the response after running the savePif method. 
  6. To add the attachment/s to the relevant candidate’s application the method addAttachment should be called with the file defined in a binary format (coding: Base64) as well as relevant information about attachment which should be provided in the call. 
  7. If the candidate added more than one attachment, step 6 should be repeated as many times as required for number of attachments. 

Response Format

XML

SOAP METHODS

 

This method accepts candidate consent This method must be called with Talentlink backoffice user credentials. The user name must be set to the following format: CompanyName:saif:BO. The password must be the user password for example: "Saif123!"

Post Parameter

 
Parameter Data Type Description
consentId
Long
[mandatory] ID of consent to accept
candidateId
Long
ID of candidate
applicationId
Long
ID of application
comment
String
Comment

Request Parameter

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

Response Parameter

 
Parameter Data Type Description
void
Void
The method uploads a file for a specific candidate and for a specific application. This method must be called with anonymous access. The user name must be set to the following format: TechnicalID:guest:FO. The password must be set to "guest".

Post Parameter

 
Parameter Data Type Description
pifAttachment
PifAttachment
Attachment to be added.
  token
String
NOTE: Token is provided as a response after successfully executed savePif method.
  langCode
LangCode
If null then EN will be used. Language possible values: Click to see possible values.
  fileName
String
Name of the file (with file extension).
  attachmentType
AttachmentType
Type of attached file. NOTE: Supported values are - RESUME, COVER_LETTER, OTHER.
  binaryData
DataHandler
The binary representation of the file.

Request Parameter

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

Response Parameter

 
Parameter Data Type Description
void
Void
This method return candidate consents. This method must be called with Talentlink backoffice user credentials. The user name must be set to the following format: CompanyName:saif:BO. The password must be the user password for example: "Saif123!"

Post Parameter

 
Parameter Data Type Description
candidateId
Long
[mandatory] ID of candidate

Request Parameter

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

Response Parameter

 
Parameter Data Type Description
candidateConsent
List
  consentDto
ConsentDto
Object representing consent data.
    id
Long
Database ID of Consent
    type
ConsentType
Type of Candidate consent. Indicates what type of consent. Can be one of possible values: - TALENT_POOL - consent for Talent Pools and General Applications - APPLICATION - consent for Applications - LINKEDIN_RSC - consent releated to LinkedIn
    language
LangCode
Language represented as Talentlink LangCode standard, ie: UK, EN, DE. Determines the language of provided consent text.
    introductionText
String
The headline of consent
    fullText
String
Full text of consent. This is exactly what candidate has seen when accepting / rejecting consent.
    department
DepartmentDto
Represents the first level department of consent.
      id
String
Department ID
      name
String
Department name
      level
Integer
Department level
      shortName
String
Department short name
      parentDept
DepartmentDto
Parent department
    defaultConsent
Boolean
True / false determining if consent is default
    current
Boolean
True / false determing if the consent is current version Current version will be presented to new candidates. Candidate can have assiged not current version if it has changes since agreement.
    version
Long
Number specifying version of the consent.
    user
UserDto
UserDto determines who has created the consent.
      id
Long
ID is the internal auto generated user of the Talentlink BackOffice system
      firstName
String
First name of user for in BackOffice, for example, Saif
      lastName
String
Last name of user, for example, Anjary
      login
String
Login username to access the Lumesse BackOffice
      email
String
Email of the user in the Lumesse BackOffice.
      cellphone
String
Cellphone number of the user
      type
String
ADVANCED = HR recruiter MSS = line manager
      active
Boolean
IF true user is active
    createdDate
Date
Date of creation of the consent.
    uniqueIdentifier
String
String unique identifier for consent.
  status
CandidateConsentStatus
Status of candidate consent. Can be one of the following values: - REQUESTED - communication has been sent to candidate asking for consent agreement - GRANTED - permission is given - REVOKED_BY_USER - permission is refused by TLK user - WITHDRAWN_BY_CANDIDATE - permission is refused by candidate
  lastGrantedDate
Date
Date of last grant action. Is null when grant has been never invoked.
  lastRevokedDate
Date
Date of last revoke action. Is null when revoke has been never invoked.
  lastRequestedDate
Date
Date of last request action. Is null when request has been never invoked.
  lastRequestedUser
UserDto
User invoking last request action. Is null when request has been never invoked.
  lastGrantedUser
UserDto
User invoking last grant action. Is null when grant has been never invoked.
  lastRevokedUser
UserDto
User invoking last revoke action. Is null when revoke has been never invoked.
  comment
String
Additional comment for consent. Can be null.
This method returns the structure of a PIF based on the provided postingTargetID. This method must be called with anonymous access. The user name must be set to the following format: TechnicalID:guest:FO. The password must be set to "guest".

Post Parameter

 
Parameter Data Type Description
postingTargetId
Long
ID of the posted advert. NOTE: PostingTargetID is provided by a few of our webservice methods (i.e. getAdvertisements from CareerPortal / FoAdvert).
langCode
LangCode
Language of the form. If null then EN will be used. 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
pifStructure
FormStructure
PIF Structure
  formSettings
FormSettings
Parameters of the Pif.
    id
Long
ID of the PIF which is linked with defied posting (via postingTargetID).
    langCode
LangCode
Language of the form (please see localization view of PIF in TalentLink back office to define relevant translations). All questions will be provided in defined language.
  questions
FormQuestion
List of Questions available in the Pif Form.
    id
Long
ID of relevant question assigned to PIF structure.
    label
String
Question label in language defined in langCode parameter.
    required
Boolean
If true - answer for the question is required; if false - answer is optional.
    repeatable
Boolean
If true - more than one instance of answer for the question is allowed; if false - only one instance is allowed.
    answerable
Boolean
If true - answer for the question can be created; if false - answer cannot be created (for example: it is section label).
    SubQuestions
List
List of subquestions in the Pif Form.
      subQuestion
FormQuestion
    ValidationRules
List
List of rules that are used to validate questions.
      validationRule
ValidationRule
        type
String
Type of validation (for example: maxLength).
        value
String
Definition of validation (number of characters allowed) or definition of question (free_text).
    Options
List
List of available anwers available for a specific question.
      option
Option
        id
Long
ID of relevant option (answer) assigned to question
        label
String
Option (answer) label in language defined in langCode parameter
        DependantQuestionIds
List
          dependantQuestionId
Long
ID of the dependant question.
        Options
List
          option
Option
    order
Integer
Order of the question in structure.
This method revokes candidate consent This method must be called with Talentlink backoffice user credentials. The user name must be set to the following format: CompanyName:saif:BO. The password must be the user password for example: "Saif123!"

Post Parameter

 
Parameter Data Type Description
consentId
Long
[mandatory] ID of consent to revoke
candidateId
Long
ID of candidate
applicationId
Long
ID of application
comment
String
Comment

Request Parameter

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

Response Parameter

 
Parameter Data Type Description
void
Void
This method is used to create the candidate’s application in TalentLink based on the relevant PIF. This method must be called with anonymous access. The user name must be set to the following format: TechnicalID:guest:FO. The password must be set to "guest".

Post Parameter

 
Parameter Data Type Description
pif
Pif
Answered questions data.
  formId
Long
ID of the PIF which is linked with defied posting (via postingTargetID).
  postingTargetId
Long
PostingTargetID of the job. Note: postingTargetID is provided by a few of our webservice methods (for example: getAdvertisements from CareerPortal > FoAdvert.
  Answers
List
    answer
Answer
      questionId
Long
ID of relevant question in PIF structure.
      value
String
Answer for relevant question (please see questionID) given by candidate.
      SelectedOptions
List
        optionId
Long
ID of relevant option assigned to question (option selected by candidate).
      SubAnswers
List
        answer
Answer
langCode
LangCode
Language of the form (please see localization view of PIF in TalentLink back office to define relevant translations). All questions will be provided in defined language. If null then EN will be used. 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
savedPif
SavedPif
Object with token identifying the saved PIF.
  token
String
Token uniquely identifying submitted application.
This method is used to create the candidate’s application in TalentLink based on provided filled forms. This method must be called with anonymous access. The user name must be set to the following format: TechnicalID:guest:FO. The password must be set to "guest".

Post Parameter

 
Parameter Data Type Description
application
Application
Answered questions data.
  FilledForms
List
    filledForm
FilledForm
      formId
Long
ID of the PIF which is linked with defied posting (via postingTargetID).
      Answers
List
        answer
Answer
          questionId
Long
ID of relevant question in PIF structure.
          value
String
Answer for relevant question (please see questionID) given by candidate.
          SelectedOptions
List
            optionId
Long
ID of relevant option assigned to question (option selected by candidate).
          SubAnswers
List
            answer
Answer
  postingTargetId
Long
PostingTargetID of the job. Note: postingTargetID is provided by a few of our webservice methods (for example: getAdvertisements from CareerPortal > FoAdvert).
langCode
LangCode
Language of the form (please see localization view of PIF in TalentLink back office to define relevant translations). All questions will be provided in defined language. If null then EN will be used. 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
submitApplication
SavedApplication
Object with token identifying the saved application.
  token
String
Unique token that identifies the application.