Candidate API - Technical implementation guide

Candidate API can be used to fetch data related to candidates that has applied to a recruitment process. It is possible to:

• List candidates, with the possibility of filtering them by process and/or current candidate status
  
  

• Fetch specific candidate data like personal information, structured cv data, file attachments etc.
  
  

• Fetch custom integration data that is added by recruitment users in the Webcruiter user interface.
  
  

• Marking candidates as processed for future filtering purpose
  
  

This API is a generic way of fetching Candidate data. If your intent is to work with Candidates with a hired status we recommend that you use the Hired Candidate API instead.

Clarifications

The following endpoint can be used to retrieve a list of candidate

GET /candidates

There's a number of filter options that can be combined, see API docs.

Notes about filtering parameters

• CandidateStatusId will filter based on the Candidates current status
  
  

• Possible CandidateStatusId:s can be found by using the endpoint Get /candidates/statuses
  
  

• The IsProcessed flag is the same flag that can be set from the candidate hired API

Custom integration data

The endpoint GET /candidates/{candidateId}/custom-data can be used to retrieve custom integration data.

This data is dependent on a customized form that must be configured by Webcruiter support team. The customized integration form is a modal form that can be triggered when a user changes the status of a Candidate in the Webcruiter user interface.

The form can contain a number of input fields like text boxes, drop downs etc. Data entered by the recruiter user in this form will be stored and available in the custom-data endpoint.

The integration form is typically used to capture data that is not part of the core recruitment process but is still essential for transferring the candidate to the integrating system. Common examples include cost center, additional dates, assignment codes, and similar fields.

Data sources for drop downs in customized integration form

When you need to present a dropdown list with selectable options for users, there are two recommended approaches:

1. Static Option Lists
   If the list contains only a few items that rarely change, the Webcruiter support team can predefine these options as part of the customized integration form configuration.
   
   

2. Dynamic Option Lists
   For larger lists or those that change frequently, it’s best to manage them through the integrating system. In this case, use the API endpoint designed to handle three data source categories:

   • Assignment Codes

   • Assignment Types

   • Cost Centers

Each category corresponds to a dropdown list that can be displayed on the customized integration form. To add or update values in these data sources, use the following endpoint:

PUT /custom-data-source

Note that values cannot be removed from the data sources, but they can be inactivated. An inactivated value will not be listed as an option in the drop downs.

Marking a Candidate as processed

The endpoint POST candidates/{candidateId}/process is a convenient way to make sure that the same Candidate is not processed twice. Calling this endpoint will set the IsProcessed flag which later can be filtered on when calling the endpoint GET /candidates.

Questions & Answers

How do I know what the different fields represent?

All fields exposed by the API are documented in the Complete API Docs that can be found here
APIs: Details

Can I fetch the same candidate twice to feed data into two different systems?

This can be done in different ways, but if you would like to have two separate integrations we recommend that you use two different API clients. The endpoint POST /candidates/{candidateId}/process will mark the candidate as processed by the executing API client, thus the isProcessed filter that can be applied to GET /candidates will only filter candidates in the context of the executing API client.

It is possible to add a message when marking the candidate as processed. Where will this message show up?

This message will be added to the Candidate log. In Webcruiter this log can be seen on in the candidate detail view (at the bottom of the view).

What is the difference between the Hired Candidate API and the Candidate API

The endpoints in the Hired Candidate API will give the same data as the endpoints in the Candidate API. The most common use case for integrations is transferring hired candidates to an HR system. The Hire Candidate API is just a set of specialized endpoints that is convenient to use for this particular use case.

Complete API Docs

All available endpoints are documented on our developer portal