Product GuideAPI ReferenceClient LibrariesStatus
ChangelogProduct UpdatesLog In

Customising and Embedding the Search UI

Suggest Edits

Affinda's Search Interface can be customised and embedded within recruitment platforms and job boards. A customised and signed URL is generated by our API which can then be added securely to your platform as an iFrame. Each URL is valid for 60 minutes.

Embedding the Search UI

Generating a URL to be embedded within your platform is a two-step process

  1. Configure your Search UI using either:
    1. Update the config for the logged-in user's embeddable resume search tool
    2. Update the config for the logged-in user's embeddable job description search tool
  2. Generate a URL using either:
    1. Create a signed URL for the embeddable resume search tool
    2. Create a signed URL for the embeddable job description search tool

Embedded URLs expire after 60 minutes. They will use the config settings at the time when they are generated. That means if you change the config, you need to generate a new URL for the changes to be effective.

Optionally, you can override the config directly when generating a URL by including configOverride in the body:

{
  "configOverride": {...}
}

Customisations

The following settings can be adjusted within the Search UI:

  • Theme / Styling (see more below)
  • Custom fields (see more below)
  • Actions (see more below)
  • Indices to Search (& whether the index dropdown is shown)
  • Maximum number of results displayed
  • Categories searched - select which out of Job Title, Location, Years of Experience, Occupation Group, Education, Skills, Languages, Management Level and Keywords are visible in the interface
  • Category weightings - change the weighting for each search category that is returned initially. Each category is weighted equally as a default
  • Ability to download original candidate resumes

These customisations can all be updated using the 'Update config' endpoints noted above, whilst a default theme can be applied at an Organization level.

Styling

The default search UI theme can be set at the user level and can then be overridden within the API request.

Our team will assist in customising the theming so please send us a list of the fonts and colours required. Once completed, this will be applied to your account.

This themed tool is available when embedding the Search Interface within your platform.

Options for styling include:

Colour palette

  • Light or dark mode
  • Background colour
  • Text colour
  • Primary colour (pink by default)
  • No match colour (red)
  • Partial Match colour (orange)
  • Info colour (blue)
  • Good Match colour (green)

Font settings

  • Font family (system font by default; can use any system font, Adobe Fonts, Google Fonts)
  • Base font size
  • Font weights (regular, medium, bold)

Border radius

  • Used for anything with rounded corners, eg. buttons, annotations, popovers

To update your default theme, contact our team.

Custom fields

Custom fields can be added to the Search UI to enable users to search across additional data fields not included in our standard categories. Once the custom data fields have been created on your account and data for these custom fields added to candidates (see Searching Custom Data for more information), simply specify the data point that should be included in the tool (and the default weight). The data point (as well as its associated data point type) will be reflected in the tool and end-users will be able to search seamlessly as they do with the other search fields.

Actions

'Actions' can be added to the Search UI to enable users to take action using the search results. Examples of such actions may be shortlisting candidates or viewing the candidate record in your platform. However, these actions will be configured in the downstream platform and as such customers retain complete control over what these actions may be.

Within the Affinda Search tool, any number of 'Actions' can be specified via the API for configuration of the embeddable Search tool - each Action must specify the human-readable label that will be shown to the user as well as the eventName to be identified by your platform.

When an action is triggered by the user, the embed will post a message to the parent window. You can listen for these events using the following JavaScript code:

window.addEventListener('message', function(e) {
    // Ensure that the event has come from Affinda
    if (e.origin !== 'https://app.affinda.com' || !e.data) return;

    if (e.data.type === 'action') {
	    console.log('action', e.data.eventName, e.data.identifiers);
    }
});

With this event information, the workflow can be triggered in your platform to add the candidate to a shortlist, open the candidate record in a new tab or whatever action has been configured.

Updated 2 months ago