Go to examples:
4. Mark Placement record ‘exported’
New Starter Exports
New Starter Exports are very commonly required to pass data about newly appointed employees from Eploy to HRIS/Payroll systems, or other systems that require a record for each member of staff within your organisation.
The best way to achieve a new starter export via the Eploy RESTful API is to poll Eploy on a regular basis to identify new Placements for new joiners (POST /api/placements/search).
Placement Statuses
Placements will reach a particular status when they are ready to be exported which means they can be identified by using "Route": "Placement.PlacementStatus" within your filters.
Most commonly, customers will either want this to happen as soon as a candidate has completed onboarding (Offer/Contract Accepted) or after the recruitment team has checked the onboarded candidate and moved them to a status to indicate they are ready to export (Onboarding Checked).
On a typical system, “Contract Accepted” would be Placement Status ID 4 and “Onboarding Checked – Candidate Ready” would be Placement Status ID 6, but these can vary depending on how your system has been configured, so it is worth reviewing the Placement Statuses that currently exist in Eploy by going to Admin > Drop Down Lists (show values for: “Placement Status”) or by making an API call to:
GET /api/options/dropdown/91
Export Packages
As you process records, you can mark them as exported by using an Export Package which Eploy can set up for you. E.g. ExportPackageID 4 might be ‘New Starter Export”. Again, you can review Export Packages in the system via Admin > Drop Down Lists (show values for: “Export Packages”) or by making an API call to:
GET /api/options/dropdown/86
Export Packages can be associated to any type of record in the system to enable you to track whether they have been exported, but typically for a new starter export, it would be associated to the Placement. Is it also possible to have multiple Export Packages for the same record type, for example if you are exporting data to multiple systems or if you need to get the data at more than one point during the recruitment process (e.g. once when the offer is made and once when the candidate has accepted the offer).
By using the Export Package, you can specify in your search filter to list records that have not been exported by using "Route": "Placement.HasBeenExportedBy".
So, a full new starter export process might look like this:
1. Placement Search
The initial search can be used not only to identify whether there are new starters to process, but also to obtain some of the data needed to populate the record in the target system. The ResponseBlocks on a Placement Search can include any fields you need from the Placement itself (e.g. the PlacementID and Salary info), the associated Candidate / Vacancy IDs and any custom questions relating to the Placement, Candidate, Vacancy etc.
API ENDPOINT
POST /api/placements/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging": {
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters": [
{
"Route": "Placement.PlacementStatus",
"Value": 6,
"Operation": "Equals"
},
{
"Route": "Placement.HasBeenExportedBy",
"Value": 4,
"Operation": "NotEquals"
}
],
"ResponseBlocks":[
"PlacementID",
"Vacancy",
"Candidate",
"Salary",
"Candidate.Question.34"
]
}
6 = The Placement Status ID(s) for the Placements you need to identify (this Value can be an array if necessary, to identify Placement that have reach one of several statuses e.g "Value": [4,5,6])
4 = The Export Package ID you are using to mark the Placement as ‘exported’.
“ResponseBlocks” can be customised to your requirements (see the Eploy Developer’s Portal for more info). Note: any custom questions can be included in your ResponseBlocks using the format {RecordType}.Question.{ID}
EXAMPLE RESPONSE
{
"Records": [
{
"Candidate": {
"Id": 5026,
"Url": "https://testsystem.eploy.net/api/candidates/5026"
},
"PlacementId": 2,
"QuestionFields": [
{
"Answer": "NI",
"AnswerType": "String (Single Line)",
"QuestionId": 34,
"QuestionType": {
"Description": "Input - Short Answer",
"ID": 1
},
"Title": "NI Number"
}
],
"Salary": {
"ChargeToClient": 0.0,
"HoursPerWeek": 37.5,
"Salary": 23500.0,
"SalaryBand": null,
"SalaryInterval": {
"ArchiveDate": null,
"Description": "Yearly",
"Id": "5",
"OptionType": {
"Description": "Rate Intervals",
"Id": 46,
"Type": "dropdown",
"Url": "https://testsystem.eploy.net/api/options/dropdown/46"
},
"ParentId": null,
"Reference": null
},
"SupplierCharge": 0.0
},
"Vacancy": {
"Id": 7,
"Url": "https://testsystem.eploy.net/api/vacancies/7"
}
}
],
"TotalPages": 1,
"CurrentPage": 1,
"TotalRecords": 1
}
2. Get Candidate Data
From the response to the Placement Search, we know the Candidate ID(s), and can use this to get the information about each Candidate from the API.
This can be done in one of two ways:
EITHER
- Individually getting each candidate’s details using GET /api/candidates/{candidateId}
OR
- Performing a subsequent Candidate search and passing all the Candidate IDs in the Filter
If you need to obtain information from sub records (e.g. Bank Details, Employment History etc.) then it is necessary to perform individual GETs on each of the relevant endpoints for these; e.g.
GET /api/candidates/{candidateId}/bank
GET /api/candidates/{candidateId}/employment
…and so on (see the Eploy Developer’s Portal for more info).
If all you need is basic candidate information though, you can use the Candidate search method:
API ENDPOINT
POST /api/candidates/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging": {
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters": [
{
"Route": "Candidate.CandidateId",
"Value": [5026,5027],
"Operation": "Equals"
}
],
"ResponseBlocks": [
"CandidateID",
"Firstname",
"Surname",
"Email",
"Mobile"
]
}
5026,5027 = The Candidate ID(s) for the Candidates returned from the Placement Search
“ResponseBlocks” can be customised to your requirements (see the Eploy Developer’s Portal for more info). Note: any custom questions can be included in your ResponseBlocks using the format {RecordType}.Question.{ID}
EXAMPLE RESPONSE
{
"Records": [
{
"CandidateId": 5026,
"FirstName": "Wendy",
"Surname": "Groves",
"Mobile": "07168 11649099",
"Email": "wendygroves@eploy-donotsend.co.uk"
},
{
"CandidateId": 5027,
"FirstName": "Craig",
"Surname": "Jefferson",
"Mobile": "07168 11649099",
"Email": "craig.candidate@eploy-donotsend.co.uk"
}
],
"TotalRecords": 2,
"CurrentPage": 1,
"TotalPages": 1
}
3. Get Vacancy Data
From the response to the Placement Search, we know the Vacancy ID(s), and can use this to get the information about each Vacancy from the API.
This can be done in one of two ways:
EITHER
- Individually getting each vacancy’s details using GET /api/vacancies/{vacancyId}
OR
- Performing a subsequent Vacancy search and passing all the Vacancy IDs in the Filter
API ENDPOINT
POST /api/vacancies/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Filters": [
{
"Operation": "Equals",
"Route": "Vacancy.VacancyID",
"Value": [5,7]
}
],
"Paging": {
"RecordsPerPage": 10,
"RequestedPage": 1
},
"ResponseBlocks": [
"VacancyID",
"Title",
"Company",
"Contact",
"CreationDate",
"Industry"
]
}
5,7 = The Vacancy ID(s) for the Vacancies returned from the Placement Search
“ResponseBlocks” can be customised to your requirements (see the Eploy Developer’s Portal for more info). Note: any custom questions can be included in your ResponseBlocks using the format {RecordType}.Question.{ID}
EXAMPLE RESPONSE
{
"Records": [
{
"VacancyId": 5,
"Title": "Chief Financial Officer",
"Industry": {
"Id": "3",
"Description": "Support Centre",
"Reference": null,
"ArchiveDate": null,
"ParentId": "0",
"OptionType": {
"Id": 41,
"Url": "https://testsystem.eploy.net/api/options/dropdown/41",
"Description": "Industries",
"Type": "dropdown"
}
},
"Company": {
"Id": 17,
"Url": "https://testsystem.eploy.net/api/companies/17"
},
"Contact": {
"Id": 1,
"Url": "https://testsystem.eploy.net/api/contacts/1"
},
"CreationDate": "2023-10-22T20:58:03.017Z"
},
{
"VacancyId": 7,
"Title": "Customer Service Advisor",
"Industry": {
"Id": "1",
"Description": "Retail",
"Reference": null,
"ArchiveDate": null,
"ParentId": "0",
"OptionType": {
"Id": 41,
"Url": "https://testsystem.eploy.net/api/options/dropdown/41",
"Description": "Industries",
"Type": "dropdown"
}
},
"Company": {
"Id": 15,
"Url": "https://testsystem.eploy.net/api/companies/15"
},
"Contact": {
"Id": 25,
"Url": "https://testsystem.eploy.net/api/contacts/25"
},
"CreationDate": "2023-11-01T17:31:16.013Z"
}
],
"TotalRecords": 2,
"CurrentPage": 1,
"TotalPages": 1
}
4. Mark Placement record ‘exported’
Finally, after processing, you can mark the Placements as exported using your ExportPackageId, so they drop from the list when you next perform the placement search. Marking the record also has other benefits; end users are able to see the export logs in Eploy and can build dashboards based on the export data, so they know which records were exported and when. Users with permission may also ‘clear’ an export flag to manually re-trigger it, if this is ever necessary.
API ENDPOINT
POST /api/export/
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"ExportPackageId": 4,
"PlacementIDs": [
{
"Id": 2,
"ExternalReference": "Eploy Test 1"
},
{
"Id": 17,
"ExternalReference": "Eploy Test 2"
},
{
"Id": 35,
"ExternalReference": "Eploy Test 3"
}
]
}
4 = The Export Package ID you are using to mark the Placement as ‘exported’.
2, 17, 35 = The PlacementID(s) returned from the Placement Search
“ExternalReference” can be used to put additional information into the export log, e.g. a unique identifier.
Note: there is no response body for this API call but a 200 response means that you have successfully marked the Placement(s) as exported.
Comments
0 comments
Article is closed for comments.