Documentation Release Notes Downloads FAQs

Match by Document

POST /v9/matcher/documents

Match a parsed resume/job to resumes/jobs in certain indexes.

Notes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.