Skip to main

API Technical Specs

Learn how to configure and leverage our services to achieve your toughest recruiting needs.
SaaS     |

Querying

Sovren's AI Matching Engine supports two types of queries, searching and matching.

Matching

Matching is where a document is provided and Sovren determines the criteria and returns the best candidates. Matching allows for humans to tell the engine what types of data are important using category weights while still letting Sovren do the heavy lifting of generating the query.

Match Workflow

Ideally, you'd have so many great matching resumes or jobs that those are all you'd see, but anyone that's done recruiting knows that there are at best a small number of great matches followed by a huge number of partial or weak matches. In some cases, depending on the actual contents of your index, the best match may be a weak match. The job of the AI Matching Engine is to show you the best matches, ranked best to worst by absolute score, so that your users can spend their time more efficiently than wading through huge volumes of bad matches.

Since our matching engine excels at sorting and scoring large document sets, it's not recommended to ever return more than 100 documents from a transaction. This is more results than a human has time to look through, and by going that deep in the dataset the results will be significantly worse. If you need to narrow the focus of a transaction, use the filtering layer to restrict the document set to a smaller subset of the index.

There are two endpoints you can use to perform a match.

Scores

Scores in matching are absolute and aren't influenced by filters or other data in the index. If the best fit you have scored a 1 (very low score) then it will be reported as a 1. Our engine doesn't use flawed density calculations or other common full-text scoring algorithms. We developed our own scoring calculation that evaluates two documents as a human would. Our matching returns those scores broken down by category with suggested weights for each category. This allows us to give suggested scores without removing users' ability to influence the calculation.

SovScore

SovScore is the overall score that represents the bidirectional fit between the source and target documents. This score is calculated from the Weighted Score and Reverse Compatibility Score using a proprietary algorithm. This considers both directions of the match.

Weighted Score

An integer score from 0-100 representing how well the target document matched the source document. This calculation is the sum of the unweighted category scores multiplied by their respective suggested weight.

Reverse Compatibility Score (RCS)

An integer score from 0-100 which represents how well the source document matched to the target document. This isn't the same as WeightedScore because when doing the reverse calculation, we are analyzing for all of the data from the target document to be found in the source document. For example, a position for a software developer that needs C#, Web Api, and SQL Server would have a high weighted score when matched to a full-stack engineer that knows C#, Web API, SQL Server, Html, CSS, JavaScript, typescript, and many other skills; however, the RCS score would be much lower, because from the candidates perspective, this job only requires a very small subset of the breadth of skills the candidate has.

Categories
CategoryExplanation
CertificationsList of certifications required or attained.
EducationHighest degree level required or attained.
Executive TypeIf an executive, then the type of executive (such as Executive, Operations, Financial, IT).
Job TitlesExact and partial match position titles.
LanguagesForeign languages required or attained.
Management LevelThe level of management required or attained, from low-level leadership and supervisory positions, to mid-level managers and directors, to high-level VPs, to C-level executives.
SkillsList of skills required or attained.
IndustriesBest Fit Taxonomy (industry) as calculated by an analysis of skills to fit a resume or job into categories such as "Information Technology → Programming" or "Finance → Accounting".

Filtering

There are many cases where you need to restrict the result set by some mandatory criteria. For example, you need to find a Java developer for a position in Dallas, Texas. You only want to see candidates that are a logistical fit for this position, so you only consider candidates within 30 miles of Dallas, Texas. This can be accomplished with a filter. For matching, filters are executed like this:(filter) AND (scoredMatchQuery). For the match to return a document as a result, it must satisfy criteria from both the filter and the scoredMatchQuery. If you expect your query to return results but you are not receiving any, try making the filter less restrictive or remove it altogether. Filters restrict the document set that matching evaluates doesn't impact the Bimetric Scoring calculation. Filters can be specified on both search and match API calls.

Semantic Filter

