As is suggested by the name, the CreateNewCandidate API request will add a new candidate record into the Interview Coordinator database, and link the candidate to a specific vacancy (IC campaign record). This, and all the other, API method(s), will accept both JSON and XML formatted requests and can be sent by any of the standard web programming languages.
A CreateNewCandidate request consists of a series of compulsory and optional parameters, which will trigger server side logic functions. For example, one compulsory field is the candidate email address. This value will be used to check whether the candidate has already applied for this vacancy. If they have, then the API response will send the appropriate notification response to the issuing server.
Here is an example CreateNewCandidate request using JSON format
V2.api.interviewcoordinator
POST /api/createcandidate/createNewCandidate
{
“Content”: {
“access_token”: “string – API key value”,
“CampaignID”: “3421”,
“FirstName”: “James”,
“LastName”: “Brown”,
“EmailAddress”: “james.brown@interviewcoordinator.com”,
“Landline”: “sample string 8”,
“Mobile”: “sample string 9”,
“AdditionalInfo”: “sample string 10”,
“Add_From”: “2”,
“UserID”: “456”,
“DD”: “”,
“CampaignPostingID”: “8222”,
“ResponseURL”: “app.interviewcoordinator.com/accountname1/3421/Indeeed13”,
“ApplyNotifications”: “2”,
“MessageName”: “SuccessResponseMessage1”,
“ExternalPostingURL”: “http:/wordpresssitedomain.com/accountname1/3421”
}
}
In response to the receipt of correctly formatted createNewCandidate request, the server will respond with a http 200 OK response and a series of response parameters. Here is an example :
{
“Status”: “Ok”,
“Content”:
{
“CandidateId”: “FbRztzl1GOI=”,
“Message”: “<html text on-screen message which can be shown to the candidate when they have completed their application>”,
“MessageHeaderText”: “Application confirmation”
},
“Errors”: null
}
We will now go into more depth about each of the createNewCandidate parameters
Compulsory 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 most of the Interview Coordinator (IC) API methods. To obtain a valid token, please contact us to set the value for your account.
CampaignID (Required)
This parameter is a required parameter. The value must correspond with a valid CampaignID value for an IC recruitment “Campaign” (vacancy) record and the value MUST also be linked to your IC account
FirstName (Required)
This value will be inserted into the FirstName field of the IC candidate record
LastName (Required)
The value inserted into the LastName field of the IC candidate record
EmailAddress (Required)
This value will be inserted into the EmailAddress field of the IC candidate record
Please note : when the emailaddress value matches an existing email address already associated with the CampaignID, then no new candidate record will be inserted. The response to the request will indicate this accordingly
Add_From (Required)
The value of this parameter tells the IC database the source of the new candidate record. Possible values are :-
“IC” = internally added candidate
“EXT” = candidate added from external source
“CE” = candidate added from in-house vacancy site
UserID (Required)
The value of this parameter tells the IC database which IC user is creating the new candidate record. If no specific IC user is to be linked with the new candidate the value can be = “1”
Optional parameter values :-
Landline (Optional)
The value inserted into LandLine (telephone) field of the IC candidate database record
Mobile (Optional)
The value inserted into the Mobile (telephone) field of the IC candidate record
AdditionalInfo (optional)
The optional value inserted into the AdditionalInfo field of the IC candidate record. This field is often used to store general text accompanying a candidate application.
DD (Optional)
The DD parameter is used to tell the IC database that the candidate application process is complete
DD = 0 (or no DD value included in the request) will signify that the new candidate record is immediately made visible to the hiring manager and other IC contributors
DD=1 is used to indicate that the candidate has only partly completed the configured application process. For example, where the application process consists of first uploading candidate details, then adding candidate documents and then adding responses to application questions, then candidate details will remain hidden to the hiring manager, until the full process has been completed.
CampaignPostingID (Optional)
IC is designed to keep track of which adverts have been posted to which job boards. Each job board posting will generate a new IC campaign posting record and this value can be used to track which advert the candidate has responded to
ResponseURL (Optional)
This parameter has a similar function to the CampaignPostingID. Where a vacancy advert is posted to a 3rd party job board there is often a need to supply a URL value which allows the Candidate to apply for the position. For each job posting IC will generate a unique URL which can be included in the advert so
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 an application.
ApplyNotifications = 1 will signify that a notification email is sent to the candidate on completion of application.
ApplyNotifications = 2 will signify that a notification email is sent to the candidate AND the hiring manager on completion of application.
MessageName (Optional)
This parameter is used to pick the message value returned when the server API responds to a createNewCandidate 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 createNewCandidate request can therefore select which on-screen message should be displayed to the candidate on completion of their application.