Search & Match V2 (Beta)🔗︎

Search & Match V2 uses Textkernel's latest Search & Match engine. With Search & Match, you can empower your users with semantic search technology and a powerful matching engine, to discover the best candidates and jobs. A key advantage of Match V2 is the improved scoring (see below)

Getting Started🔗︎

Review our use cases to get started with Search & Match V2 APIs.

Or get started with the below overview and how to's.

Procedure to integrate match v2 into your solution:

Do prototyping/testing with the APIs to become familiar with their behaviour. For Match v2 you have access to both an acceptance/staging and a production environment.
(Optional) Configure any custom fields you want to use when searching for the candidates and jobs. A common example of a custom field would be a candidate's availability status, candidate source, or a job's posting status, or a job's customer account ID. Configure custom fields using the self-service TX portal
(Optional) Configure the search query result fields. You can receive all fields from the index in the result if you prefer, but maybe you are only using a relevant subset, and that is what you want to receive back from the search or match API calls. Excluding unnecessary fields makes the response faster to consume.
(Optional) Decide what, if any, facets you want to use to refine the search results in your application. Facets are categories or filters that you want to provide to your users (perhaps via your UI) to make it easier for them to refine their search and match results
(Optional) Decide whether you will want to configure data-segregation in your candidate and/or job search environment. Will all system users be able to see all candidates and all jobs? Or do you want to model ownership, so that users only see a relevant subset of jobs or candidates. For example, if you have a German division and a US division, perhaps they can only work with candidates and/or jobs from their respective country? If you want to restrict visibility, then you need to tag the candidates and/or jobs with a "Roles" attribute.
(Optional) Decide if you will need to create independent sub-accounts in your application. Sub-accounts are useful to partition the candidate and job data so that one sub-account cannot access data from another sub-account. They are also useful to keep pools of credits from one customer separate. So, if a customer had very heavy usage, they cannot exceed their sub-account limit and consume credits that you had planned to use for other customers. Note that your configuration in terms of custom fields, facets, and query result fields is the same and shared across all sub-accounts.
Now that you have decided on your search environment features, you can proceed to build your system's integration against the APIs. Consider business-as-usual operation, when you need to copy changes in the candidate and job profiles. But also consider how you will provision new end customers (eg sub-accounts, if relevant) and how you will initially load candidate and job data into your index before the system goes live. If you have millions of records it will take a significant amount of time that requires project planning. Remember that you have access to both a production environment and an acceptance environment, so changes can be tested in acceptance before deploying them to production.

Indexing🔗︎

In order to search or match against candidates and jobs, you first need load the data into your search index. To use Search & Match V2, simply pass in your cv(s)/resume(s) or job description documents to our parsing API, while setting the appropriate IndexingOptions properties. To upload candidate documents, use the add candidates endpoint or add jobs endpoint.

Search🔗︎

Search allows you to pass in a search query that is executed to return candidates from the candidate search endpoint(index) or jobs from the job search endpoint(index). You can either use our powerful query language, or for a simplified user experience at an added cost, you can submit a natural-language request, and allow our system to map it to a structured query.

Match🔗︎

Match generates a search query given a source document ID, and a document type (either candidate or job). It returns a list of matching candidates/jobs and details on why they match given the generated match query. It returns matching candidates if you use the candidate match endpoint, or it returns matching jobs if you use the jobs match endpoint.

Match v2 Score Calculation🔗︎

A key benefit of match v2 vs match v1 is the use of the Textkernel match algorithm. Match v2 provides improved match results as compared with match v1. This section provides a high-level overview of the mechanism.

Match v2 is a term-based matching engine. Scoring for Match queries is not fundamentally different from manually entered searches. The difference is that Match v2 generates a pre-constructed query from a job or candidate that is optimized to bring the most relevant matches to the top of your search results.

Weights🔗︎

Match v2 uses different weights on different criteria to optimize the quality of the matches. For example, skills can get a higher weight than the education level. The standard weights have been optimized over years based on a broad range of jobs, candidates, and customer environments.

Conditions🔗︎

The conditions of the term (nice-to-have / should-have / must-have / must-not-have) influences the weight. Moving from nice-to-have to should-have increases the weight for that particular term. Changing it to must-have or must-not-have turns it into a hard filter.

Depending on the weight configuration, each criteria gets assigned a fixed part of the score, illustrated in the pie chart below. Note that the values in this chart are arbitrary and only serve as an example.

Scoring Pie Chart

In this example we see that the job title criteria contributes 30% to the score. That means, if you get a perfect job title match, it will contribute 0.3 to the score of the result. The combined criteria add up to a score between 0 and 1 (where 0 is an unrelated result and 1 is a perfect match that matches all criteria).

