Vacancy Exports
Vacancy Exports are a useful way to get data about Vacancies that have been created in Eploy, either to synchronize advertised jobs to an external job board, or for passing data for statistical analysis in data warehousing applications etc.
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 Vacancies (POST /api/vacancies/search).
Vacancy Statuses
Vacancies may go through one or more approval stages before they are authorised to be advertised on the Eploy jobs page, each of which will trigger an update to a new status. The status may also be used to close vacancies that are no longer required or have been closed for any other reason. Vacancies that have reached a particular Status can be identified by using "Route": "Vacancy.VacancyStatus" within your filters. You can see a list of Vacancy statuses in Eploy via Admin > Drop Down Lists (show values for: “Vacancy Status”) or by making an API call to:
GET api/options/dropdown/50
Identifying Active Vacancies
Please note that the Status alone will not necessarily tell you where the Vacancy is active or not. There are several other factors that constitute whether a particular Vacancy is "advertised", such as:
Whether the Vacancy is been marked as 'Advertise Externally': The "IncludeOnSite" field (boolean) can be used by the recruitment team to determine whether a Vacancy is to be advertised on the external-facing portal. ("AdvertiseInternally" can also be used to detemine if the Vacancy is advertised exclusively for internal applicants).
Whether the Vacancy Advertising Date is current: The "DatePosted" and "AdvertisingEndDate" (date fields) can be used to specify a date range the advert will be live for, allowing a vacancy to go live from a certain date or to stop being advertised after a certain date. ("InternalAdvertisingStartDate" and "InternalAdvertisingEndDate" can also be used to detemine the date range for the Vacancy to be advertised exclusively for internal applicants).
Whether it has been Hired: The "PositionsAvailable" (numeric field) can be used to specify how many positions are available for the Vacancy. When the Vacancy has been fully Hired (i.e. the number of active Hire records linked to the Vacancy meets the number of available positions), it is automatically removed from the site.
Whether the Vacancy has Expired: The "ExpiryDate" date field can be used to specify a date the Vacancy will expire, rendering it inactive.
The Eploy API allows you to access any Vacancy in the system, and any of the fields, including those above, may be used to filter specifically for Vacancies that meet certain criteria. However, the most common use-case is needing to easily identify Vacancies that are currently being advertised to external applicants, for which there is the "Vacancy.Advertising" object, that returns a boolean value determining this based on all the criteria above.
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 5 might be ‘Vacancy 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. In the case of a Vacancy Export, it would be associated to the Vacancy. Is it also possible to have multiple Export Packages associated to the Vacancy, if exporting to multiple systems or if you need to get the data at more than one point during the Vacancy's lifecycle.
By using the Export Package, you can specify in your search filter to list records that have not been exported by using "Route": "Vacancy.HasBeenExportedBy".
So, a full Vacancy export process might look like this:
1. Vacancy Search
The initial search can be used to identify whether there are Vacancy records to process, and to obtain the data needed from each record. The ResponseBlocks on a Vacancy Search can include any standard fields you need from the Vacancy (e.g. the Vacancy Title, the associated Organisation/Contact IDs, Advertisment fields, options used to categorise the Vacancy such as Position, Industry, Business Area and Location, Advertising Dates, Salary info etc. and any custom questions relating to the Vacancy).
API ENDPOINT
POST /api/vacancies/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters":
[
{
"Route": "Vacancy.Advertising",
"Value": true,
"Operation": "Equals"
},
{
"Route": "Vacancy.HasBeenExportedBy",
"Value": 5,
"Operation": "NotEquals"
}
],
"ResponseBlocks":
[
"VacancyID",
"Description",
"Qualifications",
"Benefits",
"VacancyStatus",
"PositionsAvailable",
"BusinessArea",
"Location",
"Industry",
"Position",
"VacancyType",
"Company",
"Contact",
"DatePosted",
"AdvertisingEndDate",
"Salary",
"Address",
"Vacancy.Question.17"
]
}5 = The Export Package ID you are using to mark the Vacancy 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":
[
{
"VacancyId": 1003,
"Description": "...",
"Qualifications": "...",
"Benefits": "...",
"VacancyStatus":
{
"Id": "15",
"Description": "Live Requirement",
"Reference": null,
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 50,
"Url": "https://tes tsystem.eploy.net/api/options/dropdown/50",
"Description": "Vacancy Status",
"Type": "dropdown"
}
},
"PositionsAvailable": 5.0,
"BusinessArea": null,
"Location":
{
"Id": "11",
"Description": "South East",
"Reference": null,
"ArchiveDate": null,
"ParentId": "18",
"OptionType":
{
"Id": 42,
"Url": "https://testsystem.eploy.net/api/options/dropdown/42",
"Description": "Locations",
"Type": "dropdown"
}
},
"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"
}
},
"Position":
{
"Id": "11",
"Description": "IT",
"Reference": null,
"ArchiveDate": null,
"ParentId": "0",
"OptionType":
{
"Id": 45,
"Url": "https://testsystem.eploy.net/api/options/dropdown/45",
"Description": "Positions",
"Type": "dropdown"
}
},
"VacancyType":
{
"Id": "1",
"Description": "Permanent",
"Reference": null,
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 51,
"Url": "https://testsystem.eploy.net/api/options/dropdown/51",
"Description": "Vacancy Types",
"Type": "dropdown"
}
},
"Company":
{
"Id": 18,
"Url": "https://testsystem.eploy.net/api/companies/18"
},
"Contact":
{
"Id": 1,
"Url": "https://testsystem.eploy.net/api/contacts/1"
},
"Salary":
{
"Salary": 26000.0,
"SalaryFrom": 22000.0,
"SalaryInterval":
{
"Id": "5",
"Description": "Yearly",
"Reference": null,
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 46,
"Url": "https://testsystem.eploy.net/api/options/dropdown/46",
"Description": "Rate Intervals",
"Type": "dropdown"
}
},
"HoursPerWeek": 37.5,
"ChargeToClient": 0.0,
"AllowChangePaySalary": false,
"PaySalary": null
},
"DatePosted": "2022-06-27T00:00:00Z",
"AdvertisingEndDate": null,
"Address":
{
"AddressID": null,
"AddressReference": null,
"Address1": null,
"Address2": null,
"Address3": null,
"Town": null,
"County": null,
"Country": null,
"PostCode": null
},
"QuestionFields":
[
{
"Answer":
{
"Id": "2",
"Description": "Increase to Headcount",
"Reference": "",
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 1,
"Url": "https://testsystem.eploy.net/api/options/custom/1",
"Description": "Reason for Hire",
"Type": "custom"
}
},
"QuestionId": 17,
"Title": "Reason for Hire?",
"AnswerType": "Option Group (Related)",
"QuestionType":
{
"ID": 9,
"Description": "Input - Drop-down"
}
}
]
}
],
"TotalRecords": 15,
"CurrentPage": 1,
"TotalPages": 15
}"..." represents the HTML to be added to each text box within the Vacancy.
2. Get Company (Organisation) Data
From the response to the Vacancy Search, we know the Organisation ID(s), and can use this to get the information about each Organisation from the API.
This can be done in one of two ways:
EITHER
Individually getting each candidate’s details using GET /api/companies/{companyId}
OR
Performing a subsequent Organisation search and passing all the Organisation IDs in the Filter
If you need to obtain information from sub records
API ENDPOINT
POST /api/companies/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters":
[
{
"Route": "Company.CompanyId",
"Value": [18,19],
"Operation": "Equals"
}
],
"ResponseBlocks":
[
"CompanyID",
"Name",
"Address"
]
}18,19 = The CompanyID(s) for the Companies returned from the Vacancy 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":
[
{
"CompanyId": 18,
"Name": "IT & Technical",
"Address":
{
"AddressID": null,
"AddressReference": null,
"Address1": "11 Lawn Road",
"Address2": null,
"Address3": null,
"Town": "Broadstairs",
"County": "Kent",
"Country":
{
"Id": "186",
"Description": "United Kingdom",
"Reference": "GB",
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 36,
"Url": "https://testsystem.eploy.net/api/options/dropdown/36",
"Description": "Countries",
"Type": "dropdown"
}
},
"PostCode": "CT101AA"
}
},
{
"CompanyId": 19,
"Name": "Human Resources",
"Address":
{
"AddressID": null,
"AddressReference": null,
"Address1": "Hoo Farm Industrial Estate",
"Address2": "Worcester Road",
"Address3": null,
"Town": "Kidderminster",
"County": "Worcestershire",
"Country":
{
"Id": "186",
"Description": "United Kingdom",
"Reference": "GB",
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 36,
"Url": "https://testsystem.eploy.net/api/options/dropdown/36",
"Description": "Countries",
"Type": "dropdown"
}
},
"PostCode": "DY11 7RA"
}
}
],
"TotalRecords": 2,
"CurrentPage": 1,
"TotalPages": 1
}
3. Mark Vacancy record ‘exported’
Finally, after processing, you can mark the Vacancies as exported using your ExportPackageId, so they drop from the list when you next perform the Vacancy 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": 5,
"VacancyIDs":
[
{
"Id": 1003,
"ExternalReference": "Eploy Test 1"
},
{
"Id": 1004,
"ExternalReference": "Eploy Test 2"
}
]
}5 = The Export Package ID you are using to mark the Vacancy as ‘exported’.
1003,1004 = The VacancyID(s) returned from the VacancySearch
“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 Vacancy/Vacancies as exported.