Sovren | REST API

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: "specialeducation" "someHighSchoolOrEquivalent" "ged" "secondary" "highSchoolOrEquivalent" "certification" "vocational" "someCollege" "HND_HNC_OrEquivalent" "associates" "international" "bachelors" "somePostgraduate" "masters" "intermediategraduate" "professional" "postprofessional" "doctorate" "postdoctorate"
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: "specialeducation" "someHighSchoolOrEquivalent" "ged" "secondary" "highSchoolOrEquivalent" "certification" "vocational" "someCollege" "HND_HNC_OrEquivalent" "associates" "international" "bachelors" "somePostgraduate" "masters" "intermediategraduate" "professional" "postprofessional" "doctorate" "postdoctorate"
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: NONE EXECUTIVE ADMIN ACCOUNTING OPERATIONS FINANCIAL MARKETING BUSINESS_DEV IT GENERAL LEARNING
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: "specialeducation" "someHighSchoolOrEquivalent" "ged" "secondary" "highSchoolOrEquivalent" "certification" "vocational" "someCollege" "HND_HNC_OrEquivalent" "associates" "international" "bachelors" "somePostgraduate" "masters" "intermediategraduate" "professional" "postprofessional" "doctorate" "postdoctorate"
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: "specialeducation" "someHighSchoolOrEquivalent" "ged" "secondary" "highSchoolOrEquivalent" "certification" "vocational" "someCollege" "HND_HNC_OrEquivalent" "associates" "international" "bachelors" "somePostgraduate" "masters" "intermediategraduate" "professional" "postprofessional" "doctorate" "postdoctorate"
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.