Filter a result set using an object-based representation of your query. These are the easiest to build, but don't have the same level of boolean flexibility as a full text filter. All of the properties queries are joined together by AND, but the terms in each property are joined together by OR by default. Some examples are provided below, but for full explanation of the FilterCriteria object and all of the available properties refer to the Search and Match endpoints. For example, to filter the result set to documents containing document id 1 or document id 2 AND employer Google AND (skill java or skill c#) use:

{  
    "FilterCriteria": {
        "DocumentId": [ "1", "2" ],
        "Employers": ["Google"],
        "Skills": [
            {
                "SkillName": "java",
            },
            {
                "SkillName": "c#",
            }
        ]
    }
}
Location Filtering

Our engine allows you to filter searches and matches based on an exact location, or a radius from that location. For example, we can filter to an exact match to Dallas, Texas, or say 25 miles from Dallas, Texas. When using a distance, our API will call out to Google to get the geo coordinates of the address you specify. Just like the Geocode endpoint, you can specify your account Google or Bing account, or you can pass the latitude and longitude directly into the search or match call. Geocoding in a search or match follows the same cost structure as the Geocode endpoint and is documented here.

Filter an exact address

{  
    "FilterCriteria": {
        "LocationCriteria": {
        "Locations": [
            {
            "CountryCode": "US",
            "Region": "Texas",
            "Municipality": "Dallas"
            }
        ]
        }
    }
}

Filter 25 miles from an exact address using the built in Google account

{  
    "FilterCriteria": {
        "LocationCriteria": {
        "Locations": [
            {
            "CountryCode": "US",
            "Region": "Texas",
            "Municipality": "Dallas"
            }
        ],
        "Distance": 25,
        "DistanceUnit": "Miles"
        }
    }
}

Filter 25 miles from an exact address using predefined latitude and longitude

{  
    "FilterCriteria": {
        "LocationCriteria": {
        "Locations": [
            {
            "GeoPoint": {
                "Latitude": 32.780115,
                "Longitude": -96.7851757
            },
            }
        ],
        "Distance": 25,
        "DistanceUnit": "Miles"
        }
    }
}
Full-text Filter

Filter a result set using a custom query expression. For example, to filter the result set to documents containing the word "Entity Framework" and currently have the skill c# use:

{  
    "FilterCriteria": {
        "SearchExpression": "skill:(c#) AND "Entity Framework""
    }
}

This is just a simple example of what full-text filtering can accomplish. This field supports standard full-text searches, semantic searches, or a combination of both types of searches.

Boolean Syntax

A Boolean search request consists of a group of words or phrases linked by connectors such as AND, OR, NOT that indicate the relationship between them.

ExpressionExplanation
apple AND pearBoth words must be present
apple OR pearEither word can be present
apple AND NOT pearapple must be present and pear must not be present

If you use more than one connector, you should use parentheses to indicate precisely what you want to search for. For example, apple AND pear OR orange could mean (apple AND pear) or orange, or it could mean apple AND (pear OR orange).

Special Operators

Search terms may include the following special characters:

CharacterExplanation
( )Parentheses for precedence and grouping
?Matches any single character. Example: appl? matches apply or apple.
*Matches any number of characters. Example: appl* matches application
~Fuzzy search. Example: managang~ matches managing.
Semantic Expressions

Search expressions support Semantic Clauses, which are Sovren extensions to the underlying search engine syntax that can be placed anywhere within the Boolean expression. Semantic Clauses take the following form: type:(term; parameter1=value; parameter2=value; ...)

Each parameter is separated by semicolons. If a term or parameter value contains an equal sign, semicolon or parentheses, then it must be surrounded by double-quotes or those characters must be escaped by a backslash character. When inside double-quotes, only double-quote characters must be escaped by a backslash. If the values come from user input, then make sure that you escape those values to prevent search syntax errors or unexpected results.

The following semantic clauses are supported:

Document Id

A DocumentId value. This is often used when scoring a single document or a small collection of documents. Syntax docid:(term)

