Go to examples:
Get Values For A Custom Dropdown List
Add New Option Type To A Custom Dropdown
Update Option Type For A Custom Dropdown
2. Get Candidate / Vacancy Info
4. Mark Application Record ‘Exported’
Workflow-based Integrations
If you are integrating a process that needs to happen as part of the recruitment workflow (e.g. a candidate assessment, background/right-to-work checks, video interviews etc.), the best way to achieve this is by having the integration represented as a Workflow Stage and using a Workflow Action to show progress/results.
The advantages of using this method are:
- It works perfectly with the Eploy recruitment workflow process meaning that the recruitment team and hiring managers are able to see and interact with the integration stage as necessary.
- The recruitment workflows in Eploy are highly configurable, so the system administrators would have full control of which recruitment workflows use the integration stage, whether applicants automatically move to and from the stage, and can control any automated communication to the candidate based on the stage being reached or certain outcomes being set.
- Actions and Action Outcomes can easily be incorporated into Eploy’s reporting and dashboard functionality to make reporting/navigation based on the integration stage easy to configure.
Managing Campaign Information
It is quite common for 3rd party applications to have several different campaigns/tests/jobs, to which each candidate needs to be allocated.
Usually, these campaigns will relate to the type of job the candidate has applied for in Eploy, in which case it is possible to set up a custom dropdown field that can be allocated to the Vacancy record. The dropdown entry can be selected in various ways within Eploy, most common being allocating them to Vacancy Templates and copying them through to any new vacancies that are raised from those templates, or having the Hiring Manager select from the list during the Vacancy Requisition.
All dropdown entries in Eploy contain a Description and a Reference. The Description is what the users see within the dropdown itself. Note that if the dropdown is going to contain lots of entries, it can be rendered in Eploy as a ‘type-picker’ so that the user can type any search term to identify the entry based on the Description. Therefore in these circumstances it is best to try to be as descriptive as possible in the Description so that they can search based on any term. The Reference is hidden from the end user, and this can contain any information needed as part of the integration (e.g. a campaign code). If multiple pieces of information need to be associated with each dropdown entry, you could even store JSON code within the Reference containing multiple values.
The options themselves can either be manually populated, or synchronised with the 3rd party system using the API. Each option consists of a ‘Description’ (which is the visible option in the system) and a ‘Reference’ (where you can store the campaign ID or any other information required to identify the campaign options in the 3rd party system. It is common to use JSON code within the Reference in order to store multiple values.
Below are some examples if you want to synchronise the options in the campaign dropdown.
Below are some examples for managing dropdown list entries via the API.
Get Values For A Custom Dropdown List
This will show all existing values in the option type (in this example, the optionReference for the option type in question is ‘25’).
URL
GET /api/options/custom/25
25 = The Eploy Option Type used to populate the dropdown question used for your campaign information. For a full list of available Option Types use GET /api/options
HEADERS
Authorization: Bearer (access_token)
EXAMPLE RESPONSE
{
"Values": [
{
"Id": "126",
"Description": "Test Assessment",
"Reference": "{ AssessmentID: '123456' }",
"ArchiveDate": null,
"ParentId": null
},
{
"Id": "127",
"Description": "Another Test",
"Reference": "{ AssessmentID: '654321' }",
"ArchiveDate": null,
"ParentId": null
}
]
}
Add New Option Type To A Custom Dropdown
This will allow you to add a new entry to the option type so that it will be selectable in the dropdown in Eploy.
URL
POST /api/options/custom/25
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Description": "Yet another test",
"Reference": "{ AssessmentID: '999999' }",
"IsActive": true
}
25 = The Eploy Option Type used to populate the dropdown question used for your campaign information. For a full list of available Option Types use GET /api/options
Variable strings
Note: the “Reference” may contain a string or JSON allowing multiple values if necessary
RESPONSE
{
"Id": 128,
"Url": "/api/options/custom/25/128"
}
Update Option Type For A Custom Dropdown
This will allow you to update an existing entry in the option type (in this case we are updating the Description and Reference for the entry we previously created). This could also be used to archive old campaigns by setting "IsActive": false (this will make it so the option cannot be selected against any new records, but it may still be set for existing records).
URL
PATCH /api/options/custom/25/128
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Description": "Last test",
"Reference": "{ AssessmentID: '888888' }",
"IsActive": true
}
25 = The Eploy Option Type used to populate the dropdown question used for your campaign information. For a full list of available Option Types use GET /api/options
128 = The OptionID you are updating
Variable strings
Note: the “Reference” may contain a string or JSON allowing multiple values if necessary
Note: there is no response body for this API call but a 200 response means that you have successfully updated the dropdown entry.
Processing New Applications
The first part of the process for a workflow-based integration involves frequently polling Eploy to identify the applicants who need to be processed, then getting their data out of the system in order to start the 3rd party process. After this, a Workflow Action can be created, which can be used to track the integration progress and report back results, and then finally the application can be marked to show it has been processed.
A typical process flow would look something like this:
1. Application Search
This process should be triggered at regular intervals depending on the need of the customer. We would recommend performing a search fairly regularly (e.g. every 10-15 minutes) so that your integration can run efficiently. By using an export package to mark records as processed, you can simplify the query so you are only looking for unprocessed records. That way, even if you are running the process regularly and not seeing any results for the majority of searches, this does not require too much resource. By simply identifying Applications that have reached a particular workflow stage like in the example below, you don’t need to over-complicate the query by having to consider the types of candidates your integration needs to run for- that can all be configured within the Eploy application workflow process and you know that if a candidate has reached this stage, they are eligible for the integration process to run for them.
URL
POST /api/applications/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging": {
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters": [
{
"Route": "Application.Stage",
"Value": 11,
"Operation": "Equals"
},
{
"Route": "Application.HasBeenExportedBy",
"Value": 4,
"Operation": "NotEquals"
}
],
"ResponseBlocks":[
"ApplicationID",
"Candidate",
"Vacancy",
"Vacancy.Question.312"
]
}
11 = The Eploy Application Stage Type ID at which your integration needs to be triggered. For a full list of available Application Stage Types use GET /api/options/dropdown/142
4 = The Export Package ID you are using to log that the Application record has been successfully exported For a full list of available Export Packages use GET /api/options/dropdown/86
Vacancy.Question.312 = An example of a custom question to return as part of the search (e.g. for campaign information)
EXAMPLE RESPONSE
{
"Records": [
{
"ApplicationId": 406,
"Vacancy": {
"Id": 1017,
"Url": "https://testsystem.eploy.net/api/vacancies/1017"
},
"Candidate": {
"Id": 5020,
"Url": "https://testsystem.eploy.net/api/candidates/5020"
},
"QuestionFields": [
{
"Answer": {
"Id": "138",
"Description": "Test Assessment",
"Reference": "{ AssessmentID: '123456' }",
"ArchiveDate": null,
"ParentId": null,
"OptionType": {
"Id": 27,
"Url": "https://testsystem.eploy.net/api/options/custom/27",
"Description": "Campaign",
"Type": "custom"
}
},
"QuestionId": 312,
"Title": "Campaign",
"AnswerType": "Option Group (Related)",
"QuestionType": {
"ID": 9,
"Description": "Input - Drop-down"
}
}
]
}
],
"TotalRecords": 1,
"CurrentPage": 1,
"TotalPages": 1
}
2. Get Candidate / Vacancy Info
Now that you have identified the Applications, you can get whatever information you need about the Candidate and Vacancy by calling the relevant API endpoints and processing the data that comes back. Most commonly you will at least need to get standard data regarding both of these records (you will need to get the CompanyID from the Vacancy record, for example, in order to insert the Action in the next step). It may also be useful at this stage to store some of the record identifiers from Eploy in the target system, if this is possible. For example, by storing the Eploy ActionID against the record, this will make the process of identifying the Action in subsequent calls much easier and less resource-heavy.
URLs
Note: these are examples of API calls that may be required for each record, based on CandidateId 3663 and VacancyId 1017. These Ids would need to be adjust accordingly based on the response from the previous step. There are other endpoints that may also need to be called – for a full list please refer to the Eploy Developer’s Portal.
GET /api/candidates/3663
GET /api/candidates/3663/questions
GET /api/1017
GET /api/1017/questions
3663 = The Eploy Candidate ID returned from the Application Search
1017 = The Eploy Vacancy ID returned from the Application Search
HEADERS
Authorization: Bearer (access_token)
Note: none of these requests require a body as they are GET requests. The response for each will list all details from the record, which are too long to list in this document.
If you want to retrieve the additional data for multiple Candidates/Vacancies in a single call, you could perform a search instead of getting each record individually. Please see section 2. Get Candidate Data from the New Starter Exports guide for an example of this.
3. Insert Action
The next step is to add the Action record into Eploy. This shows to the user that the integration has ran and it can act as a way to deliver any information you need them to see. Workflow Actions have an ActionTypeId that will be a specific Action Type that has been set up for the integration. The Action will need to relate to the VacancyID, CandidateID and CompanyID. Actions must have a StartDate, which can either simply be the date that the integration first ran, or it can be a significant date relating to the integration (e.g. if the integration was inviting a candidate to attend an event on a certain date/time that this can be used to show when it is due to happen). There is also an EndDate field that may also be populated if needed. Note that dates need to be in ISO-8601 UTC format.
Action records also have Outcomes which can be used to identify what status each applicant is at (any number of Action Outcomes can be set up and associated to the Action Type, each of which will have a unique ActionOutcomeId). Although fundamentally, you would set the outcome when the applicant have progressed further in the process (see "Updating Progress" section below), it is recommended for workflow-based integrations to set an outcome immediately by passing its ID as part of the initial call (e.g. using an Action Outcome named something like "Candidate Details Sent"). This can allow users the flexibility to be able to move applicants further on in the workflow while the external process is still ongoing, if necessary.
Another useful field on the Action record it the ExternalProviderURL, which can be used to pass a unique URL for the candidate to follow in order to access their profile on the 3rd party system or to complete a test. Eploy can be configured to automatically email and/or SMS message the Candidate when they have a Workflow Action and this URL may be included in the email/message content.
URL
POST /api/actions
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"ActionTypeId": 12,
"VacancyId": 1017,
"CandidateId": 3663,
"CompanyId": 19,
"ActionOutcomeId": 25,
"StartDate": "2022-05-24T06:43:34Z",
"ExternalProviderURL": "https://www.eploy.co.uk/example1234",
}
12 = The Eploy ActionTypeID for the type of workflow action needed – use GET /api/options/dropdown/179 to see available Action Types
1017 = The Eploy VacancyID returned from the Application Search
3663 = The Eploy CandidateID returned from the Application Search
19 = The Eploy CompanyID returned associated to the Company – use GET /api/companies/{companyId} to find this “StartDate” in ISO-8601 UTC format
25 = The Eploy ActionOutcomeID for "Candidate Details Sent" – use GET /api/options/dropdown/154 to see available Action Outcomes
“ExternalProviderURL” Unique link for the candidate to follow if needed
EXAMPLE RESPONSE
{ "Id": 14319, "Url": "/api/actions/14319" }
4. Mark Application Record ‘Exported’
Once applicant details have been processed, you can mark the Application as exported using your ExportPackageId, so they drop from the list when you next perform the application 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’ and export flag to manually re-trigger it, if this is ever necessary.
URL
POST /api/export
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"ExportPackageId": 4,
"ApplicationIds": [
{
"Id": 407,
"ExternalReference": "Test1"
}
]
}
4 = The Export Package ID you are using to mark the Application as ‘exported’.
407 = The ApplicationID returned from the Application 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 record with the export package.
Updating Progress
From this point forward, any significant updates to the applicant’s record in the 3rd party system can be reflected back into Eploy by updating the Action.
There are several fields with the Action that may be updated, depending on the circumstances. The most common ones to update are:
- CompletionDate – If the process has finished, it is best to mark the Action as completed by setting the CompletionDate. This can be used to report on the length of time it has taken to complete the process based on the StartDate/CreationDate to CompletionDate.
- ActionOutcomeId – The Outcome of the Action is primarily used to show what the result was (e.g. for a test where the outcome could be a Red/Amber/Green, these could be set up as Action Outcomes so that the relevant one can be set). The outcome can also, be used, however, to indicate the status of the Action, even if this it not the final status. Within Eploy it is possible to see an audit history of the Action Outcome so users can see each outcome that was set and the date/time each one was set.
- CommentsHTML – This field can be used to show anything you want to the Eploy users (Standard and Hiring Manager users) with the candidate’s Application Dialogue. This is very useful for displaying things like scores, comments, and even links to profiles or reports. This field accepts HTML markup and so you can have some control in how the data is displayed.
The process for this part of the integration would run like this:
5. Identify Action
(Optional – may be bypassed if you already stored the Eploy ActionID in the 3rd party system)
If you have stored the ActionID in the 3rd party system, this can simply be used to identify the Action to be updated. If this is not possible however, you can perform a Search on Actions to identify the ActionId beforehand, based on other know identifiers from the Candidate/Vacancy record.
URL
POST / api/actions/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
This example is searching by ActionType and the Candidate Email address. You may use other identifiers to locate the relevant Action. Please be aware that you may receive multiple results if you have not specified enough variables to locate the correct Action.
{
"Paging": {
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters": [
{
"Route": "Action.ActionType",
"Value": 12,
"Operation": "Equals"
},
{
"Route": "Candidate.Email",
"Value": "alec.candidate@eploy.co.uk",
"Operation": "Equals"
}
],
"ResponseBlocks":[
"ActionID"
]
}
12 = The Eploy ActionTypeID used in step 3.
“Route” can be any identifying candidate field/fields to identify the candidate
“Value” the value you are searching for
EXAMPLE RESPONSE
{ "Records": [ { "ActionId": 14320 } ], "TotalRecords": 1, "CurrentPage": 1, "TotalPages": 1 }
6. Update Action
Once you know the ActionID, you can update any of the fields against it.
URL
PATCH /api/actions/14320
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"EndDate": "2022-05-26T16:06:14.253Z",
"CompletionDate": "2022-05-26T16:06:14.253Z",
"ActionOutcomeId": 40,
"CommentsHTML": "Result - <b>99%</b>"
}
14320 = The Eploy ActionID (either stored or retrieved as per step 5.)
40 = The Eploy ActionOutcomeID associated to the outcome you want to set (e.g. representing a status of the third party activity) – use GET /api/options/dropdown/154 to see available Action Outcomes
Dates in ISO ISO-8601 UTC format
“Value” the value you are searching for
Variable strings
Note: CommentsHTML can contain HTML markup including external links etc.
EXAMPLE RESPONSE
{ "Records": [ { "ActionId": 14320 } ], "TotalRecords": 1, "CurrentPage": 1, "TotalPages": 1 }
Note: there is no response body for this API call but a 200 response means that you have successfully updated the Action.
Updates to other records
Please note, it is also possible to update other records in the system, such as the Application/Candidate, if there is data you need to send outside of what you are passing into the Action. For example, you may have a custom question on an Application record to store a score. In most circumstances, simply updating the Action details and the CommentsHTML would be enough for this, but other custom fields may be used if, for example, you need to carry out more complex reporting within Eploy on candidates who achieved a certain percentage or above.
Comments
0 comments
Article is closed for comments.