Interview Coordinator – UploadDocuments API requests
Api/UploadDocuments/CreateCandidateDocuemnts
Api/UploadDocuments/UploadApplicationDocuments
The CreateCandidateDocuments and UploadApplicationDocuments API requests provide a way to upload documents into the Interview Coordinator (IC) database and link those documents to a Candidate record.
Both requests perform exactly the same functions but use different “request authentication” logic which allows each to be used in different circumstances.
The CreateCandidateDocuments uses what we call “Access_Token” request authentication where the program making the request has secure access to the top level IC API Key for your account. Your IC API Key must be kept secret, so this method is only appropriate for Server to Server or Application to Server communications.
The UploadApplicationDocuments uses what we call “SessionID” request authentication. This is where the sending device must first obtain a SessionID token through Server to Server communication, which in turn, allows the a javascript or PHP script to upload documents to IC directly from a browser.
Up to 3 documents can be uploaded and attached to a candidate record using single request. Here is an example CreateCandidateDocuments request using JSON format
V2.api.interviewcoordinator
POST /api/uploaddocuments/CreateCandidateDocuments
{
“Content”: {
“access_token”: “string – API key value”,
“CandidateID”: “3421”,
“File1”: “<binary_encoded_contents_file>”,
“File1Type”: “1”,
“File1Name”: “JamesBrown_CV”,
“File2”: “<binary_encoded_contents_file>”,
“File2Type”: “2”,
“File2Name”: “JamesBrown_Application_Letter”,
“File3”: “<binary_encoded_contents_file>”,
“File3Type”: “2”,
“File3Name”: “JamesBrown_Application_questionaire”,
“DD”: “0”,
“Add_From”: “CE”,
“ApplyNotifications”: “2”,
“MessageName”: “SuccessResponseMessage1”,
}
}
In response to the receipt of correctly formatted CreateCandidateDocuments request, the API server will respond with an http 200 OK response and a series of response parameters. Here is an example :
{
“Status”: “Ok”,
“Content”:
{
“CandidateId”: “1045”,
“Message”: “<html text message which can be shown to the candidate when they have completed the document upload process>”,
“MessageHeaderText”: “Document Upload confirmation”
},
“Errors”: null
}
We will now go into more depth about each of the CreateCandidateDocuments parameters
Required parameter values :-
Access_Token (Required)
This parameter is a required parameter. The Access_Token value is a unique security token required to obtain access to the Interview Coordinator (IC) API methods. To obtain a valid token, please contact us to set the value for your account.
CandidateID (Required)
This parameter is a required parameter. The value must correspond with a valid CandidateID value for an existing IC “Candidate” and the CandidateID value MUST also be linked to your IC account
File1 (Required)
The request must always include at least 1 file. The file contents are binary encoded and included within the JSON format
File1Type (Required)
The request must always include a File?Type parameter for each File being uploaded. The File?Type parameter tells the IC API whether the file is a “CV” or “Other” file. CV files (Type 1) are treated differently than OTHER (Type 2) files.
File1Name (Required)
The request must always include a File?Name parameter for each File being uploaded. The File?Name parameter is the name of the file shown within the main IC application
Please note : File2, File2Type, File2Name & File3, File3Type, File3Name serve the same functions as above, but where multiple files are being uploaded
Optional parameter values :-
DD (Optional)
The DD parameter is used to indicate to the IC database whether the uploaded candidate documents should be immediately shown to the Hiring Manager and other IC contributors.
DD = 0 (or no DD value included in the request) will signify that the new candidate document(s) is/are immediately made visible to the hiring manager and other IC contributors
DD=1 is used to indicate that the CreateCandidateDocuments request is only a part of the overall process being conducted and therefore the documents should be hidden from IC Contributors until the process has finished
For example, where the application process consists of first uploading candidate details, then adding candidate documents and then asking the candidate to respond to a series of application questions, then the uploaded documents will remain hidden to the hiring manager, until the full process has been completed.
Add_From (Optional)
The value of this parameter tells the IC database the source of the new candidate document. Possible values are :-
“IC” = internally added candidate
“EXT” = candidate added from external source
“CE” = candidate added from in-house vacancy site
ApplyNotifications (Optional)
This parameter is used to tell the IC database who should get notified that a new candidate has applied for the vacancy
ApplyNotifications = 0 (or no parameter included) will signify that no notification email is sent on completion of document upload.
ApplyNotifications = 1 will signify that a notification email is sent to the candidate on completion of document upload.
ApplyNotifications = 2 will signify that a notification email is sent to the candidate AND the hiring manager on completion of document upload.
MessageName (Optional)
This parameter is used to pick the message value returned when the server API responds to a CreateCandidateDocuments request.
The administrator user for an IC account can add and edit multiple “custom message” values. These messages are stored in the database and given a unique name. A CreateCandidateDocument request can therefore select which on-screen message should be displayed to the candidate on completion of the document upload process.