Skip to main

API Technical Specs

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

Search

POST /v10/searcher

Semantic search for resumes/jobs in certain indexes.

Request Body

IndexIdsToSearchIntooptionalstring[]
The ids of the indexes in which you want to find results (case-insensitive).
PaginationSettingsoptionalobject
Choose which results to return from the list.
PaginationSettings.Skipoptionalinteger
The number of results to skip before selecting the return values.
PaginationSettings.Takeoptionalinteger
The number of results to return. No more than 100 records can be returned.
Settingsoptionalobject
Options to control variations of job titles.
Settings.PositionTitlesMustHaveAnExactMatchoptionalbool
Set to true to turn off variation matches in job titles.
Settings.NormalizeJobTitlesoptionalbool
Normalize the first three job titles specified in FilterCriteria.JobTitles and automatically include them in the query. Additional charges apply.

You will only benefit from using this parameter if the data in your index was parsed with Professions Normalization enabled.

Normalized job titles help identify more matches by looking beyond the exact job title. Normalization uses lists of synonyms behind the scenes. For example, a search for "HR Advisor" will also return results for "Human Resources Consultant".

When matching, the normalized job title is automatically included in the query if the data in your index was parsed with Professions Normalization enabled.
Settings.NormalizeJobTitlesLanguageoptionalstring
Specify the language (ISO 639-1 code) of the Job Title to be normalized. This defaults to en. See list of supported languages.
FilterCriteriaoptionalobject
Additional criteria for the result set.
FilterCriteria.RevisionDateRangeoptionalobject
When specified, the revision date of documents must fall within this range.
FilterCriteria.RevisionDateRange.Minimumoptionalstring
The minimum allowed revision date for results in "YYYY-MM-DD" format. Default is 6 months before current date.
FilterCriteria.RevisionDateRange.Maximumoptionalstring
The maximum allowed revision date for results in "YYYY-MM-DD" format. Default is current date.
FilterCriteria.DocumentIdsoptionalstring[]
Results must have one of the specified document ids (case-insensitive).
FilterCriteria.UserDefinedTagsoptionalstring[]
List of user-defined tags. Either all or at least one are required depending on the value of FilterCriteria.UserDefinedTagsMustAllExist.
FilterCriteria.UserDefinedTagsMustAllExistoptionalbool
When true, all of the user-defined tags in FilterCriteria.UserDefinedTags must be found. By default, this is false, which means that at least one of the FilterCriteria.UserDefinedTags must be found.
FilterCriteria.LocationCriteriaoptionalobject[]
Filter results based on location.
FilterCriteria.LocationCriteria.Locationsoptionalobject[]
Results must be found within a certain distance of one of the specified locations.
FilterCriteria.LocationCriteria.Locations[i].CountryCodeoptionalstring
The 2-letter ISO 3166-1 alpha-2 country code for the specified location.
FilterCriteria.LocationCriteria.Locations[i].Regionoptionalstring
The region (i.e. State for U.S. addresses) for the location.
FilterCriteria.LocationCriteria.Locations[i].Municipalityoptionalstring
The municipality (i.e. City for U.S. addresses) for the location.
FilterCriteria.LocationCriteria.Locations[i].PostalCodeoptionalstring
The postal code (or zip code) for the location.
FilterCriteria.LocationCriteria.Locations[i].GeoPointoptionalobject
The geocordinates to be used in the location.
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Latitudeoptionaldecimal
The latitude coordinate value.
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Longitudeoptionaldecimal
The longitude coordinate value.
FilterCriteria.LocationCriteria.Distanceoptionalinteger
The distance from Locations within which to find results.
FilterCriteria.LocationCriteria.DistanceUnitoptionalstring
The units for the specified distance. One of:
  • Miles
  • Kilometers
FilterCriteria.LocationCriteria.GeocodeProvideroptionalstring
The provider to lookup latitude/longitude if they are not specified. One of:
  • None
  • Google
  • Bing
FilterCriteria.LocationCriteria.GeocodeProviderKeyoptionalstring
The key for the specified GeocodeProvider. If using Bing you must specify your own provider key.
FilterCriteria.SearchExpressionoptionalstring
Full-text boolean semantic expresion. For full details on the syntax and supported operations refer to the documentation
FilterCriteria.HasPatentsoptionalbool
If true, results must have/require patent experience.
FilterCriteria.HasSecurityCredentialsoptionalbool
If true, results must have/require security credentials. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.
FilterCriteria.SecurityCredentialsoptionalstring[]
Results must have/require at least one of the security credentials specified.
FilterCriteria.IsAuthoroptionalbool
If true, results must have/require experience as an author.
FilterCriteria.IsPublicSpeakeroptionalbool
If true, results must have/require public speaking experience.
FilterCriteria.IsMilitaryoptionalbool
If true, results must have/require military experience.
FilterCriteria.SchoolNamesoptionalstring[]
Results must have at least one of the specified school names. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators
FilterCriteria.DegreeNamesoptionalstring[]
Results must have at least one of the specified degree names. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.
FilterCriteria.DegreeTypesoptionalstring[]
Results must have at least one of the specified degree types. One of the following explicit values as defined by HROpenStandards.org, in increasing order:
  • specialeducation
  • someHighSchoolOrEquivalent
  • ged
  • secondary
  • highSchoolOrEquivalent
  • certification
  • vocational
  • someCollege
  • HND_HNC_OrEquivalent
  • associates
  • international
  • bachelors
  • somePostgraduate
  • masters
  • intermediategraduate
  • professional
  • postprofessional
  • doctorate
  • postdoctorate