User-Defined Tag

An alphanumeric token in one of the user-defined tags injected into Resumes or Jobs. These are often used for filtering or partitioning the data within an index by statuses or other custom fields. Syntax id:(term) for a range use [id:(term) TO id:(term)].

Examples
TermExplanation
id:(CFZAvailable20150116)Filter the user-defined tag CFZAvailable20190116
[id:(CFZAvailable20190101) TO id:(CFZAvailable20190131)]Filter the user-defined tag is a range from CFZAvailable20190101 to CFZAvailable20190131
Taxonomy/Industry

There is an implicit AND between each parameter and an implicit OR between each comma-delimited value. If you need more control over the Boolean logic, then use multiple taxonomy clauses. Syntax taxonomy:(parameters)

Parameters
TermExplanation
bestFitComma-delimited list of ids of the best fit top-level taxonomy.
bestFitSubComma-delimited list of ids of the best fit sub-taxonomy within the best fit top-level taxonomy.
secondBestFitComma-delimited list of ids of the second best fit top-level taxonomy.
secondBestFitSubComma-delimited list of ids of the best fit sub-taxonomy within the second best fit top-level taxonomy.
Skill

A skill term. Syntax: skill:(term;parameters). Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

Optional Parameters
TermExplanation
experienceLevelLevel of experience with this skill. Supported values: low, mid, and high.
monthsAgoLimit results to skills held within this number of months before the RevisionDate
Examples
TermExplanation
skill:(java)Filter the skill java
skill:(java;experienceLevel=low)Filter the skill java with low experience
skill:(java;monthsAgo=0)Filter documents that have the skill java currently
skill:(java;experienceLevel=low;monthsAgo=0)Filter documents that have the skill java currently and low experience
Certification/License

A certification or license term. Syntax certification:(term) or license:(term). Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

Job Title

A position title in the candidate's employment history or describing a job. Syntax title:(term;parameters). Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

Optional Parameters
TermExplanation
monthsAgoLimit results to job titles held within this number of months before the RevisionDate
includeVariationsDetermines whether or not to include variations of the original job title (For example, Developer instead of Web Developer - defaults to true)
Examples
TermExplanation
title:(Web Developer)Filter the job title Web Developer
title:(Web Developer;monthsAgo=0)Filter documents that have the job title Web Developer currently
title:(Web Developer;includeVariations=false)Filter documents that have the exact job title Web Developer
Assistant To

A position to which the candidate was an assistant, such as assistant to the "CEO". Syntax assistantTo:(term)

Employer

An employer/organization name in the candidate's employment history or describing a job. Syntax employer:(term;parameters). Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

Optional Parameters
TermExplanation
monthsAgoLimit results to employers held within this number of months before the RevisionDate
Examples
TermExplanation
employer:(Google)Filter the employer Google
employer:(Google;monthsAgo=0)Filter for current employer Google
Executive Type

The type of executive experience the candidate must have. Term must be one of the following list of supported executive types:NONE, EXECUTIVE, ADMIN, ACCOUNTING, OPERATIONS, FINANCIAL, MARKETING, BUSINESS_DEV, IT, GENERAL, LEARNING. Syntax executiveType:(term)

Current Management Level

The management level that a job requires or that a candidate has in the most recent position. Term must be one of the following list of supported management levels:None, Low, Mid, High. Syntax currentManagementLevel:(term)

Author

When true, resume must have at least one publication. When false, resume must not have any publications. This clause is only valid when resumes were parsed with PublicationHistory coverage enabled. See ParserSettings.Coverage.PatentsPublicationsAndSpeakingEvents setting in the parser configuration string. Syntax isAuthor:(term)

Public Speaker

When true, resume must have at least one speaking event. When false, resume must not have any speaking events. This clause is only valid when resumes were parsed with SpeakingEventsHistory coverage enabled. See ParserSettings.Coverage.PatentsPublicationsAndSpeakingEvents or the SkipSpeakingEventsParsing setting in the parser configuration string. Syntax isPublicSpeaker:(term)

