Product GuideRecruitment AI OverviewAPI ReferenceStatus
Search & Match Product Guide
Product UpdatesApp Log In

Search & Match Product Guide

The page contains all information about Search and Match

Getting started with Search and Match

Affinda's Search & Match is a flexible and transparent solution designed to transform how recruiters find the right candidates for job openings. Affinda's Search & Match solution can be integrated with Affinda’s industry-leading Resume Parser and Job Description Parser products or users can incorporate their candidate database and search parameters.

Key features of Search and Match

Types of matching

Affinda's solution comprises various types of matching:

  • Candidate Matching
    • Search by Job Description - search an index of candidate resume data against a single job description to find the best candidates for a given role
    • Find Similar Candidates - search an index of candidate resume data against a single candidate to find similar candidates
  • Job Matching - search an index of job descriptions against a single candidate to find the best role for a given candidate
  • Profile Scoring - returns a single score assessing the match of a single candidate with a single job description

Two ways to return search results

There are two ways that customers can use the Search & Match product.

Option 1 Embedding the Affinda Search UI

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.

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

  1. Configure your Search UI using the following endpoints: for Candidate Search and for Job Search
  2. Generate a URL using the following endpoints: for Candidate Search and for Job Search

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": {...}
}

Further information about customising the Search UI can be found here.

Option 2 Using the search API

For customers who have an existing interface or want to build there own, they can choose to use Search & Match via API. The same API which powers our UI is available to receive the results in JSON format. Customers can set their own query in the request and receive the results back which can then be surfaced through their own platform. The following endpoints are used for searching via API:

🚧

Search UI not designed to be used within the Affinda app

The Search UI is available via the Affinda app for customer testing, however, it is not designed to be used in a production environment. Customers looking to use the UI should embed this within downstream platforms.

Search Algorithm

Affinda's advanced Search & Match algorithm returns the most relevant results based on the search criteria provided, while also providing flexibility and transparency to users. Each category is given a score based on the match and these scores are then combined with user-set category weights to give an overall score for the query that is used to rank candidates or job suitability.

Our search algorithm outputs raw scores for each field in a non-normalized way and they can be arbitrarily large depending on the type of the field. To make these scores usable, we need to normalize these scores to give a percentage score that is easily understood and comparable.

Please see here for some worked examples explaining how scores are calculated

Using Search and Match

Once a Resume or Job Description Parser is set up, the option to test the Affinda Search & Match UI will appear in the left-hand panel under 'Tools' within the workspace.

Note:

  • To enable the Candidate Match feature, a Resume Parser must be set up
  • To enable the Job Match feature, a Job Description Parser must be set up

To start using Search and Match, follow these steps:

  1. Index Data
  2. Search the index either via API or using the Affinda Search UI
  3. The search query can be created automatically using a resume or job description or manually using a custom query
  4. (optional) Adjust category weights and query elements

Indexing Data

Affinda's Search & Match solution is designed to search across one or more 'indices'. These indices contain the data that is relevant for searching quickly and efficiently through thousands of candidates or job records. 

Customers can create as many indices as they wish and enable a search to be made across their entire database, or just a subset of the relevant candidate or job set. For example, customers may wish to create a new index that reflects each job type, candidate location, or recruitment consultant.

Indexing data is managed programmatically via the Affinda API. There is a simple process to follow to create indices that are then easily searchable using the Affinda Search & Match solution.

  1. Create a new index - Create a new index
  2. Add data to index - Index a new document

Note, to index data from your existing database, first create the resume record in our system by uploading the resume for parsing using the POST documents endpoint. and then index using the unique document identifier returned.

Each index will have a unique identifier associated that users must then specify when searching.

Using the Affinda Search UI

Affinda has developed a user interface for the Search & Match product that can be embedded within a customer's platform. The interface is an easy-to-use tool that provides transparency to users on the reasons that candidates or jobs scored highly for the given search criteria. 

The interface is available for testing within the Affinda web app and can be embedded easily once a customer has moved to a paid plan. The embedded interface can be customised according to customer requirements, including changes to styling and functional elements.

Uploading a document to Search & Match

Searches within the interface can be created in two ways:

  1. Custom search criteria
  2. Uploading a document for matching

In the case of uploading a document for matching, simply click 'Upload a document' at the top left of the interface and upload either a job description or resume. Our document parsing engine will extract the key details from the document and populate the search query based on the data extracted. This method quickly automates the search process and finds the right matches in seconds.

Adjusting a search

