Go to examples:

Add New Option Type To A Custom Dropdown

Update Option Type For A Custom Dropdown

1. Application Search

2. Get Candidate / Vacancy Info

3. Insert Action

4. Mark Application Record ‘Exported’

5. Identify Action

6. Update Action

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 3^rd 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 3^rd 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 3^rd 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 3^rd 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.

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 3^rd 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,
  "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 “

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 3^rd party system)

If you have stored the ActionID in the 3^rd 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.)

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.

Search

Welcome to the Eploy Knowledge Base

Workflow-based Integrations

Managing Campaign Information

Get Values For A Custom Dropdown List

URL

HEADERS

EXAMPLE RESPONSE

Add New Option Type To A Custom Dropdown

URL

HEADERS

BODY

RESPONSE

Update Option Type For A Custom Dropdown

URL

HEADERS

BODY

Processing New Applications

1. Application Search

URL

HEADERS

BODY

EXAMPLE RESPONSE

2. Get Candidate / Vacancy Info

URLs

HEADERS

3. Insert Action

URL

HEADERS

BODY

EXAMPLE RESPONSE

4. Mark Application Record ‘Exported’

URL

HEADERS

BODY

Updating Progress

5. Identify Action

URL

HEADERS

BODY

EXAMPLE RESPONSE

6. Update Action

URL

HEADERS

BODY

EXAMPLE RESPONSE

Updates to other records