FilterCriteria.Employersoptionalstring[]
Results must have at least one of the employers in FilterCriteria.Employers. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.
FilterCriteria.EmployersMustAllBeCurrentEmployeroptionalbool
When true, at least one employer in FilterCriteria.Employers must be found in the current time frame.
FilterCriteria.MonthsExperienceoptionalobject
When specified, results total work experieince must fall within this range.
FilterCriteria.MonthsExperience.Minimumoptionalinteger
Results must have/require at least the amount of total work experience specified.
FilterCriteria.MonthsExperience.Maximumoptionalinteger
Results must have/require at MOST the amount of total work experience specified.
FilterCriteria.DocumentLanguagesoptionalstring[]
Results must be written in one of the specified languages.
FilterCriteria.Skillsoptionalobject[]
Results must have/require at least one of the specified skills.
FilterCriteria.Skills[i].SkillNameoptionalstring
The name of the skill. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.
FilterCriteria.Skills[i].ExperienceLeveloptionalstring
The experience level of the skill. Supports the following values:
  • Low (0-3 years)
  • Mid (4-6 years)
  • High (7+ years)
FilterCriteria.Skills[i].IsCurrentoptionalbool
The skill must be a current skill.
FilterCriteria.SkillsMustAllExistoptionalbool
When true, all of the skills in FilterCriteria.Skills must be found. By default, this is false, which means that at least one of the FilterCriteria.Skills must be found.
FilterCriteria.IsTopStudentoptionalbool
Results must have an education with a normalized gpa of .75 or higher (for example, 3.0/4.0 or higher).
FilterCriteria.IsCurrentStudentoptionalbool
Results must have a current education.
FilterCriteria.IsRecentGraduateoptionalbool
Results must have graduated within the last 18 months
FilterCriteria.JobTitlesoptionalobject[]
Results must have at least one of the specified job titles.
FilterCriteria.JobTitles[i].Titleoptionalstring
The name of the Job Title. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.
FilterCriteria.JobTitles[i].IsCurrentoptionalbool
The job title must be a current job title.
FilterCriteria.ExecutiveTypeoptionalstring[]
Results must have at least one of the following types of executive:
  • None
  • Executive
  • Admin
  • Accounting
  • Operations
  • Financial
  • Marketing
  • Business_Dev
  • IT
  • General
  • Learning
FilterCriteria.Certificationsoptionalstring[]
Results must have at least one of the specified certifications. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.
FilterCriteria.MonthsManagementExperienceoptionalobject
Results must have the management experience specified in this months range.
FilterCriteria.MonthsManagementExperience.Minimumoptionalinteger
Lower bound of the management experience range.
FilterCriteria.MonthsManagementExperience.Maximumoptionalinteger
Upper bound of the management experience range.
FilterCriteria.CurrentManagementLeveloptionalstring
Results must currently have at least one of the following management levels:
  • None
  • Low
  • Mid
  • High
FilterCriteria.LanguagesKnownoptionalstring[]
List of ISO 639-1 language codes (lower case, two letters) representing languages known. Either all or at least one are required depending on the value of FilterCriteria.LanguagesKnownMustAllExist.
FilterCriteria.LanguagesKnownMustAllExistoptionalbool
When true, all of the languages in FilterCriteria.LanguagesKnown must be found. By default, this is false, which means that at least one of the FilterCriteria.LanguagesKnown must be found.
FilterCriteria.Taxonomiesoptionalstring[]
Results must contain at least one of the specified best-fit taxonomy IDs or best-fit subtaxonomy IDs. A list of our built-in taxonomy IDs can be found here.
FilterCriteria.AverageMonthsPerEmployeroptionalobject
Results must have an average months per employers specified in this range. Only applicable for resumes; setting this when filtering jobs will cause an error.
FilterCriteria.AverageMonthsPerEmployer.Minimumoptionalinteger
Lower bound of the average months per employer range.
FilterCriteria.AverageMonthsPerEmployer.Maximumoptionalinteger
Upper bound of the average months per employer range.
FilterCriteria.JobPredictiveIndexoptionalobject
Results must have a job predictive index specified in this range. Only applicable for resumes; setting this when filtering jobs will cause an error.
FilterCriteria.JobPredictiveIndex.Minimumoptionalinteger
Lower bound of the job predictive index range.
FilterCriteria.JobPredictiveIndex.Maximumoptionalinteger
Upper bound of the job predictive index range.

Sample Request