A custom search criteria, either from a blank start or using the outputs from an uploaded document, can be created by adjusting the fields and weightings within the Search Interface.

Within the Search Interface, users can easily adjust the following elements to give the best results:

  • Search fields & criteria
  • Search types (e.g. current job titles only)
  • Category weights

The search results will be adjusted in real time based on the criteria that are visible and do not need to be refreshed.

Suggested job titles and skills will appear when these categories are included in the search query. These suggestions are based on what job titles / skills frequently appear alongside the terms that are already included in the query and are an effective way to broaden the search to include a wider range of candidates.

Viewing results

Our results panel quickly ranks and summarises candidates in an easy-to-digest format. If users want to see additional detail about the candidate and where they performed well or poorly against the search criteria and a brief summary of the data held within their profile, expanding the candidate profile will unearth a range of additional detail.

Users can also download the resume directly from the Search Interface if enabled, as well as other actions which can be customised within the users' platform.

Advanced Options

Boolean Searches

To give users full flexibility, our Candidate and Job Match products allow users to specify Boolean searches. Our product uses ElasticSearch simple query string syntax to give you the power to make complex custom searches that fit your need.

While this type of search is most typically used for the 'Keyword' category by users, the same syntax can be applied across all of our other search categories.

Search syntax

  • +signifies AND operation
  • |signifies OR operation
  • -negates a single token
  • "wraps a number of tokens to signify a phrase for searching
  • *at the end of a term signifies a prefix query
  • (and)signify precedence
  • ~Nafter a word signifies edit distance (fuzziness)
  • ~Nafter a phrase signifies slop amount

Adding and Updating Candidate Data without Parsing

If you are a new customer of Affinda, it is likely that you will want to search for candidates that you already have on file within your system. In addition, you may want to update candidates' details when you learn new information or their status changes.

Affinda's API allows you to easily add existing candidates to the Affinda platform, without having to re-parse the candidate's resumes, as well as update any candidates that have already been added.

Creating a new candidate record

Customers should use the same API endpoint Upload a document for parsing) used for uploading resumes to add an existing candidate record to the Affinda platform. However, instead of uploading a PDF, .docx or URL (or another file type), customers should create a resume with 'data'.

This requires that the data in your system be mapped to a JSON-encoded string of the ResumeData object. 

Resumes added using this data method do not use any parsing credits.

Updating an existing candidate record

The process for updating a candidate record is the same as above, in that the request requires JSON-encoded string of the ResumeData object. However, the endpoint should use the Update a document's data endpoint.

📘

For other document types, please use the PATCH /annotations/{id} endpoint or the POST /annotations/batch_update endpoint.

Adding custom fields to search criteria

While Affinda returns a wide range of data from resumes as standard, often customers will have other additional data typically not found in these documents that they would like to include in search criteria. Examples of this may include salary expectations, availability, or recruiters' notes from interviews.

Affinda has functionality available for users to add custom data to candidate records and then to be able to search across this, either via API or through the Search UI.

Adding custom data points for searching

To be able to add custom data to a candidate, the data point needs to be first created for your Organization. Custom data points can be any of the following types:

  • Boolean (true / false)
  • Date
  • Number
  • String

To create these data points, get in touch with the Affinda team who will add the fields to your Organization.

Once created, custom data can be added by either:

  • Updating an existing candidate record (e.g. one that has been parsed using Affinda's Resume or Job Description Parser)
    • Simply add the custom field name to the API request and its corresponding value and the custom data will be added (E.g. "availabilityEndDate": "2022-12-31")
  • Creating a new candidate record using data (e.g. without parsing a document)

For more information, see Adding and Updating Candidates Directly.

Searching via API

Once added, the custom fields can then be easily searched via the API.

  • Use the standard search endpoint
  • Specifying the custom fields to search within the request, where:
    o "filterType" is either equals or range
    o "dataPoint" is the custom field name
    o "value" is the search criteria
    • If the filter type is range, the value can be expressed in the formats like the following:
      • {"gte": "2022-12-01", "lte": "2022-12-31"} – between 1-Dec-22 and 31-Dec-22
      • {"lte": "2022-12-31"} – before 31-Dec-22
      • {"gte": "2022-12-01"} – on or after 1-Dec-22

Searching via the Search UI

Custom fields can be searched through the Search UI by updating the embeddable URL configuration. For more information, see Customising and Embedding the Search UI.

Patching and updating custom fields:

For detailed instructions, refer to the Patching and Updating Custom Fields Guide