Dynamic Match🔗︎

Some weights are modified depending on characteristics of the input job or candidate. For example: - If a job is remote, we don't include location in the query - If a job is in the IT domain, we value IT skills more

There are a number of rules that apply here. These two only serve as examples.

Boosting🔗︎

On top of that there are some general boosting mechanisms: - Recency boosting: job titles that are more recent are more important and get a higher score - Cross field boosting: e.g. skills occurring in a recent job title tend to be important

Semantic signals🔗︎

In the score calculation, other semantic signals than the query terms can play a role. This means that the terms in the query and the scoring explained above might not cover all edge cases. Sometimes the difference between a user's expected score and the actual score might differ due to these semantic signals. These signals may include information that is not covered by the structured (parsed) contents of the query, and are not always visible in the UI.

Frequently Asked Questions:🔗︎

How do I upgrade my Match integration from V1 to V2?

It is broadly similar to the integration procedure mentioned above, except that you already have a working match v1 integration and index.

Analyze your match v1 usage of custom fields, facets, ACLs, sub-accounts to understand how you need to configure the match v2 index. Consider what new features you may want to use from match v2, too.
Configure the match v2 environment according to your application needs.
Test/prototype the new match v2 endpoints for indexing data and retrieving matches.
Integrate the match v2 API calls into your application behind a configuration flag so you can switch between match v1 and match v2.
Load all of your job and candidate data into the match v2 job and candidate indices
Switchover the application to use the new match v2 endpoints

How do I edit the query that was auto-generated?

To edit the auto-generated query in the Match v2 API, you provide a Query object in your request body with additional query terms. The Query object will be combined with the auto-generated match query to drive the search.

The Match v2 API accepts a Query parameter that allows you to add filters, constraints, or additional search criteria on top of the auto-generated match query.

How do I page to the second page of a results set?

Sometimes the match results are returned across multiple pages. If the API response includes HasMoreResults set to True, it means additional result pages are available.

In this case, there is also a SearchAfter array value in the response. To retrieve the 2nd request, include the exact array contents from SearchAfter in the page 1 response as an input to the subsequent request for page 2. If there are additional pages of results beyond page 2, then you will can repeat this pattern.

How do I ensure compliance with my ACL (Access Control Lists) requirements?

ACL are implemented with the roles feature. You can think of roles as case-insensitive tags for a document. Examples on role strategies can be found in the Textkernel Documentation.

Once you decide on a strategy for roles, you need to ensure you're adding them in the right places. Follow the steps here:

Add the roles to the document during indexing (resumes/jobs)
Add the required roles to the queries. For example, on a search query add the roles here.

How do I update a resume or job that has already been indexed?

There are many situations that could warrant the need to update a record in the index. A few examples include:

A candidate adds new information to their profile such as an address that wasn't present on the resume.
A candidate completes some of the onboarding steps and their status changes in the ATS.
Critical information about a job changes such as desired skills.
Access control lists change and a user should no longer have access to a set of records

Match V2 doesn't support partial updates. Instead, it allows you to overwrite the entire indexed document. If something on the record changes, a new request is sent with a new JSON body to the index endpoints (resumes/jobs). This will override the entire record in the index, so make sure to populate the entire JSON body.

How do I index a profile that doesn't have a resume or job description?

In this case, you can synthesize a document from the structured data available about the candidate or job.

For Candidates, create a synthetic resume (eg, for a candidate, create a text file where you add name and contact information, list of work history and job descriptions, education, skills, etc to a document). You can also add some structured data as custom fields to the indexing request if it is not something that would normally appear in a resume. (For example information about salary expectations).

For Jobs, add the job description to a text file, and again you can add other structured data as custom fields.

How do I make something a filter vs how to make it influence the ranking?

You can use condition types to add filtering criteria to a query. We support: nice-to-have, should-have, must-have, and must-not-have

How can I change the importance of terms in the search query?

Controlling the importance of search terms in the query is a core part of the search experience. This can be accomplished two different ways:

When building query parts as objects, weight can be controlled using the Weight parameter.
When building a query string leveraging the Textkernel query syntax, weighting can be controlled using the syntax found in the weighting section.

How do I search with natural language?

Natural language querying can be enabled on any string based search. On the search request, set the UseNLQS parameter to true. More information about Textkernel Natural Language Query Search can be found in the documentation. Please note that this feature does have a cost that can be found in the transaction cost documentation.

How would I offer auto-complete functionality for users when typing in search query terms?

There is an autocomplete endpoint available to provide user instant feedback while typing a query.

How do I include data not found on a resume or job description in the search index?

You define custom fields in your index using the self-configuration portal, and then provide this data along with the resume or job description when indexing the document.