If you are using the Eploy API to create or update Candidates and you want the candidate to be able to log in using the password you have set, it is important that the password you use conforms to the password policy in your Eploy system.
The Password Policy itself is managed within Eploy- see the article Password Strength & History Policy for more information on this.
The API examples in this guide will help you to ensure that Candidate passwords are set correctly and that you don't encounter errors attempting to create/update a candidate using an invalid password.
Examples
Validate a password against the password policy
This endpoint allows you to check whether a proposed password meets the criteria defined within the password policy. It simply allows you to pass a password value and receive a response telling you whether that password is valid or not, before you try to create/update a record. If the password you pass is valid, you will recieve a 200 OK response. If it is invalid, you will receive a 400 Bad Request, and an "error_message" value telling you why the password was invalid. Please note, the password policy is configurable and therefore the example of a 'valid request' shown here might not actually be valid on your system, if it does not meet the requirements imposed by your policy.
Valid Request:
POST /api/candidates/validatepasswordpolicy
{ "Password": "Bananas5" }"Password" is the proposed password you want to check
Response: 200 OK
Invalid Request:
{ "Password": "Bananas" }"Password" is the proposed password you want to check
Response:
{ "error_message": "Your password must contain any 3 of upper case, lowercase, numeric and special characters." }Create a Candidate and set password
Once you know that the password you have proposed is valid, you can use it to create a Candidate record as per the example below. As long as your password is valid, you should receive a 200 OK response and the Id and Url for the Candidate record you created.
Request:
POST /api/candidates/
{
"FirstName": "Johnny",
"Surname": "Cash",
"Email": "johnny.cash@eploy.co.uk",
"Password": "Bananas5"
}"FirstName" the first name of the Candidate you are creating
"Surname" the surname of the Candidate you are creating
"Email" the email address of the Candidate you are creating
"Password" the password you want to set for the Candidate
Response:
{
"Id": 5408,
"Url": "https://integrationsdemo.eploy.net/api/candidates/5408"
}Set password on existing Candidate
Alternatively, if the Candidate record already exists, and you know the CandidateId, you can update the Candidate's password as per the below example. If you don't know the CandidateID, you will need to search for the Candidate beforehand (see further examples below).
Request:
PATCH /api/candidates/5407
{ "Email": "johnny.cash@eploy.co.uk", "Password": "Bananas5" }5407 the Eploy CandidateId for the existing Candidate you need to update
"Email" the email address of the Candidate (if you need to update this)
"Password" the password you want to set for the Candidate
Response: 200 OK
Validate the credentials for a Candidate
You can check whether an existing Candidate's password is set correctly using this endpoint that allows you to pass the Email and Password values. If found, the Id and URL of the existing Candidate record with matching credentials will be returned in the 200 OK Response.
Request:
POST /api/candidates/validatecredentials
{ "Email": "johnny.cash@eploy.co.uk", "Password": "Bananas5" }"Email" the email address of the Candidate you need to check
"Password" the password of the Candidate you need to check
Response:
{
"Id": 5407,
"Url": "https://integrationsdemo.eploy.net/api/candidates/validatecredentials"
}
Search for a Candidate by Email address
If you don't know the CandidateID, you can search for them using an example like the one below. Note, you can search for Candidates by any field, but the example below is using their Email address.
Request:
POST /api/candidates/search
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters":
[
{
"Route": "Candidate.Email",
"Value": "johnny.cash@eploy.co.uk",
"Operation": "Equals"
}
],
"ResponseBlocks":
[
"CandidateID",
"Firstname",
"Surname",
"Email"
]
}Value in this example is the Candidate's email address
Response:
{
"Records":
[
{
"CandidateId": 5408,
"FirstName": "Johnny",
"Surname": "Cash",
"Email": "johnny.cash@eploy.co.uk"
}
],
"TotalRecords": 1,
"CurrentPage": 1,
"TotalPages": 1
}
Search for a Candidate by CandidateID
You can also search for a Candidate by their CandidateId if you do know it, and retrieve any fields you want using the ResponseBlocks (alternatively you could use GET /api/candidates/{candidateId} to simply get all standard Candidate fields, but the example below allows you to define the fields you want ti see in the results. You can also use the below search to retrieve details of multiple Candidates simply by passing the CandidateIds as and array (e.g. "Value": [5407,5408],).
📌Note: it is not possible to get the Candidate's existing password using either of the methods, because once set, the Password is encrypted in Eploy and cannot be retrieved.
Request:
POST /api/candidates/search
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters":
[
{
"Route": "Candidate.CandidateId",
"Value": 5407,
"Operation": "Equals"
}
],
"ResponseBlocks":
[
"CandidateID",
"Firstname",
"Surname",
"Email"
]
}Value in this example is the Eploy CandidateID
Response:
{
"Records":
[
{
"CandidateId": 5407,
"FirstName": "Johnny",
"Surname": "Cash",
"Email": "johnny.cash@eploy.co.uk"
}
],
"TotalRecords": 1,
"CurrentPage": 1,
"TotalPages": 1
}