Interview Coordinator – CheckApplication API request
Api/Application/CheckApplication
This article is the latest in a series of articles looking at the new Interview Coordinator API methods. The upgrade to the IC API provides the functionality to allow any website to manage the entire process of a candidate job application.
Here we describe the CheckApplication API method. This provides a way to check the progress or “status” of a candidate application which has not yet been fully completed.
However, before we describe the functions and responses of the CheckApplication API method, we thought it might be a good idea to briefly review previous API articles which outline the different stages of the application process.
At the start of the process, the CreateNewCandidate API method will take the personal details of the candidate and store them in the Interview Coordinator database. Next, the CreateCandidateDocuments API will allow the candidate to upload one or more documents (EG CV) in support their job application. And in the future we will describe API methods which retrieve and submit application questions – which can optionally be asked as part of the candidate application process. As you can see, the candidate application process is therefore completed in a series of stages using different API requests.
However, we also need to allow for a scenario where the candidate starts the application process, completes only some of it and, for whatever reason, cannot complete the full process at that time.
There could be many reasons the candidate is not able to complete the full application process and we therefore need to allow them to return to complete the process (from wherever they left off) at a later time. This is where the CheckApplication method is used
Here is an example CheckApplication request using JSON format :
V2.api.interviewcoordinator
POST /api/Applications/CheckApplication
{“CampaignId” :”XXX”,”CandidateEmail” :”x.xxxx@151-151.com”,”MessageName” : “Application-already-received”}
The concept is that the candidate will resume the application process by entering their email address into the web page. The page knows the campaign to which they are applying and knows the message value it wants to display “IF” the CheckApplication requests finds that the candidate has already completed the application process. The web page can therefore construct the CheckApplication API request with the appropriate values.
Here are the possible responses from the CheckApplication API request :
Response scenario 1
JSON response
{“Status”: “OK”,”Content”: {“CandidateID”: null,”Status”: “No Application”,”ProgressText”: “No previous application has been recieved. Please make a NEW application. “, “FirstName”: null,”LastName”: null,”EmailAddress”: null,”Landline”: null,”Mobile”: null,”AdditionalInfo”: null,”Message”: null},”Errors”: null}
In this response the Status = “No Application” which shows that no candidate with the entered email address has started the application process for this campaign. The ProgressText parameter value provides a text string which can optionally be displayed to the prospective candidate.
Response scenario 2
JSON response
{“Status”: “OK”,”Content”: {“CandidateID”: “PsCR7cNwuOg=”,”Status”: “Application Pending – Docs + Questions”,”ProgressText”: “Please upload Application documents and complete any Application questions.”,”FirstName”: “Janet”,”LastName”: ” CandidateLastName “,”EmailAddress”: j.joplin@151-151.com ,”Landline”: “441204345678”,”Mobile”: “”,”AdditionalInfo”: ” “,”Message”: “<p><strong>Your application for this vacancy has already been received. Thank you for applying.</strong></p>\n<p>If you have not heard from us recently, I hope you will understand that for some vacancies we may receive a large number of applicants and while we will endeavour to keep you informed of your progress, this process may sometimes take longer than we would like.</p>\n<p>Therefore, if you have not heard from us within a reasonable time, please assume your application has not been successful on this occasion.</p>\n<p>Your CV will also be kept on our talent database and we may contact you where we think you might be suitable for future positions.</p>”},”Errors”: null}
In this response the Status = “Application Pending – Docs + Questions”. This shows that the candidate has entered their personal details (including their email address) but not completed the upload documents and questions stages of the application process.
The API response includes an encrypted CandidateID value which can be used to resume the previous application at the stage it was interrupted. Again the ProgressText response value provides a text string to optionally display to the prospective candidate – to guide them what do next.
Response scenario 3
JSON response
{“Status”: “OK”,”Content”: {“CandidateID”: “dAXh91IebiE=”,”Status”: “Application Pending – Questions”,”ProgressText”: “Please complete the Application questions.”,”FirstName”: “Mark”,”LastName”: “CandidateLastName”,”EmailAddress”: “mark@151-151.com”,”Landline”: “01793 848574″,”Mobile”: “”,”AdditionalInfo”: “”,”Message”: “<p><strong>Your application for this vacancy has already been received. Thank you for applying.</strong></p>\n<p>If you have not heard from us recently, I hope you will understand that for some vacancies we may receive a large number of applicants and while we will endeavour to keep you informed of your progress, this process may sometimes take longer than we would like.</p>\n<p>Therefore, if you have not heard from us within a reasonable time, please assume your application has not been successful on this occasion.</p>\n<p>Your CV will also be kept on our talent database and we may contact you where we think you might be suitable for future positions.</p>”},”Errors”: null}
In this response the Status = “Application Pending – Questions”. This shows that the candidate has entered their personal details and also uploaded their CV (and perhaps other supporting documents) but not completed the application questions stages of the application process.
Again the API response includes an encrypted CandidateID value which can be used to resume the previous application at the stage it was interrupted. And the ProgressText response value provides a text string to optionally display to the prospective candidate – to guide them what do next.
Response scenario 4
JSON response
{“Status”: “OK”,”Content”: {“CandidateID”: “”,”Status”: “Application Complete”,”ProgressText”: “Application Complete.”,”FirstName”: “”,”LastName”: “”,”EmailAddress”: “”,”Landline”: “”,”Mobile”: “”,”AdditionalInfo”: “”,”Message”: “<p><strong>Your application for this vacancy has already been received. Thank you for applying.</strong></p>\n<p>If you have not heard from us recently, I hope you will understand that for some vacancies we may receive a large number of applicants and while we will endeavour to keep you informed of your progress, this process may sometimes take longer than we would like.</p>\n<p>Therefore, if you have not heard from us within a reasonable time, please assume your application has not been successful on this occasion.</p>\n<p>Your CV will also be kept on our talent database and we may contact you where we think you might be suitable for future positions.</p>”},”Errors”: null}
In this response the Status = “Application Complete”. This shows that the candidate has entered their personal details, uploaded their CV (and perhaps other supporting documents) and also submitted any application questions – therefore they have already completed an application using this email address.
In this use case, the API response does not include an encrypted CandidateID value (if it did, the user could, in theory, review their existing application). The ProgressText parameter value also provides a text string, however the value of the Message parameter response is configured (in Interview Coordinator) to provide a customised full message to display to the prospective candidate, in order to manage their expectations.