Custom Integration

At Starred, we measure candidate experience for candidates, for whom the application process has ended. Thus, either when a candidate:

• is rejected by the company
• has withdrawn from the application process
• is hired by the company

For your custom integration, this means you want to trigger our API when an application status changes to:

• rejected,
• withdrawn, or
• hired

Please note: since you can’t build in a delay in our API call (eg. schedule invitations for a few days after the rejection/hiring), we advise you to build the trigger in such a way that you identify status changes that happened 2 or 3 days ago.

By building the workflow in this way, you are assured that any changes to an application that were made by accident don’t cause a feedback request to trigger immediately.

In case of rejected or hired candidates, this gives you enough time to properly inform your candidate of your hiring decision and this gives the candidate enough time to let the initial emotion pass before they receive an invitation to provide feedback

All required fields in the API are listed in our API documentation. Below, you find an overview of where to find these fields:

• The Starred API uses API tokens authentication. Authenticate the requests when using the API by including the Authorization header in the request. You can generate API tokens in your Company Settings
• FormID relates to the survey that needs to be triggered for a specific workflow
• Template ID relates to the feedback invitation template that should be sent. You can populate the invitation template ID at the Sending Invitations section on the API page in your Starred account
• Sender is the email address used to send the feedback invitations. This email address needs to be an active user on Starred. You can invite this email address as a colleague on Starred via the Colleagues page
• We advise you to use a generic sender address (instead of linking it to a recruiter field in your ATS). It saves access management in Starred and it also creates objectivity when, for example, you do not ask a candidate for feedback on the recruiter's preparation / expertise on behalf of this recruiter.
• Next to the fields described above, you can add any additional custom fields to the API call. You can do this by adding &[customfield]=[customfieldvalue], for example: &RecruiterName=JohnDoe. These custom fields can be used to customize your invitation text and are used to segment your feedback responses on.
• In order to customize your invitation text, you need to add an @-sign to the custom field. For example: “Many thanks for applying to the vacancy of @JobTitle. Sorry to hear it didn’t work out.”
• We advise you to leave out any spaces used in your custom fields. For example, write ‘Job Title’
  as ‘JobTitle’

Custom fields we advise you to add to your API call

• JobTitle - referring to the vacancy a candidate applied for.
  Using this in the invitation text assures that your candidate knows to what application the feedback request refers in case of multiple applications by the same candidate
• RecruiterName - relates to the recruiter responsible for this application
• HiringManagerName - relates to the Hiring Manager involved in this application
• Fields to locate the feedback:
  1. Country
  2. Department
  3. BusinessUnit
  4. Office
• RejectionReason - relates to the reason a candidate was rejected
  (Sometimes this field is used to distinguish between ‘Candidate withdraws’ vs ‘We rejected the candidate’ in order to trigger the right survey)

Reminders

If you would like reminders to be sent, you have to adjust the parameters in your API call. In our API documentation you can learn how to modify your API parameters to enable reminders. This way, those who have not yet responded to the survey will be reminded 6 calendar days after the initial invitations have been sent. we are unable to send reminders for the previously sent invitations (where the reminders were disabled)

Cooling down period

Lastly, the email address of the recipient of the feedback request is the field we use as a unique identifier on Starred. We’ve built a cooling down period on Starred. This feature prevents you from reaching out to the same email address more than once within a certain timeframe: when enabled, we automatically filter out any email address that appears more than once within the set timeframe. Read more about this feature in this support article.