Has Military History

When true, resume must have some military history. When false, resume must not have any military history. This clause is only valid when resumes were parsed with MilitaryHistory coverage enabled. See ParserSettings.Coverage.MilitaryHistoryAndSecurityCredentials or the SkipMilitaryHistoryParsing setting in the parser configuration string. Syntax isMilitary:(term)

Has Been Self Employed

When true, resume must have some self-employment history. When false, resume must not have any self-employment history. Syntax hasBeenSelfEmployed:(term)

Has Patents

When true, resume must have at least one patent. When false, resume must not have any patents. This clause is only valid when resumes were parsed with PatentHistory coverage enabled. See ParserSettings.Coverage.PatentsPublicationsAndSpeakingEvents or the SkipPatentsParsing setting in the parser configuration string. Syntax hasPatents:(term)

Has Security Credentials

When true, resume must have at least one security credential. When false, resume must not have any security credentials. This clause is only valid when resumes were parsed with SecurityCredentials coverage enabled. See ParserSettings.Coverage.SecurityCredentials or the SkipSecurityCredentialsParsing setting in the parser configuration string. Syntax hasSecurityCredentials:(term)

Security Credential

A security credential name. This clause is only valid when resumes were parsed with SecurityCredentials coverage enabled. See ParserSettings.Coverage.SecurityCredentials or the SkipSecurityCredentialsParsing setting in the parser configuration string. Syntax securityCredential:(term). Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

School Name

Either an exact match or a normalized version of a school name. For example, a search for "Purdue" will match "Purdue University" and vice versa. Syntax schoolName:(term). Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

Degree Name

An exact match of a degree name. Syntax degreeName:(term). Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

Degree Major

An exact match of a degree major. Syntax degreeMajor:(term). Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

Degree Type

A specific type of degree that a resume has or that a job requires. The term can be a common name for a degree like "Bachelor of Science" or one of the following list of supported degree types defined by the HR-XML standard:ged, secondary, highSchoolOrEquivalent, certification, vocational, someCollege, HND_HNC_OrEquivalent, associates, international, bachelors, somePostgraduate, masters, intermediategraduate, professional, postprofessional, doctorate, postdoctorateSyntax degreeType:(term)

Minimum Degree Level

A specific type of degree that is the minimum that a resume must have or that a job requires. The term can be a common name for a degree like "Bachelor of Science" or one of the following list of supported degree types defined by the HR-XML standard:ged, secondary, highSchoolOrEquivalent, certification, vocational, someCollege, HND_HNC_OrEquivalent, associates, international, bachelors, somePostgraduate, masters, intermediategraduate, professional, postprofessional, doctorate, postdoctorateSyntax minimumDegreeLevel:(term)

Minimum GPA

A normalized GPA value from 0.0 to 1.0, with 1.0 being the top mark. For example, 3.5 on a scale of 4.0 would have a value of 0.875. Syntax minimumGPA:(term)

Location

Location that takes multiple parameters AND'd together. Syntax location:(parameters)

Parameters
TermExplanation
countryISO 3166 2-letter country code.
postalCodePostal Code.
regionName or abbreviation of a state or province or region.
municipalityName of a city.
Postal Code

A postal code value. Syntax postalcode:(term)

Municipality

A city name. Syntax municipality:(term)

Region

The name or standardized postal abbreviation for a state or province. Syntax region:(term)

Country

ISO 3166 2-letter alpha code for the country. For example, "US" for United States, and "CA" for Canada. Syntax country:(term)

Language

A language known by the candidate or required by a job. The value is an ISO 639-1 two letter alpha code. For example, "en" for English, and "fr" for French. Syntax language:(term)

Document Language

The language of the document (resume or job order). The value is an ISO 639-1 two letter alpha code. For example, "en" for English, and "fr" for French. Syntax docLanguage:(term)