Match by Document
POST /v9/matcher/documents
Match a parsed resume/job to resumes/jobs in certain indexes.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Request Body
{ "ParsedDocument": "", "IndexIdsToSearchInto": [ "" ], "Take": 0, "CategoryWeights": [ { "Category": "", "Weight": 0 } ], "Settings": { "PositionTitlesMustHaveAnExactMatch": false, "PositionTitlesIgnoreSingleWordVariations": false }, "FilterCriteria": { "RevisionDateRange": { "Minimum": "", "Maximum": "" }, "DocumentIds": [ "" ], "CustomValueIds": [ "" ], "LocationCriteria": { "Locations": [ { "CountryCode": "", "Region": "", "Municipality": "", "PostalCode": "", "GeoPoint": { "Latitude": 0, "Longitude": 0 } } ], "Distance": 0, "GeocodeProvider": "None", "DistanceUnit": "Miles", "GeocodeProviderKey": "" }, "SearchExpression": "", "HasPatents": false, "HasSecurityCredentials": false, "SecurityCredentials": [ "" ], "IsAuthor": false, "IsPublicSpeaker": false, "IsMilitary": false, "Educations": [ { "SchoolName": "", "DegreeMajor": "", "DegreeName": "", "DegreeType": "", "MinimumGPA": 0 } ], "Employers": [ "" ], "MonthsExperience": { "Minimum": 0, "Maximum": 0 }, "DocumentLanguages": [ "" ], "Skills": [ { "SkillName": "", "MonthsOfExperienceRange": { "Minimum": 0, "Maximum": 0 }, "IsCurrent": false } ] } }
Field | Data Type | Required | Description |
---|---|---|---|
ParsedDocument | string | Yes | Parsed JSON/XML from the Sovren Resume or Job Order Parser. |
IndexIdsToSearchInto | string[] | Yes | The ids of the indexes in which you want to find results. |
Take | integer | No | The number of results to return. |
CategoryWeights | CategoryWeight[] | No | List of categories with weights that determine how the WeightedScore is calculated. It's important to specify these before the match so the query returns the top results using these weights. Only the categories included in this list will be used to calculate the WeightedScore. |
CategoryWeights.Category | string | No | The name of the category. One of: {"EDUCATION", "JOB_TITLES", "SKILLS", "INDUSTRIES", "LANGUAGES", "CERTIFICATIONS", "EXECUTIVE_TYPE", "MANAGEMENT_LEVEL"} |
CategoryWeights.Weight | decimal | No | The weight of the category relative to other categories. It's recommended for the specified categories to add up to 1, so it's obvious how the percentages are applied. |
Settings.PositionTitlesMustHaveAnExactMatch | bool | No | Set to true to turn off variation matches in job titles. |
Settings.PositionTitlesIgnoreSingleWordVariations | bool | No | Set to true to ignore single-word variations of multi-word job titles. |
FilterCriteria.RevisionDateRange.Minimum | string | No | The minimum allowed revision date for results in "YYYY-MM-DD" format. Default is 6 months before current date. |
FilterCriteria.RevisionDateRange.Maximum | string | No | The maximum allowed revision date for results in "YYYY-MM-DD" format. Default is current date. |
FilterCriteria.DocumentIds | string[] | No | Results must have one of the specified document ids. |
FilterCriteria.CustomValueIds | string[] | No | Results must have at least one of the specified custom value ids. |
FilterCriteria.LocationCriteria.Locations | object[] | No | Results must be found within a certain distance of one of the specified locations. |
FilterCriteria.LocationCriteria.Locations[i].CountryCode | string | No | The 2-letter ISO 3166-1 alpha-2 country code for the specified location. |
FilterCriteria.LocationCriteria.Locations[i].Region | string | No | The region (i.e. State for U.S. addresses) for the location. |
FilterCriteria.LocationCriteria.Locations[i].Municipality | string | No | The municipality (i.e. City for U.S. addresses) for the location. |
FilterCriteria.LocationCriteria.Locations[i].PostalCode | string | No | The postal code (or zip code) for the location. |
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Latitude | decimal | No | The latitude coordinate value. |
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Longitude | decimal | No | The longitude coordinate value. |
FilterCriteria.LocationCriteria.Distance | integer | No | The distance from Locations within which to find results. |
FilterCriteria.LocationCriteria.DistanceUnit | string | No | The units for the specified distance. One of: {"Miles", "Kilometers"} |
FilterCriteria.LocationCriteria.GeocodeProvider | string | Conditional | The provider to lookup latitude/longitude if they are not specified. One of: {"None", "Google", "Bing"} |
FilterCriteria.LocationCriteria.GeocodeProviderKey | string | Conditional | The key for the specified GeocodeProvider. If using Bing you must specify your own provider key. |
FilterCriteria.SearchExpression | string | No | Full-text boolean semantic expresion. For full details on the syntax and supported operations refer to the documentation |
FilterCriteria.HasPatents | bool | No | If true, results must have/require patent experience. |
FilterCriteria.HasSecurityCredentials | bool | No | If true, results must have/require security credentials. |
FilterCriteria.SecurityCredentials | string[] | No | Results must have/require at least one of the security credentials specified. |
FilterCriteria.IsAuthor | bool | No | If true, results must have/require experience as an author. |
FilterCriteria.IsPublicSpeaker | bool | No | If true, results must have/require public speaking experience. |
FilterCriteria.IsMilitary | bool | No | If true, results must have/require military experience. |
FilterCriteria.Educations | object[] | No | Results must have at least one of the specified educations. |
FilterCriteria.Educations[i].SchoolName | string | No | The name of a university/college/tech school. |
FilterCriteria.Educations[i].DegreeMajor | string | No | A degree major (eg. "Chemistry", "Architecture", etc.) |
FilterCriteria.Educations[i].DegreeName | string | No | A free-text field for the degree name. |
FilterCriteria.Educations[i].DegreeType | string | No |
A specific level of education. One of the following explicit values
as defined by HROpenStandards.org, in increasing order:
|
FilterCriteria.Educations[i].MinimumGPA | decimal | No | 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. |
FilterCriteria.Employers | string[] | No | Results must have at least one of the specified employers. |
FilterCriteria.MonthsExperience.Minimum | integer | No | Results must have/require at least the amount of total work experience specified. |
FilterCriteria.MonthsExperience.Maximum | integer | No | Results must have/require at MOST the amount of total work experience specified. |
FilterCriteria.DocumentLanguages | string[] | No | Results must be written in one of the specified languages. |
FilterCriteria.Skills | object[] | No | Results must have/require at least one of the specified skills. |
FilterCriteria.Skills[i].SkillName | string | No | The name of the skill. |
FilterCriteria.Skills[i].MonthsOfExperienceRange.Minimum | integer | No | The minimum amount of experience with this skill. |
FilterCriteria.Skills[i].MonthsOfExperienceRange.Maximum | integer | No | The maximum amount of experience with this skill. |
FilterCriteria.Skills[i].IsCurrent | bool | No | The skill must be a current skill. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { "Matches": [ { "Id": "", "IndexId": "", "WeightedScore": 0, "UnweightedCategoryScores": [ { "Category": "", "UnweightedScore": 0, "TermsFound": [ "" ] } ], "ReverseCompatibilityScore": 0 } ], "SuggestedCategoryWeights": [ { "Category": "", "Weight": 0 } ], "AppliedCategoryWeights": [ { "Category": "", "Weight": 0 } ], "CurrentCount": 0, "TotalCount": 0, "ElapsedMilliseconds": 0, "CreditsRemaining": 0 } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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.Message | string | This message further describes the code providing additional detail. |
Value.Matches | object[] | An object[] containing the results for each match result. |
Value.Matches[i].Id | string | Id of the matched document in the index. |
Value.Matches[i].IndexId | string | Id of the index in which the match was found. |
Value.Matches[i].WeightedScore | integer | An integer score from 0-100 representing how well the source document matched the current document. This calculation is the sum of the unweighted category weights multiplied by their respective suggested weight. |
Value.Matches[i].UnweightedCategoryScores | object[] | An object[] containing the scoring breakdown per category. |
Value.Matches[i].UnweightedCategoryScores[i].Category | string | Name of the category. |
Value.Matches[i].UnweightedCategoryScores[i].UnweightedScore | decimal | An unweighted score from 0-100. This is the percentage match of the specified category. This can be used in conjunction with the SuggestedCategoryWeights to calculate the WeightedScore. |
Value.Matches[i].UnweightedCategoryScores[i].TermsFound | string[] | A string[] of terms for the specified category that matched between the source and this document. |
Value.Matches[i].ReverseCompatibilityScore | integer | An integer score from 0-100 which represents how well the target document matched to the source document/criteria. 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/criteria. |
Value.SuggestedCategoryWeights | object[] | An object[] containing our suggested weights for each category based on the source document. |
Value.SuggestedCategoryWeights[i].Category | string | Name of the category. |
Value.SuggestedCategoryWeights[i].Weight | decimal | A 0-100 weight of suggested importance for the speficied category. This is calculated from the data in the source document. A sum of all of the SuggestedCategoryWeights will equal 100. |
Value.AppliedCategoryWeights | object[] | An object[] containing the weights that were used for each category based on a combination of the data in the source document (or criteria) and any desired weights passed in the request. |
Value.AppliedCategoryWeights[i].Category | string | Name of the category. |
Value.AppliedCategoryWeights[i].Weight | decimal | A 0-100 weight of suggested importance for the speficied category. This is calculated from the data in the source document combined with any desired weights passed in the request. A sum of all of the AppliedCategoryWeights will equal 100. |
Value.CurrentCount | integer | The number of results that were returned. This number will never be greater than the Take in the request. |
Value.TotalCount | integer | The total number of match results found for the specified query. Only the top Take of these results are returned. |
Value.ElapsedMilliseconds | integer | The number of milliseconds the query took. |
Value.CreditsRemaining | decimal | The number of remaining credits is returned with every response. Please ensure that you set up monitoring of this value to ensure that you don't experience an outage by letting your credits reach 0. |
Match by Document Id
POST /v9/matcher/indexes/{indexId}/documents/{documentId}
Match a parsed resume/job to resumes/jobs in certain indexes.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | Id of the index that the source document is located in. |
documentId | string | Id of the document to use as the source for matching. |
Request Body
{ "IndexIdsToSearchInto": [ "" ], "Take": 0, "CategoryWeights": [ { "Category": "", "Weight": 0 } ], "Settings": { "PositionTitlesMustHaveAnExactMatch": false, "PositionTitlesIgnoreSingleWordVariations": false }, "FilterCriteria": { "RevisionDateRange": { "Minimum": "", "Maximum": "" }, "DocumentIds": [ "" ], "CustomValueIds": [ "" ], "LocationCriteria": { "Locations": [ { "CountryCode": "", "Region": "", "Municipality": "", "PostalCode": "", "GeoPoint": { "Latitude": 0, "Longitude": 0 } } ], "Distance": 0, "GeocodeProvider": "None", "DistanceUnit": "Miles", "GeocodeProviderKey": "" }, "SearchExpression": "", "HasPatents": false, "HasSecurityCredentials": false, "SecurityCredentials": [ "" ], "IsAuthor": false, "IsPublicSpeaker": false, "IsMilitary": false, "Educations": [ { "SchoolName": "", "DegreeMajor": "", "DegreeName": "", "DegreeType": "", "MinimumGPA": 0 } ], "Employers": [ "" ], "MonthsExperience": { "Minimum": 0, "Maximum": 0 }, "DocumentLanguages": [ "" ], "Skills": [ { "SkillName": "", "MonthsOfExperienceRange": { "Minimum": 0, "Maximum": 0 }, "IsCurrent": false } ] } }
Field | Data Type | Required | Description |
---|---|---|---|
IndexIdsToSearchInto | string[] | Yes | The ids of the indexes in which you want to find results. |
Take | integer | No | The number of results to return. |
CategoryWeights | CategoryWeight[] | No | List of categories with weights that determine how the WeightedScore is calculated. It's important to specify these before the match so the query returns the top results using these weights. Only the categories included in this list will be used to calculate the WeightedScore. |
CategoryWeights.Category | string | No | The name of the category. One of: {"EDUCATION", "JOB_TITLES", "SKILLS", "INDUSTRIES", "LANGUAGES", "CERTIFICATIONS", "EXECUTIVE_TYPE", "MANAGEMENT_LEVEL"} |
CategoryWeights.Weight | decimal | No | The weight of the category relative to other categories. It's recommended for the specified categories to add up to 1, so it's obvious how the percentages are applied. |
Settings.PositionTitlesMustHaveAnExactMatch | bool | No | Set to true to turn off variation matches in job titles. |
Settings.PositionTitlesIgnoreSingleWordVariations | bool | No | Set to true to ignore single-word variations of multi-word job titles. |
FilterCriteria.RevisionDateRange.Minimum | string | No | The minimum allowed revision date for results in "YYYY-MM-DD" format. Default is 6 months before current date. |
FilterCriteria.RevisionDateRange.Maximum | string | No | The maximum allowed revision date for results in "YYYY-MM-DD" format. Default is current date. |
FilterCriteria.DocumentIds | string[] | No | Results must have one of the specified document ids. |
FilterCriteria.CustomValueIds | string[] | No | Results must have at least one of the specified custom value ids. |
FilterCriteria.LocationCriteria.Locations | object[] | No | Results must be found within a certain distance of one of the specified locations. |
FilterCriteria.LocationCriteria.Locations[i].CountryCode | string | No | The 2-letter ISO 3166-1 alpha-2 country code for the specified location. |
FilterCriteria.LocationCriteria.Locations[i].Region | string | No | The region (i.e. State for U.S. addresses) for the location. |
FilterCriteria.LocationCriteria.Locations[i].Municipality | string | No | The municipality (i.e. City for U.S. addresses) for the location. |
FilterCriteria.LocationCriteria.Locations[i].PostalCode | string | No | The postal code (or zip code) for the location. |
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Latitude | decimal | No | The latitude coordinate value. |
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Longitude | decimal | No | The longitude coordinate value. |
FilterCriteria.LocationCriteria.Distance | integer | No | The distance from Locations within which to find results. |
FilterCriteria.LocationCriteria.DistanceUnit | string | No | The units for the specified distance. One of: {"Miles", "Kilometers"} |
FilterCriteria.LocationCriteria.GeocodeProvider | string | Conditional | The provider to lookup latitude/longitude if they are not specified. One of: {"None", "Google", "Bing"} |
FilterCriteria.LocationCriteria.GeocodeProviderKey | string | Conditional | The key for the specified GeocodeProvider. If using Bing you must specify your own provider key. |
FilterCriteria.SearchExpression | string | No | Full-text boolean semantic expresion. For full details on the syntax and supported operations refer to the documentation |
FilterCriteria.HasPatents | bool | No | If true, results must have/require patent experience. |
FilterCriteria.HasSecurityCredentials | bool | No | If true, results must have/require security credentials. |
FilterCriteria.SecurityCredentials | string[] | No | Results must have/require at least one of the security credentials specified. |
FilterCriteria.IsAuthor | bool | No | If true, results must have/require experience as an author. |
FilterCriteria.IsPublicSpeaker | bool | No | If true, results must have/require public speaking experience. |
FilterCriteria.IsMilitary | bool | No | If true, results must have/require military experience. |
FilterCriteria.Educations | object[] | No | Results must have at least one of the specified educations. |
FilterCriteria.Educations[i].SchoolName | string | No | The name of a university/college/tech school. |
FilterCriteria.Educations[i].DegreeMajor | string | No | A degree major (eg. "Chemistry", "Architecture", etc.) |
FilterCriteria.Educations[i].DegreeName | string | No | A free-text field for the degree name. |
FilterCriteria.Educations[i].DegreeType | string | No |
A specific level of education. One of the following explicit values
as defined by HROpenStandards.org, in increasing order:
|
FilterCriteria.Educations[i].MinimumGPA | decimal | No | 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. |
FilterCriteria.Employers | string[] | No | Results must have at least one of the specified employers. |
FilterCriteria.MonthsExperience.Minimum | integer | No | Results must have/require at least the amount of total work experience specified. |
FilterCriteria.MonthsExperience.Maximum | integer | No | Results must have/require at MOST the amount of total work experience specified. |
FilterCriteria.DocumentLanguages | string[] | No | Results must be written in one of the specified languages. |
FilterCriteria.Skills | object[] | No | Results must have/require at least one of the specified skills. |
FilterCriteria.Skills[i].SkillName | string | No | The name of the skill. |
FilterCriteria.Skills[i].MonthsOfExperienceRange.Minimum | integer | No | The minimum amount of experience with this skill. |
FilterCriteria.Skills[i].MonthsOfExperienceRange.Maximum | integer | No | The maximum amount of experience with this skill. |
FilterCriteria.Skills[i].IsCurrent | bool | No | The skill must be a current skill. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { "Matches": [ { "Id": "", "IndexId": "", "WeightedScore": 0, "UnweightedCategoryScores": [ { "Category": "", "UnweightedScore": 0, "TermsFound": [ "" ] } ], "ReverseCompatibilityScore": 0 } ], "SuggestedCategoryWeights": [ { "Category": "", "Weight": 0 } ], "AppliedCategoryWeights": [ { "Category": "", "Weight": 0 } ], "CurrentCount": 0, "TotalCount": 0, "ElapsedMilliseconds": 0, "CreditsRemaining": 0 } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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.Message | string | This message further describes the code providing additional detail. |
Value.Matches | object[] | An object[] containing the results for each match result. |
Value.Matches[i].Id | string | Id of the matched document in the index. |
Value.Matches[i].IndexId | string | Id of the index in which the match was found. |
Value.Matches[i].WeightedScore | integer | An integer score from 0-100 representing how well the source document matched the current document. This calculation is the sum of the unweighted category weights multiplied by their respective suggested weight. |
Value.Matches[i].UnweightedCategoryScores | object[] | An object[] containing the scoring breakdown per category. |
Value.Matches[i].UnweightedCategoryScores[i].Category | string | Name of the category. |
Value.Matches[i].UnweightedCategoryScores[i].UnweightedScore | decimal | An unweighted score from 0-100. This is the percentage match of the specified category. This can be used in conjunction with the SuggestedCategoryWeights to calculate the WeightedScore. |
Value.Matches[i].UnweightedCategoryScores[i].TermsFound | string[] | A string[] of terms for the specified category that matched between the source and this document. |
Value.Matches[i].ReverseCompatibilityScore | integer | An integer score from 0-100 which represents how well the target document matched to the source document/criteria. 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/criteria. |
Value.SuggestedCategoryWeights | object[] | An object[] containing our suggested weights for each category based on the source document. |
Value.SuggestedCategoryWeights[i].Category | string | Name of the category. |
Value.SuggestedCategoryWeights[i].Weight | decimal | A 0-100 weight of suggested importance for the speficied category. This is calculated from the data in the source document. A sum of all of the SuggestedCategoryWeights will equal 100. |
Value.AppliedCategoryWeights | object[] | An object[] containing the weights that were used for each category based on a combination of the data in the source document (or criteria) and any desired weights passed in the request. |
Value.AppliedCategoryWeights[i].Category | string | Name of the category. |
Value.AppliedCategoryWeights[i].Weight | decimal | A 0-100 weight of suggested importance for the speficied category. This is calculated from the data in the source document combined with any desired weights passed in the request. A sum of all of the AppliedCategoryWeights will equal 100. |
Value.CurrentCount | integer | The number of results that were returned. This number will never be greater than the Take in the request. |
Value.TotalCount | integer | The total number of match results found for the specified query. Only the top Take of these results are returned. |
Value.ElapsedMilliseconds | integer | The number of milliseconds the query took. |
Value.CreditsRemaining | decimal | The number of remaining credits is returned with every response. Please ensure that you set up monitoring of this value to ensure that you don't experience an outage by letting your credits reach 0. |
Match by Criteria
POST /v9/matcher/criteria
Match a parsed resume/job to resumes/jobs in certain indexes.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Request Body
{ "MatchCriteria": { "TaxonomyCriteria": { "BestFitTaxonomyId": 0, "BestFitSubTaxonomyId": 0, "SecondBestFitTaxonomyId": 0, "SecondBestFitSubTaxonomyId": 0 }, "Skills": [ "" ], "PositionTitles": [ "" ], "MonthsManagementExperience": { "Minimum": 0, "Maximum": 0 }, "CurrentManagementLevel": "", "ExecutiveType": "", "MinimumDegreeLevel": "", "LicensesAndCertifications": [ "" ], "Languages": [ "" ] }, "IndexIdsToSearchInto": [ "" ], "Take": 0, "CategoryWeights": [ { "Category": "", "Weight": 0 } ], "Settings": { "PositionTitlesMustHaveAnExactMatch": false, "PositionTitlesIgnoreSingleWordVariations": false }, "FilterCriteria": { "RevisionDateRange": { "Minimum": "", "Maximum": "" }, "DocumentIds": [ "" ], "CustomValueIds": [ "" ], "LocationCriteria": { "Locations": [ { "CountryCode": "", "Region": "", "Municipality": "", "PostalCode": "", "GeoPoint": { "Latitude": 0, "Longitude": 0 } } ], "Distance": 0, "GeocodeProvider": "None", "DistanceUnit": "Miles", "GeocodeProviderKey": "" }, "SearchExpression": "", "HasPatents": false, "HasSecurityCredentials": false, "SecurityCredentials": [ "" ], "IsAuthor": false, "IsPublicSpeaker": false, "IsMilitary": false, "Educations": [ { "SchoolName": "", "DegreeMajor": "", "DegreeName": "", "DegreeType": "", "MinimumGPA": 0 } ], "Employers": [ "" ], "MonthsExperience": { "Minimum": 0, "Maximum": 0 }, "DocumentLanguages": [ "" ], "Skills": [ { "SkillName": "", "MonthsOfExperienceRange": { "Minimum": 0, "Maximum": 0 }, "IsCurrent": false } ] } }
Field | Data Type | Required | Description |
---|---|---|---|
MatchCriteria | object | Yes | Object representing the source criteria to match against. At least one data point is required. |
MatchCriteria.TaxonomyCriteria.BestFitTaxonomyId | string | No | Results will score higher if they have the specified best-fit taxonomy. A list of our built-in taxonomy IDs can be found here. |
MatchCriteria.TaxonomyCriteria.BestFitSubTaxonomyId | string | No | Results will score higher if they have the specified best-fit subtaxonomy. |
MatchCriteria.TaxonomyCriteria.SecondBestFitTaxonomyId | string | No | Results will score higher if they have the specified second-best-fit taxonomy. |
MatchCriteria.TaxonomyCriteria.SecondBestFitSubTaxonomyId | string | No | Results will score higher if they have the specified second-best-fit subtaxonomy. |
MatchCriteria.Skills | string[] | No | One or more desired (optional) skills. |
MatchCriteria.PositionTitles | string[] | No | One or more desired job titles. Recommend that you pass a single title. |
MatchCriteria.MonthsManagementExperience.Minimum | integer | No | The minimum amount of management experience to search for. |
MatchCriteria.MonthsManagementExperience.Maximum | integer | No | The maximum amount of management experience to search for. |
MatchCriteria.CurrentManagementLevel | string | No | The current level of management, expressed as one of these values: {"None", "Low", "Mid", "High"}. |
MatchCriteria.ExecutiveType | string | No |
The type of executive. One of the following case-insensitive values:
|
MatchCriteria.MinimumDegreeLevel | string | No | The level of education to search for. See FilterCriteria.Educations[i].DegreeType for possible values. |
MatchCriteria.LicensesAndCertifications | string[] | No | One or more licenses or certifications. Name must match exactly. |
MatchCriteria.Languages | string[] | No | One or more known languages. A ISO 639-1 language code (lower case, two letters). |
IndexIdsToSearchInto | string[] | Yes | The ids of the indexes in which you want to find results. |
Take | integer | No | The number of results to return. |
CategoryWeights | CategoryWeight[] | No | List of categories with weights that determine how the WeightedScore is calculated. It's important to specify these before the match so the query returns the top results using these weights. Only the categories included in this list will be used to calculate the WeightedScore. |
CategoryWeights.Category | string | No | The name of the category. One of: {"EDUCATION", "JOB_TITLES", "SKILLS", "INDUSTRIES", "LANGUAGES", "CERTIFICATIONS", "EXECUTIVE_TYPE", "MANAGEMENT_LEVEL"} |
CategoryWeights.Weight | decimal | No | The weight of the category relative to other categories. It's recommended for the specified categories to add up to 1, so it's obvious how the percentages are applied. |
Settings.PositionTitlesMustHaveAnExactMatch | bool | No | Set to true to turn off variation matches in job titles. |
Settings.PositionTitlesIgnoreSingleWordVariations | bool | No | Set to true to ignore single-word variations of multi-word job titles. |
FilterCriteria.RevisionDateRange.Minimum | string | No | The minimum allowed revision date for results in "YYYY-MM-DD" format. Default is 6 months before current date. |
FilterCriteria.RevisionDateRange.Maximum | string | No | The maximum allowed revision date for results in "YYYY-MM-DD" format. Default is current date. |
FilterCriteria.DocumentIds | string[] | No | Results must have one of the specified document ids. |
FilterCriteria.CustomValueIds | string[] | No | Results must have at least one of the specified custom value ids. |
FilterCriteria.LocationCriteria.Locations | object[] | No | Results must be found within a certain distance of one of the specified locations. |
FilterCriteria.LocationCriteria.Locations[i].CountryCode | string | No | The 2-letter ISO 3166-1 alpha-2 country code for the specified location. |
FilterCriteria.LocationCriteria.Locations[i].Region | string | No | The region (i.e. State for U.S. addresses) for the location. |
FilterCriteria.LocationCriteria.Locations[i].Municipality | string | No | The municipality (i.e. City for U.S. addresses) for the location. |
FilterCriteria.LocationCriteria.Locations[i].PostalCode | string | No | The postal code (or zip code) for the location. |
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Latitude | decimal | No | The latitude coordinate value. |
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Longitude | decimal | No | The longitude coordinate value. |
FilterCriteria.LocationCriteria.Distance | integer | No | The distance from Locations within which to find results. |
FilterCriteria.LocationCriteria.DistanceUnit | string | No | The units for the specified distance. One of: {"Miles", "Kilometers"} |
FilterCriteria.LocationCriteria.GeocodeProvider | string | Conditional | The provider to lookup latitude/longitude if they are not specified. One of: {"None", "Google", "Bing"} |
FilterCriteria.LocationCriteria.GeocodeProviderKey | string | Conditional | The key for the specified GeocodeProvider. If using Bing you must specify your own provider key. |
FilterCriteria.SearchExpression | string | No | Full-text boolean semantic expresion. For full details on the syntax and supported operations refer to the documentation |
FilterCriteria.HasPatents | bool | No | If true, results must have/require patent experience. |
FilterCriteria.HasSecurityCredentials | bool | No | If true, results must have/require security credentials. |
FilterCriteria.SecurityCredentials | string[] | No | Results must have/require at least one of the security credentials specified. |
FilterCriteria.IsAuthor | bool | No | If true, results must have/require experience as an author. |
FilterCriteria.IsPublicSpeaker | bool | No | If true, results must have/require public speaking experience. |
FilterCriteria.IsMilitary | bool | No | If true, results must have/require military experience. |
FilterCriteria.Educations | object[] | No | Results must have at least one of the specified educations. |
FilterCriteria.Educations[i].SchoolName | string | No | The name of a university/college/tech school. |
FilterCriteria.Educations[i].DegreeMajor | string | No | A degree major (eg. "Chemistry", "Architecture", etc.) |
FilterCriteria.Educations[i].DegreeName | string | No | A free-text field for the degree name. |
FilterCriteria.Educations[i].DegreeType | string | No |
A specific level of education. One of the following explicit values
as defined by HROpenStandards.org, in increasing order:
|
FilterCriteria.Educations[i].MinimumGPA | decimal | No | 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. |
FilterCriteria.Employers | string[] | No | Results must have at least one of the specified employers. |
FilterCriteria.MonthsExperience.Minimum | integer | No | Results must have/require at least the amount of total work experience specified. |
FilterCriteria.MonthsExperience.Maximum | integer | No | Results must have/require at MOST the amount of total work experience specified. |
FilterCriteria.DocumentLanguages | string[] | No | Results must be written in one of the specified languages. |
FilterCriteria.Skills | object[] | No | Results must have/require at least one of the specified skills. |
FilterCriteria.Skills[i].SkillName | string | No | The name of the skill. |
FilterCriteria.Skills[i].MonthsOfExperienceRange.Minimum | integer | No | The minimum amount of experience with this skill. |
FilterCriteria.Skills[i].MonthsOfExperienceRange.Maximum | integer | No | The maximum amount of experience with this skill. |
FilterCriteria.Skills[i].IsCurrent | bool | No | The skill must be a current skill. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { "Matches": [ { "Id": "", "IndexId": "", "WeightedScore": 0, "UnweightedCategoryScores": [ { "Category": "", "UnweightedScore": 0, "TermsFound": [ "" ] } ], "ReverseCompatibilityScore": 0 } ], "SuggestedCategoryWeights": [ { "Category": "", "Weight": 0 } ], "AppliedCategoryWeights": [ { "Category": "", "Weight": 0 } ], "CurrentCount": 0, "TotalCount": 0, "ElapsedMilliseconds": 0, "CreditsRemaining": 0 } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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.Message | string | This message further describes the code providing additional detail. |
Value.Matches | object[] | An object[] containing the results for each match result. |
Value.Matches[i].Id | string | Id of the matched document in the index. |
Value.Matches[i].IndexId | string | Id of the index in which the match was found. |
Value.Matches[i].WeightedScore | integer | An integer score from 0-100 representing how well the source document matched the current document. This calculation is the sum of the unweighted category weights multiplied by their respective suggested weight. |
Value.Matches[i].UnweightedCategoryScores | object[] | An object[] containing the scoring breakdown per category. |
Value.Matches[i].UnweightedCategoryScores[i].Category | string | Name of the category. |
Value.Matches[i].UnweightedCategoryScores[i].UnweightedScore | decimal | An unweighted score from 0-100. This is the percentage match of the specified category. This can be used in conjunction with the SuggestedCategoryWeights to calculate the WeightedScore. |
Value.Matches[i].UnweightedCategoryScores[i].TermsFound | string[] | A string[] of terms for the specified category that matched between the source and this document. |
Value.Matches[i].ReverseCompatibilityScore | integer | An integer score from 0-100 which represents how well the target document matched to the source document/criteria. 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/criteria. |
Value.SuggestedCategoryWeights | object[] | An object[] containing our suggested weights for each category based on the source document. |
Value.SuggestedCategoryWeights[i].Category | string | Name of the category. |
Value.SuggestedCategoryWeights[i].Weight | decimal | A 0-100 weight of suggested importance for the speficied category. This is calculated from the data in the source document. A sum of all of the SuggestedCategoryWeights will equal 100. |
Value.AppliedCategoryWeights | object[] | An object[] containing the weights that were used for each category based on a combination of the data in the source document (or criteria) and any desired weights passed in the request. |
Value.AppliedCategoryWeights[i].Category | string | Name of the category. |
Value.AppliedCategoryWeights[i].Weight | decimal | A 0-100 weight of suggested importance for the speficied category. This is calculated from the data in the source document combined with any desired weights passed in the request. A sum of all of the AppliedCategoryWeights will equal 100. |
Value.CurrentCount | integer | The number of results that were returned. This number will never be greater than the Take in the request. |
Value.TotalCount | integer | The total number of match results found for the specified query. Only the top Take of these results are returned. |
Value.ElapsedMilliseconds | integer | The number of milliseconds the query took. |
Value.CreditsRemaining | decimal | The number of remaining credits is returned with every response. Please ensure that you set up monitoring of this value to ensure that you don't experience an outage by letting your credits reach 0. |
Search
POST /v9/searcher
Semantic search for resumes/jobs in certain indexes.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Request Body
{ "IndexIdsToSearchInto": [ "" ], "PaginationSettings": { "Skip": 0, "Take": 0 }, "Settings": { "PositionTitlesMustHaveAnExactMatch": false, "PositionTitlesIgnoreSingleWordVariations": false }, "FilterCriteria": { "RevisionDateRange": { "Minimum": "", "Maximum": "" }, "DocumentIds": [""], "CustomValueIds": [""], "LocationCriteria": { "Locations": [ { "CountryCode": "", "Region": "", "Municipality": "", "PostalCode": "", "GeoPoint": { "Latitude": 0, "Longitude": 0 }, } ], "Distance": 0, "GeocodeProvider": "", "DistanceUnit": "", "GeocodeProviderKey": "" }, "SearchExpression": "", "HasPatents": false, "HasSecurityCredentials": false, "SecurityCredentials": [""], "IsAuthor": false, "IsPublicSpeaker": false, "IsMilitary": false, "Educations": [ { "SchoolName": "", "DegreeMajor": "", "DegreeName": "", "DegreeType": "", "MinimumGPA": 0, } ], "Employers": [""], "MonthsExperience": { "Minimum": 0, "Maximum": 0 }, "DocumentLanguages": [""], "Skills": [ { "SkillName": "", "MonthsOfExperienceRange": { "Minimum": 0, "Maximum": 0 }, "IsCurrent": false } ] } }
Field | Data Type | Required | Description |
---|---|---|---|
IndexIdsToSearchInto | string[] | Yes | The ids of the indexes in which you want to find results. |
PaginationSettings.Skip | integer | No | The number of results to skip before selecting the return values. |
PaginationSettings.Take | integer | No | The number of results to return. |
Settings.PositionTitlesMustHaveAnExactMatch | bool | No | Set to true to turn off variation matches in job titles. |
Settings.PositionTitlesIgnoreSingleWordVariations | bool | No | Set to true to ignore single-word variations of multi-word job titles. |
FilterCriteria.RevisionDateRange.Minimum | string | No | The minimum allowed revision date for results in "YYYY-MM-DD" format. Default is 6 months before current date. |
FilterCriteria.RevisionDateRange.Maximum | string | No | The maximum allowed revision date for results in "YYYY-MM-DD" format. Default is current date. |
FilterCriteria.DocumentIds | string[] | No | Results must have one of the specified document ids. |
FilterCriteria.CustomValueIds | string[] | No | Results must have at least one of the specified custom value ids. |
FilterCriteria.LocationCriteria.Locations | object[] | No | Results must be found within a certain distance of one of the specified locations. |
FilterCriteria.LocationCriteria.Locations[i].CountryCode | string | No | The 2-letter ISO 3166-1 alpha-2 country code for the specified location. |
FilterCriteria.LocationCriteria.Locations[i].Region | string | No | The region (i.e. State for U.S. addresses) for the location. |
FilterCriteria.LocationCriteria.Locations[i].Municipality | string | No | The municipality (i.e. City for U.S. addresses) for the location. |
FilterCriteria.LocationCriteria.Locations[i].PostalCode | string | No | The postal code (or zip code) for the location. |
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Latitude | decimal | No | The latitude coordinate value. |
FilterCriteria.LocationCriteria.Locations[i].GeoPoint.Longitude | decimal | No | The longitude coordinate value. |
FilterCriteria.LocationCriteria.Distance | integer | No | The distance from Locations within which to find results. |
FilterCriteria.LocationCriteria.DistanceUnit | string | No | The units for the specified distance. One of: {"Miles", "Kilometers"} |
FilterCriteria.LocationCriteria.GeocodeProvider | string | Conditional | The provider to lookup latitude/longitude if they are not specified. One of: {"None", "Google", "Bing"} |
FilterCriteria.LocationCriteria.GeocodeProviderKey | string | Conditional | The key for the specified GeocodeProvider. If using Bing you must specify your own provider key. |
FilterCriteria.SearchExpression | string | No | Full-text boolean semantic expresion. For full details on the syntax and supported operations refer to the documentation |
FilterCriteria.HasPatents | bool | No | If true, results must have/require patent experience. |
FilterCriteria.HasSecurityCredentials | bool | No | If true, results must have/require security credentials. |
FilterCriteria.SecurityCredentials | string[] | No | Results must have/require at least one of the security credentials specified. |
FilterCriteria.IsAuthor | bool | No | If true, results must have/require experience as an author. |
FilterCriteria.IsPublicSpeaker | bool | No | If true, results must have/require public speaking experience. |
FilterCriteria.IsMilitary | bool | No | If true, results must have/require military experience. |
FilterCriteria.Educations | object[] | No | Results must have at least one of the specified educations. |
FilterCriteria.Educations[i].SchoolName | string | No | The name of a university/college/tech school. |
FilterCriteria.Educations[i].DegreeMajor | string | No | A degree major (eg. "Chemistry", "Architecture", etc.) |
FilterCriteria.Educations[i].DegreeName | string | No | A free-text field for the degree name. |
FilterCriteria.Educations[i].DegreeType | string | No |
A specific level of education. One of the following explicit values
as defined by HROpenStandards.org, in increasing order:
|
FilterCriteria.Educations[i].MinimumGPA | decimal | No | 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. |
FilterCriteria.Employers | string[] | No | Results must have at least one of the specified employers. |
FilterCriteria.MonthsExperience.Minimum | integer | No | Results must have/require at least the amount of total work experience specified. |
FilterCriteria.MonthsExperience.Maximum | integer | No | Results must have/require at MOST the amount of total work experience specified. |
FilterCriteria.DocumentLanguages | string[] | No | Results must be written in one of the specified languages. |
FilterCriteria.Skills | object[] | No | Results must have/require at least one of the specified skills. |
FilterCriteria.Skills[i].SkillName | string | No | The name of the skill. |
FilterCriteria.Skills[i].MonthsOfExperienceRange.Minimum | integer | No | The minimum amount of experience with this skill. |
FilterCriteria.Skills[i].MonthsOfExperienceRange.Maximum | integer | No | The maximum amount of experience with this skill. |
FilterCriteria.Skills[i].IsCurrent | bool | No | The skill must be a current skill. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { "Matches": [ { "Id": "", "IndexId": "" } ], "CurrentCount": 0, "TotalCount": 0, "ElapsedMilliseconds": 0, "CreditsRemaining": 0 } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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.Message | string | This message further describes the code providing additional detail. |
Value.Matches | object[] | An object[] containing the results for each match result. |
Value.Matches[i].Id | string | Id of the matched document in the index. |
Value.Matches[i].IndexId | string | Id of the index in which the match was found. |
Value.CurrentCount | integer | The number of results that were returned. This number will never be greater than the MaxRecords in the request. |
Value.TotalCount | integer | The total number of match results found for the specified query. Only the top MaxRecords of these results are returned. |
Value.ElapsedMilliseconds | integer | The number of milliseconds the query took. |
Value.CreditsRemaining | decimal | The number of remaining credits is returned with every response. Please ensure that you set up monitoring of this value to ensure that you don't experience an outage by letting your credits reach 0. |
Score a Set of Documents
POST /v9/scorer/bimetric
Score a parsed resume/job order to a group of resumes/job orders that aren't indexed. It's highly recommended to index all of your documents and leverage the speed and power of the AI Matching Engine and use one of the AI Match endpoints. This will also reduce your overall cost as the bimetric scoring is a higher charge per transaction.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. Supported values are
application/json and application/xml .
|
Accept | string | No |
Controls the media type of the response body. Supported values are
application/json and application/xml .
If not specified the response will default to JSON.
|
Request Body
{ "SourceDocument": { "Id": "", "FileText": "" }, "TargetDocuments": [ { "Id": "", "FileText": "" } ], "Settings": { "PositionTitlesMustHaveAnExactMatch": false, "PositionTitlesIgnoreSingleWordVariations": false } }
Field | Data Type | Required | Description |
---|---|---|---|
SourceDocument.Id | string | Yes | Id of the source document. This isn't used in any calculation, only to assist in displaying output. |
SourceDocument.FileText | string | Yes | Parsed JSON/XML from the Sovren Resume or Job Order Parser |
TargetDocuments[i].Id | string | Yes | Id of the target document. This isn't used in any calculation, only to assist in displaying output. |
TargetDocuments[i].FileText | string | Yes | Parsed JSON/XML from the Sovren Resume or Job Order Parser |
Settings.PositionTitlesMustHaveAnExactMatch | bool | No | Set to true to turn off variation matches in job titles. |
Settings.PositionTitlesIgnoreSingleWordVariations | bool | No | Set to true to ignore single-word variations of multi-word job titles. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { "Matches": [ { "Id": "", "WeightedScore": 0, "UnweightedCategoryScores": [ { "Category": "", "UnweightedScore": 0, "TermsFound": [ "" ] } ], "ReverseCompatibilityScore": 0 } ], "CreditsRemaining": 0, "SuggestedCategoryWeights": [ { "Category": "", "Weight": 0 } ] } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 InvalidParameter - A parameter was incorrectly specified AuthenticationError - An error occurred with the credentials provided |
Info.Message | string | This message further describes the code providing additional detail. |
Value.Matches | object[] | An object[] containing the results for each match that was executed. |
Value.Matches[i].Id | string | Name or Id of the target document as specified in the request. |
Value.Matches[i].WeightedScore | integer | An integer score from 0-100 representing how well the source document matched the specified target document. This calculation is the sum of the unweighted category weights multiplied by their respective suggested weight. |
Value.Matches[i].UnweightedCategoryScores | object[] | An object[] containing the scoring breakdown per category. |
Value.Matches[i].UnweightedCategoryScores[i].Category | string | Name of the category. |
Value.Matches[i].UnweightedCategoryScores[i].UnweightedScore | decimal | An unweighted score from 0-100. This is the percentage match of the specified category. This can be used in conjunction with the SuggestedCategoryWeights to calculate the WeightedScore. |
Value.Matches[i].UnweightedCategoryScores[i].TermsFound | string[] | A string[] of terms for the specified category that matched between the documents. |
Value.Matches[i].ReverseCompatibilityScore | integer | An integer score from 0-100 which represents how well the target document matched to the source 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. |
Value.CreditsRemaining | decimal | The number of remaining credits is returned with every response. Please ensure that you set up monitoring of this value to ensure that you don't experience an outage by letting your credits reach 0. |
Value.SuggestedCategoryWeights | object[] | An object[] containg our suggested weights for each category based on the source document. |
Value.SuggestedCategoryWeights[i].Category | string | Name of the category. |
Value.SuggestedCategoryWeights[i].Weight | decimal | A 0-100 weight of suggested importance for the speficied category. This is calculated from the data in the source document. A sum of all of the SuggestedCategoryWeights will equal 100. |
Index a Document
POST /v9/index/{indexId}/documents/{documentId}
Adds a single document to an index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id for the index where the document should be added. |
documentId | string | The id to assign to the new document. This is restricted to alphanumeric with dashes and underscores. |
Request Body
{ "ParsedDocument": "", "CustomIds": [ "" ] }
Field | Data Type | Required | Description |
---|---|---|---|
ParsedDocument | string | Yes | Parsed JSON/XML from the Sovren Resume or Job Order Parser. |
CustomIds | string[] | No | The custom ids you want the document to have. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": {} }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value | object | An empty object. |
Get a Document
GET /v9/index/{indexId}/documents/{documentId}
Retrieves a single document from an index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id for the index that contains the document. |
documentId | string | The id of the document to retrieve. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": "" }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value | string | The JSON document in string format. |
Check if a Document Exists
HEAD /v9/index/{indexId}/documents/{documentId}
Check id a document exists in an index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id for the index that contains the document. |
documentId | string | The id of the document to retrieve. |
Response
This api call has no reponse body, and utilizes the HttpStatusCode to specify success or failure.
Http Status Code | Description |
---|---|
200 | The document exists in the index |
404 | The document doesn't exist in the index |
500 | An unexpected error occured |
Update Custom Values
PATCH /v9/index/{indexId}/documents/{documentId}
Updates the custom value ids for a document.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id for the index that contains the document. |
documentId | string | The id of the document to update. |
Request Body
{ "CustomValues": [ "" ], "Method": "" }
Field | Data Type | Required | Description |
---|---|---|---|
CustomValues | string[] | Yes | The custom value ids to add/remove/overwrite in the document. |
Method | string | Yes | One of: "Delete", "Add", "Overwrite" |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": {} }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value | object | An empty object. |
Delete a Document
DELETE /v9/index/{indexId}/documents/{documentId}
Delete a single document from an index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id for the index that contains the document. |
documentId | string | The id of the document to delete. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value | object | An empty object. |
Index Multiple Document
POST /v9/index/{indexId}/documents
Adds multiple documents to an index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id for the index where the documents should be added. |
Request Body
[ { "DocumentId": "", "ParsedDocument": "", "CustomIds": [ "" ] } ]
Field | Data Type | Required | Description |
---|---|---|---|
DocumentId | string | Yes | The id of the current document. |
ParsedDocument | string | Yes | Parsed JSON/XML from the Sovren Resume or Job Order Parser. |
CustomIds | string[] | No | The custom ids you want the current document to have. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": [ { "DocumentId": "", "Code": "", "SubCode": "", "Message": "" } ] }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 SomeErrors – Some items in the bulk request failed MissingParameter - A 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value | object[] | An array of objects representing the individual document add responses. This is used to determine which documents failed in the event of an error. |
Value[i].DocumentId | string | Id of the specific document represented in the response |
Value[i].Code | string |
The following is a list of codes that can be returned by the service:
Success – Successful transaction Error – The specified document had an error during indexing |
Value[i].SubCode | string |
The following is a list of subcodes that can be returned by the service:
Success – Successful transaction InvalidParameter - A parameter was incorrectly specified UnhandledException - Unexpected error occurred |
Value[i].Message | string | This message further describes the code/subcode providing additional detail. |
Delete Multiple Documents
DELETE /v9/index/{indexId}/documents
Delete multiple documents from an index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id for the index that contains the documents. |
Request Body
[""]
Field | Data Type | Required | Description |
---|---|---|---|
Body | string[] | Yes | Each item in the array is the id of a document to delete from the index. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value | object | An empty object. |
Create an Index
POST /v9/index/{indexId}
Creates an index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id to assign to the new index. This is restricted to alphanumeric with dashes and underscores. |
Request Body
{ "IndexType": "" }
Field | Data Type | Required | Description |
---|---|---|---|
IndexType | string | Yes | The type of the index. One of: {"Resume", "Job"} |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": {} }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 |
Info.Message | string | This message further describes the code providing additional detail. |
Value | object | An empty object. |
Get an Index
GET /v9/index/{indexId}
Retrieves information about a single index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id of the index. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { "OwnerId": "", "Name": "", "IndexType": "" } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value.OwnerId | string | The account id of the index owner. |
Value.Name | string | The name of the index. |
Value.IndexType | string | The type of the index. One of: {"Resume", "Job"} |
Delete an Index
DELETE /v9/index/{indexId}
Delete an index.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Path Parameters
Parameter | Data Type | Description |
---|---|---|
indexId | string | The id of the index to delete. |
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": { } }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value | object | An empty object. |
Get All Indexes
GET /v9/index
Retrieves information about all the indexes associated with your account.
Notes
- You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Response Body
{ "Info": { "Code": "", "Message": "" }, "Value": [ { "OwnerId": "", "Name": "", "IndexType": "" } ] }
Field | Data Type | Description |
---|---|---|
Info.Code | string |
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 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 - Data with the specified name wasn't found |
Info.Message | string | This message further describes the code providing additional detail. |
Value[i].OwnerId | string | The account id of the index owner. |
Value[i].Name | string | The name of the index. |
Value[i].IndexType | string | The type of the index. One of: {"Resume", "Job"} |
Generate the Matching UI
POST /ui/v9/matcher/criteria
POST /ui/v9/matcher/documents
POST /ui/v9/matcher/indexes/{indexId}/documents/{documentId}
POST /ui/v9/searcher
POST /ui/v9/scorer/bimetric
Generate an HTML user interface for matching/searching that can be consumed in your client application.
Notes
- Pagination settings in the SaasRequest such as Take or Skip will be ignored in the Matching UI results.
Request Headers
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes |
Indicates the media type of the incoming request body. The only supported value for AIM endpoints is
application/json .
|
Accept | string | No |
Controls the media type of the response body. The only supported value for AIM endpoints is
application/json .
|
Request Body
{ "UIOptions": { "Username": "", "ShowMatchCriteria": true, "ShowFilterCriteria": true, "ExecuteImmediately": false, "ShowBanner": true, "ShowWeights": true, "ShowDetailsButton": true, "ShowFindSimilar": true, "ShowWebSourcing": true, "ShowJobBoards": true, "ShowSavedSearches": true }, "SaasRequest": { "IndexIdsToSearchInto": [ "" ], //... }, "ParseOptions" : { "Configuration": "", "SkillsData": [ "" ], "NormalizerData": "" }, "GeocodeOptions": { //... } }
Field | Data Type | Required | Description |
---|---|---|---|
UIOptions | object | No | Object representing various options for generating the UI. |
UIOptions.Username | string | No | The username of the current user. |
UIOptions.ShowMatchCriteria | boolean | No | Allow the user to see/modify the match criteria. Only used when matching by criteria. |
UIOptions.ShowFilterCriteria | boolean | No | Allow the user to see/modify the filter criteria. |
UIOptions.ExecuteImmediately | boolean | No | Execute the query as soon as the page loads. |
UIOptions.ShowBanner | boolean | No | Show the banner containing your account logo inside the matching UI. |
UIOptions.ShowWeights | boolean | No | Allow the user to see/modify the category weights. |
UIOptions.ShowDetailsButton | boolean | No | Show a button that opens the 'details' popup containing detailed job/resume info. |
UIOptions.ShowFindSimilar | boolean | No | Adds a button in the Actions menu that matches other jobs/resumes similar to the current one. |
UIOptions.ShowWebSourcing | boolean | No | Include Sovren custom web sourcing in search/match results. Cannot be used for bimetric scoring. |
UIOptions.ShowJobBoards | boolean | No | Include job boards in search/match results. Cannot be used for bimetric scoring. Must add credentials at My Sovren Portal |
UIOptions.ShowSavedSearches | boolean | No | Allow the user to save custom searches, upload a document to generate match criteria, or select from premade criteria templates. |
SaasRequest | object | Yes | The SaaS request that defines the match/search. See the AI Match and AI Search endpoints for details. |
SaasRequest.IndexIdsToSearchInto | string[] | Yes | The ids of the indexes in which you want to find results. This is the only required value in the SaasRequest. |
SaasRequest.* | any | No | All of the parameters that are supported in the normal AI Match and AI Search requests are supported, apart from pagination settings as noted above. |
ParseOptions | object | No | Object representing parsing options to use when parsing resumes from external sources, such as job boards and Sovren custom web sourcing. |
ParseOptions.ConfigurationString | string | No | Optional parser configuration string to be used for parsing. If not specified, the default parser configuration will be used. For more information regarding the parser configuration string and assistance generating one, refer to the Parser Configuration Documentation. |
ParseOptions.SkillsData | string[] | No | String[] of your custom skills list names and the Sovren "builtin" skills list. If no list is provided the Sovren builtin skills list will be used. The parser automatically detects language and looks for a corresponding skills list in that language, if no match is found this list is ignored. |
ParseOptions.NormalizerData | string | No | Name of your custom normalization data file. If no list is provided the Sovren builtin skills list will be used (english only). When using custom normalization files the language to be used is determined by the Parser (the default fall back language is English if the Parser cannot find a match). |
GeocodeOptions | object | No | All of the parameters that are supported in the normal parsing geocode options requests are supported. See Parse a Resume for more details. |
Response Body
{ "url": "", "expires_in": 0 }
Field | Data Type | Description |
---|---|---|
url | string | The endpoint to hit to get the generated Matching UI. The first request to this endpoint will automatically authenticate the user. Subsequent requests (who are not already authenticated) will require a login. This url will be valid for at least 24 hours. |
expires_in | integer | The number of seconds until the url auto-authentication expires. |