{ ... 
[ ... 
""
],
{ ... 
"Skip" :  0,"Take" :  0
},
{ ... 
"PositionTitlesMustHaveAnExactMatch" :  false,"NormalizeJobTitles" :  false,"NormalizeJobTitlesLanguage" :  ""
},
{ ... 
{ ... 
"Minimum" :  "","Maximum" :  ""
},
[ ... 
""
],
[ ... 
""
],
"UserDefinedTagsMustAllExist" :  false,{ ... 
[ ... 
{
"CountryCode" :  "","Region" :  "","Municipality" :  "","PostalCode" :  "",{ ... 
"Latitude" :  0,"Longitude" :  0
}
}
],
"Distance" :  0,"DistanceUnit" :  "Miles","GeocodeProvider" :  "None","GeocodeProviderKey" :  ""
},
"SearchExpression" :  "","HasPatents" :  false,"HasSecurityCredentials" :  false,[ ... 
""
],
"IsAuthor" :  false,"IsPublicSpeaker" :  false,"IsMilitary" :  false,[ ... 
""
],
[ ... 
""
],
[ ... 
""
],
[ ... 
""
],
"EmployersMustAllBeCurrentEmployer" :  false,{ ... 
"Minimum" :  0,"Maximum" :  0
},
[ ... 
""
],
[ ... 
{
"SkillName" :  "","ExperienceLevel" :  "",{ ... 
"Minimum" :  0,"Maximum" :  0
},
"IsCurrent" :  false
}
],
"SkillsMustAllExist" :  false,"IsTopStudent" :  false,"IsCurrentStudent" :  false,"IsRecentGraduate" :  false,[ ... 
{
"Title" :  "","IsCurrent" :  false
}
],
[ ... 
""
],
[ ... 
""
],
{ ... 
"Minimum" :  0,"Maximum" :  0
},
"CurrentManagementLevel" :  "",[ ... 
""
],
"LanguagesKnownMustAllExist" :  false,[ ... 
""
],
{ ... 
"Minimum" :  0,"Maximum" :  0
},
{ ... 
"Minimum" :  0,"Maximum" :  0
}
}
}

Response Body

Infoobject
Information explaining the outcome of the transaction.
Info.Codestring
A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

ConstraintError - A conditionally required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

Unauthorized - Your account doesn't have permission to perform this operation

DataNotFound - Couldn't find the requested asset
Info.Messageoptionalstring
This message further describes the code providing additional detail.
Info.TransactionIdstring
The (GUID) id for a specific API transaction. Use this when contacting support@sovren.comabout issues.
Info.EngineVersionstring
The version of the parsing/matching engine running under-the-hood.
Info.ApiVersionstring
The version of the API.
Info.TotalElapsedMillisecondsinteger
How long the transaction took on Sovren's server, in milliseconds. If the transaction takes longer to complete on the client side, that extra duration is solely network latency.
Info.TransactionCostdecimal
How many credits the transaction costs.How many credits the transaction costs.
Info.CustomerDetailsobject
Information about the customer who made the API call.
Value.CustomerDetails.AccountIdstring
The AccountId for the account.
Value.CustomerDetails.Namestring
The customer name on the account.
Value.CustomerDetails.IPAddressstring
The client IP Address where the API call originated.
Value.CustomerDetails.Regionstring
The region for the account, also known as the 'Data Center'.
Value.CustomerDetails.CreditsRemainingdecimal
The number of credits remaining to be used by the account.
Value.CustomerDetails.CreditsUseddecimal
The number of credits used by the account.
Value.CustomerDetails.MaximumConcurrentRequestsinteger
The number of requests that can be made at one time. If using sub-accounts, this is the maximum number of concurent requests across all accounts, not just this single sub-account.
Value.CustomerDetails.ExpirationDatedate
The date that the current credits expire.
Valueobject
Contains response data for the transaction.
Value.Matchesobject[]
An object[] containing the results for each result. Learn more about sort order.
Value.Matches[i].Idstring
Id of the matched document in the index.
Value.Matches[i].IndexIdstring
Id of the index in which the match was found.
Value.CurrentCountinteger
The number of results that were returned. This number will never be greater than the Take in the request.
Value.TotalCountinteger
The total number of match results found for the specified query. Only the top Take of these results are returned.
Value.ElapsedMillisecondsinteger
The number of milliseconds the query took.

Sample Response

{ ... 
{ ... 
"Code" :  "string","Message" :  "string","TransactionId" :  "string","EngineVersion" :  "string","ApiVersion" :  "string","TotalElapsedMilliseconds" :  0,"TransactionCost" :  0,{ ... 
"AccountId" :  "string","Name" :  "string","IPAddress" :  "string","Region" :  "string","CreditsRemaining" :  0,"CreditsUsed" :  0,"ExpirationDate" :  "2021-12-31","MaximumConcurrentRequests" :  0
}
},
{ ... 
[ ... 
{
"Id" :  "","IndexId" :  ""
}
],
"CurrentCount" :  0,"TotalCount" :  0,"ElapsedMilliseconds" :  0
}
}