Sovren | REST API

Sovren REST API

Legacy SOAP documentation can be found here. Deprecated

Getting Started

Start by reading the Acceptable Use Policy. There are many items in the Acceptable Use Policy that will require your programming expertise in order to be in compliance.

Sovren's products and services contain open source software developed by third parties. A list of this software, including licensing and links to source code, can be found in our Open Source Disclosure.

Here we have a few code samples to get you up and running quickly:

//go to http://docs.sovren.com/Downloads/v9/Schemas/ResumeSchema.zip to download necessary Resume.cs file

string filePath = "resume.docx";
byte[] fileBytes = File.ReadAllBytes(filePath); 
dynamic data = new 
{ 
    DocumentAsBase64String = Convert.ToBase64String(fileBytes),
    RevisionDate = File.GetLastWriteTime(filePath).ToString("yyyy-MM-dd")
    //other options here (see http://docs.sovren.com/API/Rest/Parsing)
};

//use https://eu-rest.resumeparsing.com/v9/parser/resume if your account is in the EU data center
string url = "https://rest.resumeparsing.com/v9/parser/resume"; 
string json = JsonSerializer.Serialize(data); 

string strResume = "";

using (WebClient client = new WebClient())
{
    client.Headers[HttpRequestHeader.ContentType] = "application/json";
    client.Headers[HttpRequestHeader.Accept] = "application/json";
    client.Headers["Sovren-AccountId"] = "12345678";
    client.Headers["Sovren-ServiceKey"] = "eumey7feY5zjeWZW397Jks6PBj2NRKSH";
    //This line is important to preserve utf8 characters
    client.Encoding = System.Text.Encoding.UTF8;

    string result = client.UploadString(url, "POST", json);
    //for response properties and types, see http://docs.sovren.com/API/Rest/Parsing
    strResume = JsonSerializer.Deserialize<dynamic>(result).GetProperty("Value").GetProperty("ParsedDocument").ToString();
}

Sovren.External.Resume resume = null;
//in order to use the XSD-generated class here, we must go from JSON to XML first
XmlDocument node = JsonConvert.DeserializeXmlNode(strResume);
XmlSerializer serializer = new XmlSerializer(typeof(Sovren.External.Resume));
using (StringReader sr = new StringReader(node.InnerXml))
{
    resume = serializer.Deserialize(sr) as Sovren.External.Resume;
}

Console.WriteLine(resume.StructuredXMLResume.ContactInfo.PersonName.FormattedName);

//https://developer.mozilla.org/en-US/docs/Using_files_from_web_applications
var file = $("#input").files[0];
var revisionDate = (new Date(file.lastModified)).toISOString().substring(0, 10);
var reader = new FileReader();

reader.onload = function (event) {
    //the Base64 library can be found at http://docs.sovren.com/Downloads/v9/Libs/base64.zip
    var base64Text = Base64.encodeArray(event.target.result);

    var data = {
        "DocumentAsBase64String": base64Text,
        "RevisionDate": revisionDate
        //other options here (see http://docs.sovren.com/API/Rest/Parsing)
    };

    //use https://eu-rest.resumeparsing.com/v9/parser/resume if your account is in the EU data center
    //NOTE: this is shown for demonstration purposes only, you should never embed your credentials
    // in javascript that is going to be distributed to end users. Instead, your javascript should
    // call a back-end service which then makes the POST to Sovren's API
    $.ajax({
        "url": "https://rest.resumeparsing.com/v9/parser/resume",
        "method": "POST",
        "crossDomain": true,
        "headers": {
            "Accept": "application/json",
            "Content-Type": "application/json",
            "Sovren-AccountId": "12345678",
            "Sovren-ServiceKey": "eumey7feY5zjeWZW397Jks6PBj2NRKSH"
        },
        "data": JSON.stringify(data)
    });
}

// when the file is read it triggers the onload event above.
reader.readAsArrayBuffer(file);

import base64
import requests #this module will need to be installed
import json
import os.path
import datetime

base64str = ''
filePath = 'resume.docx'
#open the file, encode the bytes to base64, then decode that to a UTF-8 string
with open(filePath, 'rb') as f:
    base64str = base64.b64encode(f.read()).decode('UTF-8')

epochSeconds = os.path.getmtime(filePath)
revisionDate = datetime.datetime.fromtimestamp(epochSeconds).strftime("%Y-%m-%d") 

#use https://eu-rest.resumeparsing.com/v9/parser/resume if your account is in the EU data center
url = "https://rest.resumeparsing.com/v9/parser/resume"
payload = {
    'DocumentAsBase64String': base64str,
    'RevisionDate': revisionDate
    #other options here (see http://docs.sovren.com/API/Rest/Parsing)
}

headers = {
    'accept': "application/json",
    'content-type': "application/json",
    'sovren-accountid': "12345678",
    'sovren-servicekey': "eumey7feY5zjeWZW397Jks6PBj2NRKSH",
}

#make the request, NOTE: the payload must be serialized to a json string
response = requests.request("POST", url, data=json.dumps(payload), headers=headers)
responseJson = json.loads(response.content)

#load ParsedDocument string into json object
parsedDoc = json.loads(responseJson['Value']['ParsedDocument'])

#access the ParsedDocument properties with simple JSON syntax:
print(parsedDoc['Resume']['StructuredXMLResume']['ContactInfo'])
#for response properties and types, see http://docs.sovren.com/API/Rest/Parsing

require 'uri'
require 'net/http'
require 'net/https'
require 'base64'
require 'json'

file_path = 'resume.docx'
file_data = IO.binread(file_path)
revision_date = File.mtime(file_path).to_s[0,10]

# Encode the bytes to base64
base_64_file = Base64.encode64(file_data)
data = {
  "DocumentAsBase64String" => base_64_file,
  "RevisionDate" => revision_date
   #other options here (see http://docs.sovren.com/API/Rest/Parsing)
}.to_json

#use https://eu-rest.resumeparsing.com/v9/parser/resume if your account is in the EU data center
uri = URI.parse("https://rest.resumeparsing.com/v9/parser/resume")
https = Net::HTTP.new(uri.host,uri.port)
https.use_ssl = true

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Sovren-AccountId' => '12345678', # use your account id here
  'Sovren-ServiceKey' =>  'eumey7feY5zjeWZW397Jks6PBj2NRKSH', # use your service key here
}

req = Net::HTTP::Post.new(uri.path, initheader = headers)
req.body = data

res = https.request(req)

# Parse the response body into an object
respObj = JSON.parse(res.body)

# Parse the ParsedDocument string into an object (for response properties and types, see http://docs.sovren.com/API/Rest/Parsing)
parsedDoc = JSON.parse(respObj["Value"]["ParsedDocument"])

# Access properties such as the GivenName and TextResume
givenName = parsedDoc["Resume"]["StructuredXMLResume"]["ContactInfo"]["PersonName"]["GivenName"]
resumeText = parsedDoc["Resume"]["NonXMLResume"]["TextResume"]

//import java.io.*;
//import java.nio.file.*;
//import java.net.*;
//import java.util.*;

// Specify filename and compute path
Path filePath = Paths.get("resume.docx");

// Open file, encode contents to base64, then decode to UTF-8
byte[] encoded = Base64.getEncoder().encode(Files.readAllBytes(filePath));
String base64Str = new String(encoded, "UTF-8");

String revisionDate = Files.getLastModifiedTime(filePath).toString().substring(0, 10);
        
// Create connection object, based on the given url-name
//use https://eu-rest.resumeparsing.com/v9/parser/resume if your account is in the EU data center
URL url = new URL("https://rest.resumeparsing.com/v9/parser/resume");
HttpURLConnection connection = (HttpURLConnection)url.openConnection();

// Properties in order to ensure succesful POST-request
connection.setUseCaches(false);
connection.setDoInput(true);
connection.setDoOutput(true);

// Specify request-method and headers
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/json");
connection.setRequestProperty("accept", "application/json");

// Specify your credentials
connection.setRequestProperty("Sovren-AccountId", "12345678");
connection.setRequestProperty("Sovren-ServiceKey", "eumey7feY5zjeWZW397Jks6PBj2NRKSH");

// Construct payload in JSON-format
// (This is a very primitive way to do so, as not to have any external dependencies 
//  feel free to use your preferred json-library)
String payload = "{ \"DocumentAsBase64String\": \"" + base64Str + "\", \"RevisionDate\": \"" + revisionDate + "\" }";
//other options here (see http://docs.sovren.com/API/Rest/Parsing)

// Send payload
BufferedWriter bw = new BufferedWriter(
    new OutputStreamWriter(new DataOutputStream(connection.getOutputStream()), "UTF-8"));
bw.write(payload);
bw.flush();
bw.close();

// Read response
int responseCode = connection.getResponseCode();
BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream(), "UTF-8"));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();

// (Optional) Output response details
System.out.println(responseCode);
System.out.println(response.toString());
//for response properties and types, see http://docs.sovren.com/API/Rest/Parsing

//If your PHP installation doesn't have an up-to-date CA root certificate bundle, download the one at the curl website and save it on your server:
//http://curl.haxx.se/docs/caextract.html
//Then set a path to it in your php.ini file, e.g. on Windows:
//curl.cainfo=c:\php\cacert.pem
        
// open the file
$filepath = "resume.docx";
$handle = fopen($filepath, "r");
$contents = fread($handle, filesize($filepath));
fclose($handle);

$revisionDate = date("Y-m-d", filemtime($filepath));

//encode to base64
$base64str = base64_encode($contents);
$data = ["DocumentAsBase64String" => $base64str, "RevisionDate" => $revisionDate];
//other options here (see http://docs.sovren.com/API/Rest/Parsing)

//use https://eu-rest.resumeparsing.com/v9/parser/resume if your account is in the EU data center
$url = "https://rest.resumeparsing.com/v9/parser/resume";
        
//setup curl to make the REST call, you can use an external library
//such as Guzzle if you prefer: http://guzzle.readthedocs.io
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
        
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        
$headers = [
    "accept: application/json",
    "content-type: application/json; charset=utf-8",
    "sovren-accountid: 12345678",
    "sovren-servicekey: eumey7feY5zjeWZW397Jks6PBj2NRKSH"
];
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
        
$result = curl_exec($curl);
curl_close($curl);

echo $result;//this is a string, you can now use json_decode if you like
//for response properties and types, see http://docs.sovren.com/API/Rest/Parsing

const http = require('https');
const fs = require('fs');

var filePath = "resume.docx";
var buffer = fs.readFileSync(filePath);
var base64Doc = buffer.toString('base64');

var revisionDate = (new Date(fs.statSync(filePath).mtimeMs)).toISOString().substring(0, 10);

//other options here (see http://docs.sovren.com/API/Rest/Parsing)
var postData = JSON.stringify({
    'DocumentAsBase64String': base64Doc,
    'RevisionDate': revisionDate
});

//use https://eu-rest.resumeparsing.com/v9/parser/resume if your account is in the EU data center
var options = {
    host: 'rest.resumeparsing.com',
    protocol: 'https:',
    path: '/v9/parser/resume',
    method: 'POST',
    headers: {
        'Sovren-AccountId': '12345678',
        'Sovren-ServiceKey': 'eumey7feY5zjeWZW397Jks6PBj2NRKSH',
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Content-Length': postData.length
  }
};

var request = http.request(options, function (response) {
    console.log(`STATUS: ${response.statusCode}`);
    response.setEncoding('utf8');
    
    var responseAsString = '';
    
    response.on('data', (chunk) => {
        responseAsString += chunk;
    });
    
    response.on('end', () => {
        var responseAsJson = JSON.parse(responseAsString);
        console.log(responseAsJson.Info);
        
        var parsedDocString = responseAsJson.Value.ParsedDocument;
        console.log(parsedDocString);
        
        var parsedDocJson = JSON.parse(parsedDocString);		
        //now you can consume the parsedDocJson
    });
});

request.write(postData);
request.end();

All above code samples are provided without warranty and are not necessarily indicative of best practices.

Transaction Cost

Endpoint	Cost
POST /v9/parser/resume	1 credit (2 credits with matching enabled, additional credits can be consumed when geocoding is enabled that follow the same structure as the `POST /geocoder` endpoint)
POST /v9/parser/joborder	1 credit (2 credits with matching enabled, additional credits can be consumed when geocoding is enabled that follow the same structure as the `POST /geocoder` endpoint)
POST /v9/scorer/bimetric	1 credit + number of target documents * 0.1
POST /v9/matcher/*	Free when initiated by a human end-user for a single transaction. (Additional credits can be consumed when geocoding is enabled that follow the same structure as the `POST /geocoder` endpoint). When this method is called by anything other than a human end-user, this endpoint may be subject to an additional 1 credit surcharge as per the Acceptable Use Policy.
POST /v9/searcher	Free when initiated by a human end-user for a single transaction. (Additional credits can be consumed when geocoding is enabled that follow the same structure as the `POST /geocoder` endpoint). When this method is called by anything other than a human end-user, this endpoint may be subject to an additional 1 credit surcharge as per the Acceptable Use Policy.
POST /v9/normalizer/resume	0.1 credits
POST /v9/geocoder	0.5 credits (if you use your own provider key, or specify your own latitude and longitude the transaction is free. If you use geocoding in parsing/searching/matching the same cost is applied to those transactions.)
POST /v9/geocodeAndIndex	0.5 credits (if you use your own provider key, or specify your own latitude and longitude the transaction is free).
POST /v9/apply/session	1 credit (2 credits with matching enabled)
GET /v9/index/{indexId}/count	1 credit

Note: Credit cost is increased 15% when Sovren Apply or Sovren Sourcing are enabled (30% increase when both are enabled).

Note: Additional costs may be incurred when using deprecated versions as per the Terms of Service.

Endpoints

Notes

Our REST API is also documented using Swagger. Follow the links below for the appropriate data center to access an HTML page where you can make sample requests.

	US Data Center	EU Data Center
HTTPS	https://rest.resumeparsing.com/v9/	https://eu-rest.resumeparsing.com/v9/

Authentication

Our REST API handles authentication via the Sovren-AccountId and Sovren-ServiceKey headers. These keys were generated during account creation and send to the contacts listed on the account. If authentication fails we return a 401 Unathorized HTTP Status Code.

The most common causes for unauthorized exceptions are:

Not including the headers in the request
Making requests to the wrong data center. If you have questions about which data center your account is setup for contact support@sovren.com

If you recieve a 403 Forbidden Access exception, please confirm that you are using https. We have deprecated the use of unsecured http connections in this verison.

Versioning

We continuously deploy bug fixes and new features to our API. We limit breaking changes to new versions deployed to new urls unless the change is to fix an error in the output. In the top right of our documentation site you can change the API version of the documentation.

Release notes can be found here.

When integrating to our API, make sure that all of your API calls use same version. When upgrading to a new version it's crucial to upgrade all api calls to the new version at the same time. NEVER use multiple versions in your integration.

There are three different statuses for API versions, and they are defined as follows:

Suggested - this is the version we suggest that you use. It will continue to receive new features, and bug fixes as they are identified.
Supported - do not integrate against this version, and if you're currently utilizing it plan your upgrade to the suggested version before this version is deprecated. Supported versions will continue to receive critical bug fixes, but not new features or accuracy improvements.
Deprecated - do not use this version. If you're integrated to a deprecated version you should plan your upgrade to the suggested version. Deprecated versions do not receive any bug fixes or new features. Deprecated versions may incur higher use of credits.

API Version	Status	Notes
Version 9	Suggested	This is the latest and most accurate version. If you're not already using this version please make plans to upgrade as soon as possible. Full release notes can be found here.
Version 8	Deprecated and do not integrate to this (6/26/2018)	Do not integrate to v8. If you are using v8, click here to view the upgrade path.
Version 7.5	Deprecated (6/26/2018)	If you're still using the version 7.5 of the API we recommend upgrading straight to version 9. The upgrade path can be found here.

HTTP Status Codes

Our API uses conventional HTTP status codes to describe the overall status of the transaction. The specific code we return are detailed below and mapped to the Info.Code values we return for every transaction:

HTTP Status Code	Info.Code	Description
200 - OK	Success, WarningsFoundDuringParsing, PossibleTruncationFromTimeout, SomeErrors	The transaction was successful
400 - Bad Request	MissingParameter, InvalidParameter, InsufficientData, DataNotFound, CoordinatesNotFound, ConstraintError	Unable to process request
401 - Unauthorized	AuthenticationError, Unauthorized	The AccountId and/or ServiceKey were invalid
403 - Forbidden	N/A	The request was made using http instead of https.
404 - Not Found	DataNotFound	The requested asset wasn't found.
409 - Conflict	DuplicateAsset	The request could not be completed due to a conflict with the current state of the target resource.
422 - Unprocessable Entity	ConversionException	The request made was syntactically correct, but the provided document was unable to be converted to text.
429 - Too Many Requests	TooManyRequests	Your submission has been rejected without being processed because you were exceeding the allowable batch parsing transaction concurrency limit per the AUP. You have been charged for submitting the transaction. It is your responsibility to resubmit this transaction after you correct the process which caused the concurrency problem.
500 - Internal Server Error	UnhandledException	An unexpected issue occurred (these are extremely rare).

Parse a Resume

POST /v9/parser/resume

Parse a single Resume/CV.

Notes

You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
This service is designed to parse resumes/CVs. It assumes that all files passed to it are resumes/CVs. It does not attempt to detect whether a document is a resume/CV or not. It should not be used to try to extract information from other types of documents.
This service supports all commercially viable document formats used for text documents (image formats are not supported). The service does not support parsing of image files (such as TIFF, JPG) or scanned images within supported document file formats. Always send the original file, not the result of copy/paste, not a conversion by some other software, not a scanned image, and not a version marked up with recruiter notes or other non-resume information. Be aware that if you pass garbage into the service, then you are likely to get garbage out. The best results are always obtained by parsing the original resume/CV file.
If you are running batch transactions (i.e. iterating through files in a folder), make sure that you do not try to reparse a file if you get an exception back from the service since you will get the same result each time and credits will be deducted from your account.
Batch transactions must adhere to our Acceptable Use Policy.
Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

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 is `application/json`.

Request Body

DocumentAsBase64String required string

A Base64 encoded string of the resume file bytes. This should use the standard 'base64' encoding as defined in RFC 4648 Section 4 (not the 'base64url' variant). .NET users can use the Convert.ToBase64String(byte[]) method.

RevisionDate required string

Mandatory date, in YYYY-MM-DD format, so that the Parser knows how to interpret dates in the document that are expressed as "current" or "as of" or similar. To find out why this is so important and how to calculate/find it, read here. Failing to pass a RevisionDate, or passing RevisionDates that are clearly improbable, may result in rejection of data and/or additional charges, and will utterly decimate the usefulness of AI Matching. Use of the RevisionDate field is subject to the Acceptable Use Policy.

OutputHtml optional bool

When true, the original file is converted to HTML and stored in the Html property.

OutputRtf optional bool

When true, the original file is converted to RTF and stored in the Rtf property.

OutputPdf optional bool

When true, the original file is converted to PDF and stored in the Pdf property as a byte array.

OutputCandidateImage optional bool

When true, if the document contains inline images, the image that is most likely to be a photo of the candidate is returned as a byte array.

Configuration optional string

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.

SkillsData optional string[]

Unavailable except in special cases. Please reach out to support@sovren.com. 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.

NormalizerData optional string

Unavailable except in special cases. Please reach out to support@sovren.com. 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 optional object

Get or insert geocode coordinate values (latitude/longitude) during the parse transaction.

Show Child Properties

GeocodeOptions.IncludeGeocoding optional bool

When set to true we will automatically geocode the address that is parsed out leveraging an api call to our /geocode endpoint, and thus will be charged accordingly. This parameter defaults to false.

GeocodeOptions.Provider optional string

The Provider you wish to use to geocode the postal address (current options are "Google" or "Bing"). If not specified, we will default to Google.
If passing a ProviderKey, this field is required.

GeocodeOptions.ProviderKey optional string

The Provider Key for the specified Provider. If using Bing you must specify your own provider key.

GeocodeOptions.PostalAddress optional object

The postal address you wish to geocode. For best results, specify as many of the PostalAddress fields as possible. If provided, this address will be used to get the geocode coordinates instead of the address included in the ParsedDocument (if present), however, the address in the ParsedDocument will not be modified.

Show Child Properties

GeocodeOptions.PostalAddress.CountryCode optional string

The ISO 3166-1 alpha-2 code indicating the country for the postal address.

GeocodeOptions.PostalAddress.PostalCode optional string

The postal code (or zip code) for the postal address

GeocodeOptions.PostalAddress.Region optional string

The region (i.e. State for U.S. addresses) for the postal address.

GeocodeOptions.PostalAddress.Municipality optional string

The municipality (i.e. City for U.S. addresses) for the postal address

GeocodeOptions.PostalAddress.AddressLine optional string

The address line (i.e. Street address for U.S. address) for the postal address

GeocodeOptions.GeoCoordinates optional object

The geographic coordinates (latitude/longitude) for your postal address. Use this if you already have latitude/longitude coordinates and simply wish to add them to your parsed document. If provided, these values will be inserted into your ParsedDocument and the address included in the ParsedDocument (if present), will not be modified.

Show Child Properties

IndexingOptions optional object

When your account is enabled for Matching/Searching you can automatically index documents during the parse transactions.

Show Child Properties

{
  "DocumentAsBase64String": "",
  "RevisionDate": "",
  "OutputHtml": false,
  "OutputRtf": false,
  "OutputPdf": false,
  "OutputCandidateImage": false,
  "Configuration": "",
  "SkillsData": [
    ""
  ],
  "NormalizerData": "",
  "GeocodeOptions": {
    "IncludeGeocoding": false,
    "Provider": "",
    "ProviderKey": "",
    "PostalAddress": {
      "CountryCode": "",
      "PostalCode": "",
      "Region": "",
      "Municipality": "",
      "AddressLine": ""
    },
    "GeoCoordinates": {
      "Latitude": 0,
      "Longitude": 0
    }
  },
  "IndexingOptions": {
    "IndexId": "",
    "DocumentId": "",
    "CustomIds": [
      ""
    ]
  }
}

Response Body

Info object

Explains the outcome of the transaction.

Show Child Properties

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

WarningsFoundDuringParsing - A successful transaction that contains warnings in the parsed document result

PossibleTruncationFromTimeout - The timeout occurred before the document was finished parsing which can result in truncation

ConversionException - There was an issue converting the document

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 object

Contains response data for the transaction.

Show Child Properties

Value.ParsedDocument string

The parser results in JSON string format.

Value.ScrubbedParsedDocument string

This property is the Value.ParsedDocument with all of the Personally Identifiable Information (PII) fields such as first name, last name, email addresses, phone numbers, etc. scrubbed out.

Value.FileType string

The input file type that was submitted through the ParseResumeRequest.

Value.Text string

The plain text of the parsed resume.

Value.TextCode string

A response code indicating the status of the conversion to text. See Document Conversion Result Codes for a complete list.

Value.Html string

HTML version of the input file, if OutputHtml was set to true.

Value.HtmlCode string

A response code indicating the status of the conversion to HTML. See Document Conversion Result Codes for a complete list.

Value.Rtf string

RTF version of the input file, if OutputRtf was set to true.

Value.RtfCode string

A response code indicating the status of the conversion to RTF. See Document Conversion Result Codes for a complete list.

Value.Pdf string

The base 64 encoded string of the PDF version of the input file, if OutputPdf was set to true.

Value.PdfCode string

A response code indicating the status of the conversion to PDF. See Document Conversion Result Codes for a complete list.

Value.CandidateImage string

If a candidate photo was extracted, it will be output in this field as a base 64 encoded string of the byte array.

Value.CandidateImageExtension string

If a candidate photo was extracted, the appropriate file extension for the photo will be output for this field (e.g. ".png").

Value.FileExtension string

The recommended file extension of the input file.

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.GeocodeResponse object

If Request.GeocodeOptions.IncludeGeocoding is set to true (thus geocoding is executed), this object will be populated with a response.

Show Child Properties

Value.IndexingResponse object

If Request.IndexingOptions contains any specified parameters, this object will be populated with a response.

Show Child Properties

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "ParsedDocument": "",
    "ScrubbedParsedDocument": "",
    "FileType": "",
    "Text": "",
    "TextCode": "",
    "Html": "",
    "HtmlCode": "",
    "Rtf": "",
    "RtfCode": "",
    "Pdf": "",
    "PdfCode": "",
    "CandidateImage": "",
    "CandidateImageExtension": "",
    "FileExtension": "",
    "CreditsRemaining": 0,
    "GeocodeResponse": {
      "Code": "",
      "Message": ""
    },
    "IndexingResponse": {
      "Code": "",
      "Message": ""
    }
  }
}

Parse a Job Order

POST /v9/parser/joborder

Parse a single Job Order.

Notes

You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
This service is designed to parse job orders. It assumes that all files passed to it are job orders. It does not attempt to detect whether a document is a job order or not. It should not be used to try to extract information from other types of documents.
This service supports all commercially viable document formats used for text documents (image formats are not supported). The service does not support parsing of image files (such as TIFF, JPG) or scanned images within supported document file formats. Always send the original file, not the result of copy/paste, not a conversion by some other software, not a scanned image, and not a version marked up with recruiter notes or other non-job order information. Be aware that if you pass garbage into the service, then you are likely to get garbage out. The best results are always obtained by parsing the original job order file.
If you are running batch transactions (i.e. iterating through files in a folder), make sure that you do not try to reparse a file if you get an exception back from the service since you will get the same result each time and credits will be deducted from your account.
Batch transactions must adhere to our Acceptable Use Policy.
Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

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 is `application/json`.

Request Body

DocumentAsBase64String required string

A Base64 encoded string of the job order file bytes. This should use the standard 'base64' encoding as defined in RFC 4648 Section 4 (not the 'base64url' variant). .NET users can use the Convert.ToBase64String(byte[]) method.

RevisionDate required string

Mandatory date, in YYYY-MM-DD format, representing the "current" or "as of" date used during parsing. This is useful when parsing older documents. Read more about this here.

OutputHtml optional boolean

When true, the original file is converted to HTML and stored in the Html property.

OutputRtf optional boolean

When true, the original file is converted to RTF and stored in the Rtf property.

OutputPdf optional boolean

When true, the original file is converted to PDF and stored in the Pdf property as a byte array.

Configuration optional object

Options that influence parser behavior.

Show Child Properties

Configuration.CountryCode optional string

A 2-letter ISO 3166 code (or comma-delimited list of such codes) indicating the country to be assumed in cases where the location cannot be automatically detected. If multiple codes are specified, the first one is given the highest priority.

Configuration.Language optional string

An ISO 639-1 two letter language code indicating the language to be assumed in cases where the language cannot be automatically detected.

Configuration.KnownType optional string

Optionally specify a known type to enable special processing. Possible values include: Indeed, Stride, JOB_SUBMISSION_REPLY_TO_CANDIDATE

Configuration.IncludeRecruitingTerms optional boolean

Recruiting terms in skills and job titles are ignored by default, because these terms often appear in job orders that are unrelated to recruiting. If this job order is for a recruiting or human resources position, then set this to true.

Configuration.IncludeSupplementalText optional boolean

The parser defaults to extracting data from only the text that precedes the place in job orders where they transition from describing the job itself to describing the company, hiring policies, background checks, benefits, etc. This division of text normally works well, but in some job orders it can occur in the wrong place. Set this to true to allow the parser to extract data from all of the text.

Configuration.PreferShorterJobTitles optional boolean

The parser defaults to returning full job titles. Setting this option to true will shorten job titles by excluding trailing phrases that do not include job words, so that "Vice President" would be returned instead of "Vice President, Information Systems".

SkillsData optional string[]

NormalizerData optional string

Will be used in a future release.

GeocodeOptions optional object

Get or insert geocode coordinate values (latitude/longitude) during the parse transaction.

Show Child Properties

GeocodeOptions.IncludeGeocoding optional bool

GeocodeOptions.Provider optional string

The Provider you wish to use to geocode the postal address (current options are "Google" or "Bing"). If not specified, we will default to Google.
If passing a ProviderKey, this field is required.

GeocodeOptions.ProviderKey optional string

The Provider Key for the specified Provider. If using Bing you must specify your own provider key.

GeocodeOptions.PostalAddress optional object

Show Child Properties

GeocodeOptions.PostalAddress.CountryCode optional string

The ISO 3166-1 alpha-2 code indicating the country for the postal address.

GeocodeOptions.PostalAddress.PostalCode optional string

The postal code (or zip code) for the postal address

GeocodeOptions.PostalAddress.Region optional string

The region (i.e. State for U.S. addresses) for the postal address.

GeocodeOptions.PostalAddress.Municipality optional string

The municipality (i.e. City for U.S. addresses) for the postal address

GeocodeOptions.PostalAddress.AddressLine optional string

The address line (i.e. Street address for U.S. address) for the postal address

GeocodeOptions.GeoCoordinates optional object

Show Child Properties

IndexingOptions optional object

When your account is enabled for Matching/Searching you can automatically index documents during the parse transactions.

Show Child Properties

{
  "DocumentAsBase64String": "",
  "RevisionDate": "",
  "OutputHtml": false,
  "OutputRtf": false,
  "OutputPdf": false,  
  "Configuration": {
    "CountryCode": "",
    "Language": "",
    "KnownType": "",
    "IncludeRecruitingTerms": false,
    "IncludeSupplementalText": false,
    "PreferShorterJobTitles": false
  },
  "SkillsData": [
    ""
  ],
  "NormalizerData": "",
  "GeocodeOptions": {
    "IncludeGeocoding": false,
    "Provider": "",
    "ProviderKey": "",
    "PostalAddress": {
      "CountryCode": "",
      "PostalCode": "",
      "Region": "",
      "Municipality": "",
      "AddressLine": ""
    },
    "GeoCoordinates": {
      "Latitude": 0,
      "Longitude": 0
    }
  },
  "IndexingOptions": {
    "IndexId": "",
    "DocumentId": "",
    "CustomIds": [
      ""
    ]
  }
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

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

PossibleTruncationFromTimeout - The timeout occurred before the document was finished parsing which can result in truncation

ConversionException - There was an issue converting the document

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 object

Contains response data for the transaction.

Show Child Properties

Value.ParsedDocument string

The parser results in JSON string format.

Value.FileType string

The input file type that was submitted through the ParseJobOrderRequest.

Value.Text string

The plain text of the parsed job order.

Value.TextCode string

A response code indicating the status of the conversion to Text.

Value.Html string

HTML version of the input file, if OutputHtml was set to true.

Value.HtmlCode string

A response code indicating the status of the conversion to HTML.

Value.Rtf string

RTF version of the input file, if OutputRtf was set to true.

Value.RtfCode string

A response code indicating the status of the conversion to RTF.

Value.Pdf string

The PDF version of the input file, if OutputPdf was set to true. The file bytes are in a Base64-encoded string.

Value.PdfCode string

A response code indicating the status of the conversion to PDF.

Value.FileExtension string

The recommended file extension of the input file.

Value.CreditsRemaining decimal

Value.GeocodeResponse object

If Request.GeocodeOptions.IncludeGeocoding is set to true (thus geocoding is executed), this object will be populated with a response.

Show Child Properties

Value.IndexingResponse object

If Request.IndexingOptions contains any specified parameters, this object will be populated with a response.

Show Child Properties

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "ParsedDocument": "",
    "FileType": "",
    "Text": "",
    "TextCode": "",
    "Html": "",
    "HtmlCode": "",
    "Rtf": "",
    "RtfCode": "",
    "Pdf": "",
    "PdfCode": "",
    "FileExtension": "",
    "CreditsRemaining": 0,
    "GeocodeResponse": {
      "Code": "",
      "Message": ""
    },
    "IndexingResponse": {
      "Code": "",
      "Message": ""
    }
  }
}

Get Account Info

GET /v9/account

Retrieve your account's current information.

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 is `application/json`.

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

Contains response data for the transaction.

Show Child Properties

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "CreditsRemaining": 0,
    "CreditsUsed": 0,
    "MaximumConcurrentRequests": 0,
    "ExpirationDate": ""
  }
}

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 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. All values will be converted to lower-case.

Request Body

IndexType required string

The type of the index. One of: {"Resume", "Job"}

{
  "IndexType": ""
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

An empty object.

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {}
}

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id of the index (case-insensitive).

Response Body

Infp object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

Contains response data for the transaction.

Show Child Properties

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "OwnerId": "",
    "Name": "",
    "IndexType": ""
  }
}

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 is `application/json`.

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object[]

Contains response data for the transaction.

Show Child Properties

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": [
    {
      "OwnerId": "",
      "Name": "",
      "IndexType": ""
    }
  ]
}

Get Index Document Count

GET /v9/index/{indexId}/count

Retrieve the number of documents in 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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id of the index (case-insensitive).

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

Contains response data for the transaction.

Show Child Properties

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "Count": 0,
    "CreditsRemaining": 0
  }
}

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id of the index to delete (case-insensitive).

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

An empty object.

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": { }
}

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 )
Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id for the index where the document should be added (case-insensitive).
documentId	string	The id to assign to the new document. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.

Request Body

ParsedDocument required string

Parsed JSON from the Sovren Resume or Job Order Parser.

CustomIds optional string[]

The custom ids you want the document to have.

{
  "ParsedDocument": "",
  "CustomIds": [
    ""
  ]
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

An empty object.

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {}
}

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 )
Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id for the index where the documents should be added (case-insensitive).

Request Body

DocumentId required string

The id of the current document. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.

ParsedDocument required string

Parsed JSON from the Sovren Resume or Job Order Parser.

CustomIds optional string[]

The custom ids you want the current document to have.

[
  {
    "DocumentId": "",
    "ParsedDocument": "",
    "CustomIds": [
      ""
    ]
  }
]

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

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.

Show Child Properties

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.

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": [
    {
      "DocumentId": "",
      "Code": "",
      "SubCode": "",
      "Message": ""
    }
  ]
}

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id for the index that contains the document (case-insensitive).
documentId	string	The id of the document to retrieve (case-insensitive).

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value string

The JSON document in string format.

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": ""
}

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id for the index that contains the document (case-insensitive).
documentId	string	The id of the document to retrieve (case-insensitive).

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id for the index that contains the document (case-insensitive).
documentId	string	The id of the document to update (case-insensitive).

Request Body

CustomValues required string[]

The custom value ids to add/remove/overwrite in the document.

Method required string

One of: "Delete", "Add", "Overwrite"

{
  "CustomValues": [
    ""
  ],
  "Method": ""
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

An empty object.

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {}
}

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id for the index that contains the document (case-insensitive).
documentId	string	The id of the document to delete (case-insensitive).

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

An empty object.

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": { }
}

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 is `application/json`.

Path Parameters

Parameter	Data Type	Description
indexId	string	The id for the index that contains the documents (case-insensitive).

Request Body

Body required string[]

Each item in the array is the id of a document to delete from the index (case-insensitive).

[""]

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

An empty object.

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": { }
}

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 )
Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

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 is `application/json`.

Request Body

ParsedDocument required string

Parsed JSON from the Sovren Resume or Job Order Parser.

IndexIdsToSearchInto required string[]

The ids of the indexes in which you want to find results (case-insensitive).

Take optional integer

The number of results to return.

CategoryWeights optional object[]

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.

Show Child Properties

Settings optional object

Options to control variations of job titles.

Show Child Properties

FilterCriteria optional object

Additional criteria for the result set.

Show Child Properties

FilterCriteria.RevisionDateRange optional object

When specified, the revision date of documents must fall within this range.

Show Child Properties

FilterCriteria.DocumentIds optional string[]

Results must have one of the specified document ids (case-insensitive).

FilterCriteria.CustomValueIds optional string[]

List of custom value ids. Either all or at least one are required depending on the value of FilterCriteria.CustomValueIdsMustAllExist.

FilterCriteria.CustomValueIdsMustAllExist optional bool

When true, all of the custom value ids in FilterCriteria.CustomValueIds must be found. By default, this is false, which means that at least one of the FilterCriteria.CustomValueIds must be found.

FilterCriteria.LocationCriteria optional object[]

Filter results based on location.

Show Child Properties

FilterCriteria.LocationCriteria.Locations optional object[]

Results must be found within a certain distance of one of the specified locations.

Show Child Properties

FilterCriteria.LocationCriteria.Locations[i].CountryCode optional string

The 2-letter ISO 3166-1 alpha-2 country code for the specified location.

FilterCriteria.LocationCriteria.Locations[i].Region optional string

The region (i.e. State for U.S. addresses) for the location.

FilterCriteria.LocationCriteria.Locations[i].Municipality optional string

The municipality (i.e. City for U.S. addresses) for the location.

FilterCriteria.LocationCriteria.Locations[i].PostalCode optional string

The postal code (or zip code) for the location.

FilterCriteria.LocationCriteria.Locations[i].GeoPoint optional object

The geocordinates to be used in the location.

Show Child Properties

FilterCriteria.LocationCriteria.Distance optional integer

The distance from Locations within which to find results.

FilterCriteria.LocationCriteria.DistanceUnit optional string

The units for the specified distance. One of: {"Miles", "Kilometers"}

FilterCriteria.LocationCriteria.GeocodeProvider conditional string

The provider to lookup latitude/longitude if they are not specified. One of: {"None", "Google", "Bing"}

FilterCriteria.LocationCriteria.GeocodeProviderKey conditional string

The key for the specified GeocodeProvider. If using Bing you must specify your own provider key.

FilterCriteria.SearchExpression optional string

Full-text boolean semantic expresion. For full details on the syntax and supported operations refer to the documentation

FilterCriteria.HasPatents optional bool

If true, results must have/require patent experience.

FilterCriteria.HasSecurityCredentials optional bool

If true, results must have/require security credentials. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.SecurityCredentials optional string[]

Results must have/require at least one of the security credentials specified.

FilterCriteria.IsAuthor optional bool

If true, results must have/require experience as an author.

FilterCriteria.IsPublicSpeaker optional bool

If true, results must have/require public speaking experience.

FilterCriteria.IsMilitary optional bool

If true, results must have/require military experience.

FilterCriteria.Educations optional object[]

Deprecated

Show Child Properties

FilterCriteria.SchoolNames optional string[]

Results must have at least one of the specified school names. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.DegreeNames optional string[]

Results must have at least one of the specified degree names. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.DegreeTypes optional string[]

Results must have at least one of the specified degree types. One of the following explicit values as defined by HROpenStandards.org, in increasing order:

specialeducation
someHighSchoolOrEquivalent
ged
secondary
highSchoolOrEquivalent
certification
vocational
someCollege
HND_HNC_OrEquivalent
associates
international
bachelors
somePostgraduate
masters
intermediategraduate
professional
postprofessional
doctorate
postdoctorate

FilterCriteria.Employers optional string[]

Results must have at least one of the employers in FilterCriteria.Employers. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.EmployersMustAllBeCurrentEmployer optional bool

When true, at least one employer in FilterCriteria.Employers must be found in the current time frame.

FilterCriteria.MonthsExperience optional object

When specified, results total work experieince must fall within this range.

Show Child Properties

FilterCriteria.DocumentLanguages optional string[]

Results must be written in one of the specified languages.

FilterCriteria.Skills optional object[]

Results must have/require at least one of the specified skills.

Show Child Properties

FilterCriteria.Skills[i].SkillName optional string

The name of the skill. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.Skills[i].ExperienceLevel optional string

The experience level of the skill. Supports the following values:

Low (0-3 years)
Mid (4-6 years)
High (7+ years)

FilterCriteria.Skills[i].MonthsOfExperienceRange optional object[]

Deprecated - use FilterCriteria.Skills[i].ExperienceLevel

Show Child Properties

FilterCriteria.Skills[i].IsCurrent optional bool

The skill must be a current skill.

FilterCriteria.SkillsMustAllExist optional bool

When true, all of the skills in FilterCriteria.Skills must be found. By default, this is false, which means that at least one of the FilterCriteria.Skills must be found.

FilterCriteria.IsTopStudent optional bool

Results must have an education with a normalized gpa of .75 or higher (for example, 3.0/4.0 or higher).

FilterCriteria.IsCurrentStudent optional bool

Results must have a current education.

FilterCriteria.IsRecentGraduate optional bool

Results must have graduated within the last 18 months

FilterCriteria.JobTitles optional object[]

Results must have at least one of the specified job titles.

Show Child Properties

FilterCriteria.ExecutiveType optional string[]

Results must have at least one of the following types of executive:

None
Executive
Admin
Accounting
Operations
Financial
Marketing
Business_Dev
IT
General
Learning

FilterCriteria.Certifications optional string[]

Results must have at least one of the specified certifications. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.MonthsManagementExperience optional object

Results must have the management experience specified in this months range.

Show Child Properties

FilterCriteria.CurrentManagementLevel optional string

Results must currently have at least one of the following management levels:

None
Low
Mid
High

FilterCriteria.LanguagesKnown optional string[]

List of ISO 639-1 language codes (lower case, two letters) representing languages known. Either all or at least one are required depending on the value of FilterCriteria.LanguagesKnownMustAllExist.

FilterCriteria.LanguagesKnownMustAllExist optional bool

When true, all of the languages in FilterCriteria.LanguagesKnown must be found. By default, this is false, which means that at least one of the FilterCriteria.LanguagesKnown must be found.

FilterCriteria.Taxonomies optional string[]

Results must contain at least one of the specified best-fit taxonomy IDs or best-fit subtaxonomy IDs. A list of our built-in taxonomy IDs can be found here.

{
  "ParsedDocument": "",
  "IndexIdsToSearchInto": [
    ""
  ],
  "Take": 0,
  "CategoryWeights": [
    {
      "Category": "",
      "Weight": 0
    }
  ],
  "Settings": {
    "PositionTitlesMustHaveAnExactMatch": false,
    "PositionTitlesIgnoreSingleWordVariations": false
  },
  "FilterCriteria": {
    "RevisionDateRange": {
      "Minimum": "",
      "Maximum": ""
    },
    "DocumentIds": [
      ""
    ],
    "CustomValueIds": [
      ""
    ],
    "CustomValueIdsMustAllExist" : false,
    "LocationCriteria": {
      "Locations": [
        {
          "CountryCode": "",
          "Region": "",
          "Municipality": "",
          "PostalCode": "",
          "GeoPoint": {
            "Latitude": 0,
            "Longitude": 0
          }
        }
      ],
      "Distance": 0,
      "DistanceUnit": "Miles",
      "GeocodeProvider": "None",
      "GeocodeProviderKey": ""
    },
    "SearchExpression": "",
    "HasPatents": false,
    "HasSecurityCredentials": false,
    "SecurityCredentials": [
      ""
    ],
    "IsAuthor": false,
    "IsPublicSpeaker": false,
    "IsMilitary": false,
    "Educations": [
      {
        "SchoolName": "",
        "DegreeMajor": "",
        "DegreeName": "",
        "DegreeType": "",
        "MinimumGPA": 0
      }
    ],
    "SchoolNames": [
      ""
    ],
    "DegreeNames": [
      ""
    ],
    "DegreeTypes": [
      ""
    ],
    "Employers": [
      ""
    ],
    "EmployersMustAllBeCurrentEmployer": false,
    "MonthsExperience": {
      "Minimum": 0,
      "Maximum": 0
    },
    "DocumentLanguages": [
      ""
    ],
    "Skills": [
      {
        "SkillName": "",
        "ExperienceLevel" : "",
        "MonthsOfExperienceRange": {
          "Minimum": 0,
          "Maximum": 0
        },
        "IsCurrent": false
      }
    ],
    "SkillsMustAllExist" : false,
    "IsTopStudent" : false,
    "IsCurrentStudent" : false,
    "IsRecentGraduate" : false,
    "JobTitles": [
      {
        "Title": "",
        "IsCurrent": false
      }
    ],
    "ExecutiveType": [
      ""
    ],
    "Certifications": [
      ""
    ],
    "MonthsManagementExperience": {
        "Minimum": 0,
        "Maximum": 0
    },
    "CurrentManagementLevel" : "",
    "LanguagesKnown": [
      ""
    ],
    "LanguagesKnownMustAllExist" : false,
    "Taxonomies": [
      ""
    ]
  }
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

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

ConstraintError - A conditionally required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

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

DataNotFound - Couldn't find the requested asset

Info.Message optional string

This message further describes the code providing additional detail.

Value object

Contains response data for the transaction.

Show Child Properties

Value.Matches object[]

An object[] containing the results for each match result.

Show Child Properties

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].SovScore integer

An integer score representing the overall fit of the match. Results are sorted by this parameter in descending order.

Value.Matches[i].EnrichedScoreData object

Detailed information about the source to target match.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Languages object

Detailed match information for the Languages category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Certifications object

Detailed match information for the Certifications category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ExecutiveType object

Detailed match information for the ExecutiveType category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education object

Detailed match information for the Eduction category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Education.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education.ExpectedEducation string

Requested level of education.

Value.Matches[i].EnrichedScoreData.Education.ActualEducation string

Actual level of education found.

Value.Matches[i].EnrichedScoreData.Education.Comparison string

Description of the relationship of ExpectedEducation and ActualEducation. This provides an easier value to key off of. Possible values are:

DoesNotMeetExpected
MeetsExpected
ExceedsExpected

Value.Matches[i].EnrichedScoreData.Taxonomies object

Detailed match information for the Taxonomies category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Taxonomies.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies object

Taxonomies found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies object

Taxonomies requested.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles object

Detailed match information for the JobTitles category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.JobTitles.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.Found string[]

Array of Job Titles found in both documents.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedScoreData.Skills object

Detailed match information for the Skills category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Skills.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.Found string[]

Array of Skills found in both documents.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedScoreData.ManagementLevel object

Detailed match information for the ManagementLevel category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ManagementLevel.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.ManagementLevel.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ManagementLevel.Actual string

Actual management level found.

Value.Matches[i].EnrichedScoreData.ManagementLevel.Desired string

Requested management level.

Value.Matches[i].EnrichedScoreData.ManagementLevel.AmountOfExperienceMatches bool

True when the duration of management level matches in the two documents.

Value.Matches[i].EnrichedRCSScoreData object

Detailed information about the target to source match.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Languages object

Detailed match information for the Languages category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Certifications object

Detailed match information for the Certifications category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ExecutiveType object

Detailed match information for the ExecutiveType category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education object

Detailed match information for the Eduction category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Education.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education.ExpectedEducation string

Requested level of education.

Value.Matches[i].EnrichedRCSScoreData.Education.ActualEducation string

Actual level of education found.

Value.Matches[i].EnrichedRCSScoreData.Education.Comparison string

Description of the relationship of ExpectedEducation and ActualEducation. This provides an easier value to key off of. Possible values are:

DoesNotMeetExpected
MeetsExpected
ExceedsExpected

Value.Matches[i].EnrichedRCSScoreData.Taxonomies object

Detailed match information for the Taxonomies category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies object

Taxonomies found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies object

Taxonomies requested.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles object

Detailed match information for the JobTitles category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.JobTitles.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.Found string[]

Array of Job Titles found in both documents.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedRCSScoreData.Skills object

Detailed match information for the Skills category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Skills.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.Found string[]

Array of Skills found in both documents.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel object

Detailed match information for the ManagementLevel category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Actual string

Actual management level found.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Desired string

Requested management level.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.AmountOfExperienceMatches bool

True when the duration of management level matches in the two documents.

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 scores multiplied by their respective suggested weight.

Value.Matches[i].UnweightedCategoryScores object[]

Deprecated

Show Child Properties

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.SuggestedCategoryWeights object[]

An object[] containing our suggested weights for each category based on the source document.

Show Child Properties

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 and any desired weights passed in the request.

Show Child Properties

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

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "Matches": [
      {
        "Id": "",
        "IndexId": "",
        "SovScore": 0,
        "EnrichedScoreData" : {
          "Languages" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Certifications" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "ExecutiveType" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Education" : {
            "UnweightedScore" : 0,
            "ExpectedEducation" : "",
            "ActualEducation" : "",
            "Comparison" : "",
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ]
          },
          "Taxonomies" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "ActualTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            },
            "DesiredTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            }
          },
          "JobTitles" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "RawTerm" : "",
                "VariationOf" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "Skills" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "Skill" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "ManagementLevel" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Actual" : "",
            "Desired" : "",
            "AmountOfExperienceMatches" : false,
          }
        },
        "EnrichedRCSScoreData" : {
          "Languages" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Certifications" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "ExecutiveType" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Education" : {
            "UnweightedScore" : 0,
            "ExpectedEducation" : "",
            "ActualEducation" : "",
            "Comparison" : "",
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ]
          },
          "Taxonomies" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "ActualTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            },
            "DesiredTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            }
          },
          "JobTitles" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "RawTerm" : "",
                "VariationOf" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "Skills" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "Skill" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "ManagementLevel" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Actual" : "",
            "Desired" : "",
            "AmountOfExperienceMatches" : false,
          }
        },
        "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
  }
}

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 )
Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

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 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 (case-insensitive).

Request Body

IndexIdsToSearchInto required string[]

The ids of the indexes in which you want to find results (case-insensitive).

Take optional integer

The number of results to return.

CategoryWeights optional object[]

Show Child Properties

Settings optional object

Options to control variations of job titles.

Show Child Properties

FilterCriteria optional object

Additional criteria for the result set.

Show Child Properties

FilterCriteria.RevisionDateRange optional object

When specified, the revision date of documents must fall within this range.

Show Child Properties

FilterCriteria.DocumentIds optional string[]

Results must have one of the specified document ids (case-insensitive).

FilterCriteria.CustomValueIds optional string[]

List of custom value ids. Either all or at least one are required depending on the value of FilterCriteria.CustomValueIdsMustAllExist.

FilterCriteria.CustomValueIdsMustAllExist optional bool

When true, all of the custom value ids in FilterCriteria.CustomValueIds must be found. By default, this is false, which means that at least one of the FilterCriteria.CustomValueIds must be found.

FilterCriteria.LocationCriteria optional object[]

Filter results based on location.

Show Child Properties

FilterCriteria.LocationCriteria.Locations optional object[]

Results must be found within a certain distance of one of the specified locations.

Show Child Properties

FilterCriteria.LocationCriteria.Locations[i].CountryCode optional string

The 2-letter ISO 3166-1 alpha-2 country code for the specified location.

FilterCriteria.LocationCriteria.Locations[i].Region optional string

The region (i.e. State for U.S. addresses) for the location.

FilterCriteria.LocationCriteria.Locations[i].Municipality optional string

The municipality (i.e. City for U.S. addresses) for the location.

FilterCriteria.LocationCriteria.Locations[i].PostalCode optional string

The postal code (or zip code) for the location.

FilterCriteria.LocationCriteria.Locations[i].GeoPoint optional object

The geocordinates to be used in the location.

Show Child Properties

FilterCriteria.LocationCriteria.Distance optional integer

The distance from Locations within which to find results.

FilterCriteria.LocationCriteria.DistanceUnit optional string

The units for the specified distance. One of: {"Miles", "Kilometers"}

FilterCriteria.LocationCriteria.GeocodeProvider conditional string

The provider to lookup latitude/longitude if they are not specified. One of: {"None", "Google", "Bing"}

FilterCriteria.LocationCriteria.GeocodeProviderKey conditional string

The key for the specified GeocodeProvider. If using Bing you must specify your own provider key.

FilterCriteria.SearchExpression optional string

Full-text boolean semantic expresion. For full details on the syntax and supported operations refer to the documentation

FilterCriteria.HasPatents optional bool

If true, results must have/require patent experience.

FilterCriteria.HasSecurityCredentials optional bool

If true, results must have/require security credentials. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.SecurityCredentials optional string[]

Results must have/require at least one of the security credentials specified.

FilterCriteria.IsAuthor optional bool

If true, results must have/require experience as an author.

FilterCriteria.IsPublicSpeaker optional bool

If true, results must have/require public speaking experience.

FilterCriteria.IsMilitary optional bool

If true, results must have/require military experience.

FilterCriteria.Educations optional object[]

Deprecated

Show Child Properties

FilterCriteria.SchoolNames optional string[]

Results must have at least one of the specified school names. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.DegreeNames optional string[]

Results must have at least one of the specified degree names. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.DegreeTypes optional string[]

Results must have at least one of the specified degree types. One of the following explicit values as defined by HROpenStandards.org, in increasing order:

specialeducation
someHighSchoolOrEquivalent
ged
secondary
highSchoolOrEquivalent
certification
vocational
someCollege
HND_HNC_OrEquivalent
associates
international
bachelors
somePostgraduate
masters
intermediategraduate
professional
postprofessional
doctorate
postdoctorate

FilterCriteria.Employers optional string[]

Results must have at least one of the employers in FilterCriteria.Employers. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.EmployersMustAllBeCurrentEmployer optional bool

When true, at least one employer in FilterCriteria.Employers must be found in the current time frame.

FilterCriteria.MonthsExperience optional object

When specified, results total work experieince must fall within this range.

Show Child Properties

FilterCriteria.DocumentLanguages optional string[]

Results must be written in one of the specified languages.

FilterCriteria.Skills optional object[]

Results must have/require at least one of the specified skills.

Show Child Properties

FilterCriteria.Skills[i].SkillName optional string

The name of the skill. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.Skills[i].ExperienceLevel optional string

The experience level of the skill. Supports the following values:

Low (0-3 years)
Mid (4-6 years)
High (7+ years)

FilterCriteria.Skills[i].MonthsOfExperienceRange optional object[]

Deprecated - use FilterCriteria.Skills[i].ExperienceLevel

Show Child Properties

FilterCriteria.Skills[i].IsCurrent optional bool

The skill must be a current skill.

FilterCriteria.SkillsMustAllExist optional bool

When true, all of the skills in FilterCriteria.Skills must be found. By default, this is false, which means that at least one of the FilterCriteria.Skills must be found.

FilterCriteria.IsTopStudent optional bool

Results must have an education with a normalized gpa of .75 or higher (for example, 3.0/4.0 or higher).

FilterCriteria.IsCurrentStudent optional bool

Results must have a current education.

FilterCriteria.IsRecentGraduate optional bool

Results must have graduated within the last 18 months

FilterCriteria.JobTitles optional object[]

Results must have at least one of the specified job titles.

Show Child Properties

FilterCriteria.ExecutiveType optional string[]

Results must have at least one of the following types of executive:

None
Executive
Admin
Accounting
Operations
Financial
Marketing
Business_Dev
IT
General
Learning

FilterCriteria.Certifications optional string[]

Results must have at least one of the specified certifications. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.MonthsManagementExperience optional object

Results must have the management experience specified in this months range.

Show Child Properties

FilterCriteria.CurrentManagementLevel optional string

Results must currently have at least one of the following management levels:

None
Low
Mid
High

FilterCriteria.LanguagesKnown optional string[]

List of ISO 639-1 language codes (lower case, two letters) representing languages known. Either all or at least one are required depending on the value of FilterCriteria.LanguagesKnownMustAllExist.

FilterCriteria.LanguagesKnownMustAllExist optional bool

When true, all of the languages in FilterCriteria.LanguagesKnown must be found. By default, this is false, which means that at least one of the FilterCriteria.LanguagesKnown must be found.

FilterCriteria.Taxonomies optional string[]

Results must contain at least one of the specified best-fit taxonomy IDs or best-fit subtaxonomy IDs. A list of our built-in taxonomy IDs can be found here.

{
  "IndexIdsToSearchInto": [
    ""
  ],
  "Take": 0,
  "CategoryWeights": [
    {
      "Category": "",
      "Weight": 0
    }
  ],
  "Settings": {
    "PositionTitlesMustHaveAnExactMatch": false,
    "PositionTitlesIgnoreSingleWordVariations": false
  },
  "FilterCriteria": {
    "RevisionDateRange": {
      "Minimum": "",
      "Maximum": ""
    },
    "DocumentIds": [
      ""
    ],
    "CustomValueIds": [
      ""
    ],
    "CustomValueIdsMustAllExist" : false,
    "LocationCriteria": {
      "Locations": [
        {
          "CountryCode": "",
          "Region": "",
          "Municipality": "",
          "PostalCode": "",
          "GeoPoint": {
            "Latitude": 0,
            "Longitude": 0
          }
        }
      ],
      "Distance": 0,
      "DistanceUnit": "Miles",
      "GeocodeProvider": "None",
      "GeocodeProviderKey": ""
    },
    "SearchExpression": "",
    "HasPatents": false,
    "HasSecurityCredentials": false,
    "SecurityCredentials": [
      ""
    ],
    "IsAuthor": false,
    "IsPublicSpeaker": false,
    "IsMilitary": false,
    "Educations": [
      {
        "SchoolName": "",
        "DegreeMajor": "",
        "DegreeName": "",
        "DegreeType": "",
        "MinimumGPA": 0
      }
    ],
    "SchoolNames": [
      ""
    ],
    "DegreeNames": [
      ""
    ],
    "DegreeTypes": [
      ""
    ],
    "Employers": [
      ""
    ],
    "EmployersMustAllBeCurrentEmployer": false,
    "MonthsExperience": {
      "Minimum": 0,
      "Maximum": 0
    },
    "DocumentLanguages": [
      ""
    ],
    "Skills": [
      {
        "SkillName": "",
        "ExperienceLevel" : "",
        "MonthsOfExperienceRange": {
          "Minimum": 0,
          "Maximum": 0
        },
        "IsCurrent": false
      }
    ],
    "SkillsMustAllExist" : false,
    "IsTopStudent" : false,
    "IsCurrentStudent" : false,
    "IsRecentGraduate" : false,
    "JobTitles": [
      {
        "Title": "",
        "IsCurrent": false
      }
    ],
    "ExecutiveType": [
      ""
    ],
    "Certifications": [
      ""
    ],
    "MonthsManagementExperience": {
        "Minimum": 0,
        "Maximum": 0
    },
    "CurrentManagementLevel" : "",
    "LanguagesKnown": [
      ""
    ],
    "LanguagesKnownMustAllExist" : false,
    "Taxonomies": [
      ""
    ]
  }
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Info.Code string

Info.Message optional string

This message further describes the code providing additional detail.

Value object

Contains response data for the transaction.

Show Child Properties

Value.Matches object[]

An object[] containing the results for each match result.

Show Child Properties

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].SovScore integer

An integer score representing the overall fit of the match. Results are sorted by this parameter in descending order.

Value.Matches[i].EnrichedScoreData object

Detailed information about the source to target match.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Languages object

Detailed match information for the Languages category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Certifications object

Detailed match information for the Certifications category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ExecutiveType object

Detailed match information for the ExecutiveType category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education object

Detailed match information for the Eduction category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Education.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education.ExpectedEducation string

Requested level of education.

Value.Matches[i].EnrichedScoreData.Education.ActualEducation string

Actual level of education found.

Value.Matches[i].EnrichedScoreData.Education.Comparison string

Description of the relationship of ExpectedEducation and ActualEducation. This provides an easier value to key off of. Possible values are:

DoesNotMeetExpected
MeetsExpected
ExceedsExpected

Value.Matches[i].EnrichedScoreData.Taxonomies object

Detailed match information for the Taxonomies category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Taxonomies.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies object

Taxonomies found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies object

Taxonomies requested.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles object

Detailed match information for the JobTitles category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.JobTitles.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.Found string[]

Array of Job Titles found in both documents.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedScoreData.Skills object

Detailed match information for the Skills category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Skills.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.Found string[]

Array of Skills found in both documents.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedScoreData.ManagementLevel object

Detailed match information for the ManagementLevel category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ManagementLevel.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.ManagementLevel.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ManagementLevel.Actual string

Actual management level found.

Value.Matches[i].EnrichedScoreData.ManagementLevel.Desired string

Requested management level.

Value.Matches[i].EnrichedScoreData.ManagementLevel.AmountOfExperienceMatches bool

True when the duration of management level matches in the two documents.

Value.Matches[i].EnrichedRCSScoreData object

Detailed information about the target to source match.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Languages object

Detailed match information for the Languages category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Certifications object

Detailed match information for the Certifications category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ExecutiveType object

Detailed match information for the ExecutiveType category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education object

Detailed match information for the Eduction category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Education.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education.ExpectedEducation string

Requested level of education.

Value.Matches[i].EnrichedRCSScoreData.Education.ActualEducation string

Actual level of education found.

Value.Matches[i].EnrichedRCSScoreData.Education.Comparison string

Description of the relationship of ExpectedEducation and ActualEducation. This provides an easier value to key off of. Possible values are:

DoesNotMeetExpected
MeetsExpected
ExceedsExpected

Value.Matches[i].EnrichedRCSScoreData.Taxonomies object

Detailed match information for the Taxonomies category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies object

Taxonomies found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies object

Taxonomies requested.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles object

Detailed match information for the JobTitles category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.JobTitles.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.Found string[]

Array of Job Titles found in both documents.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedRCSScoreData.Skills object

Detailed match information for the Skills category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Skills.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.Found string[]

Array of Skills found in both documents.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel object

Detailed match information for the ManagementLevel category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Actual string

Actual management level found.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Desired string

Requested management level.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.AmountOfExperienceMatches bool

True when the duration of management level matches in the two documents.

Value.Matches[i].WeightedScore integer

Value.Matches[i].UnweightedCategoryScores object[]

Deprecated

Show Child Properties

Value.Matches[i].ReverseCompatibilityScore integer

Value.SuggestedCategoryWeights object[]

An object[] containing our suggested weights for each category based on the source document.

Show Child Properties

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 and any desired weights passed in the request.

Show Child Properties

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

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "Matches": [
      {
        "Id": "",
        "IndexId": "",
        "SovScore": 0,
        "EnrichedScoreData" : {
          "Languages" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Certifications" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "ExecutiveType" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Education" : {
            "UnweightedScore" : 0,
            "ExpectedEducation" : "",
            "ActualEducation" : "",
            "Comparison" : "",
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ]
          },
          "Taxonomies" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "ActualTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            },
            "DesiredTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            }
          },
          "JobTitles" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "RawTerm" : "",
                "VariationOf" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "Skills" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "Skill" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "ManagementLevel" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Actual" : "",
            "Desired" : "",
            "AmountOfExperienceMatches" : false,
          }
        },
        "EnrichedRCSScoreData" : {
          "Languages" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Certifications" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "ExecutiveType" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Education" : {
            "UnweightedScore" : 0,
            "ExpectedEducation" : "",
            "ActualEducation" : "",
            "Comparison" : "",
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ]
          },
          "Taxonomies" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "ActualTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            },
            "DesiredTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            }
          },
          "JobTitles" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "RawTerm" : "",
                "VariationOf" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "Skills" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "Skill" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "ManagementLevel" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Actual" : "",
            "Desired" : "",
            "AmountOfExperienceMatches" : false,
          }
        },
        "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
  }
}

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 is `application/json`.

Request Body

IndexIdsToSearchInto required string[]

The ids of the indexes in which you want to find results (case-insensitive).

PaginationSettings optional object

Choose which results to return from the list.

Show Child Properties

Settings optional object

Options to control variations of job titles.

Show Child Properties

FilterCriteria optional object

Additional criteria for the result set.

Show Child Properties

FilterCriteria.RevisionDateRange optional object

When specified, the revision date of documents must fall within this range.

Show Child Properties

FilterCriteria.DocumentIds optional string[]

Results must have one of the specified document ids (case-insensitive).

FilterCriteria.CustomValueIds optional string[]

List of custom value ids. Either all or at least one are required depending on the value of FilterCriteria.CustomValueIdsMustAllExist.

FilterCriteria.CustomValueIdsMustAllExist optional bool

When true, all of the custom value ids in FilterCriteria.CustomValueIds must be found. By default, this is false, which means that at least one of the FilterCriteria.CustomValueIds must be found.

FilterCriteria.LocationCriteria optional object[]

Filter results based on location.

Show Child Properties

FilterCriteria.LocationCriteria.Locations optional object[]

Results must be found within a certain distance of one of the specified locations.

Show Child Properties

FilterCriteria.LocationCriteria.Locations[i].CountryCode optional string

The 2-letter ISO 3166-1 alpha-2 country code for the specified location.

FilterCriteria.LocationCriteria.Locations[i].Region optional string

The region (i.e. State for U.S. addresses) for the location.

FilterCriteria.LocationCriteria.Locations[i].Municipality optional string

The municipality (i.e. City for U.S. addresses) for the location.

FilterCriteria.LocationCriteria.Locations[i].PostalCode optional string

The postal code (or zip code) for the location.

FilterCriteria.LocationCriteria.Locations[i].GeoPoint optional object

The geocordinates to be used in the location.

Show Child Properties

FilterCriteria.LocationCriteria.Distance optional integer

The distance from Locations within which to find results.

FilterCriteria.LocationCriteria.DistanceUnit optional string

The units for the specified distance. One of: {"Miles", "Kilometers"}

FilterCriteria.LocationCriteria.GeocodeProvider conditional string

The provider to lookup latitude/longitude if they are not specified. One of: {"None", "Google", "Bing"}

FilterCriteria.LocationCriteria.GeocodeProviderKey conditional string

The key for the specified GeocodeProvider. If using Bing you must specify your own provider key.

FilterCriteria.SearchExpression optional string

Full-text boolean semantic expresion. For full details on the syntax and supported operations refer to the documentation

FilterCriteria.HasPatents optional bool

If true, results must have/require patent experience.

FilterCriteria.HasSecurityCredentials optional bool

If true, results must have/require security credentials. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.SecurityCredentials optional string[]

Results must have/require at least one of the security credentials specified.

FilterCriteria.IsAuthor optional bool

If true, results must have/require experience as an author.

FilterCriteria.IsPublicSpeaker optional bool

If true, results must have/require public speaking experience.

FilterCriteria.IsMilitary optional bool

If true, results must have/require military experience.

FilterCriteria.Educations optional object[]

Deprecated

Show Child Properties

FilterCriteria.SchoolNames optional string[]

Results must have at least one of the specified school names. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.DegreeNames optional string[]

Results must have at least one of the specified degree names. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.DegreeTypes optional string[]

Results must have at least one of the specified degree types. One of the following explicit values as defined by HROpenStandards.org, in increasing order:

specialeducation
someHighSchoolOrEquivalent
ged
secondary
highSchoolOrEquivalent
certification
vocational
someCollege
HND_HNC_OrEquivalent
associates
international
bachelors
somePostgraduate
masters
intermediategraduate
professional
postprofessional
doctorate
postdoctorate

FilterCriteria.Employers optional string[]

Results must have at least one of the employers in FilterCriteria.Employers. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.EmployersMustAllBeCurrentEmployer optional bool

When true, at least one employer in FilterCriteria.Employers must be found in the current time frame.

FilterCriteria.MonthsExperience optional object

When specified, results total work experieince must fall within this range.

Show Child Properties

FilterCriteria.DocumentLanguages optional string[]

Results must be written in one of the specified languages.

FilterCriteria.Skills optional object[]

Results must have/require at least one of the specified skills.

Show Child Properties

FilterCriteria.Skills[i].SkillName optional string

The name of the skill. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.Skills[i].ExperienceLevel optional string

The experience level of the skill. Supports the following values:

Low (0-3 years)
Mid (4-6 years)
High (7+ years)

FilterCriteria.Skills[i].MonthsOfExperienceRange optional object[]

Deprecated - use FilterCriteria.Skills[i].ExperienceLevel

Show Child Properties

FilterCriteria.Skills[i].IsCurrent optional bool

The skill must be a current skill.

FilterCriteria.SkillsMustAllExist optional bool

When true, all of the skills in FilterCriteria.Skills must be found. By default, this is false, which means that at least one of the FilterCriteria.Skills must be found.

FilterCriteria.IsTopStudent optional bool

Results must have an education with a normalized gpa of .75 or higher (for example, 3.0/4.0 or higher).

FilterCriteria.IsCurrentStudent optional bool

Results must have a current education.

FilterCriteria.IsRecentGraduate optional bool

Results must have graduated within the last 18 months

FilterCriteria.JobTitles optional object[]

Results must have at least one of the specified job titles.

Show Child Properties

FilterCriteria.ExecutiveType optional string[]

Results must have at least one of the following types of executive:

None
Executive
Admin
Accounting
Operations
Financial
Marketing
Business_Dev
IT
General
Learning

FilterCriteria.Certifications optional string[]

Results must have at least one of the specified certifications. Supports (*, ?) wildcard characters after the third character in the term as defined in Special Operators.

FilterCriteria.MonthsManagementExperience optional object

Results must have the management experience specified in this months range.

Show Child Properties

FilterCriteria.CurrentManagementLevel optional string

Results must currently have at least one of the following management levels:

None
Low
Mid
High

FilterCriteria.LanguagesKnown optional string[]

List of ISO 639-1 language codes (lower case, two letters) representing languages known. Either all or at least one are required depending on the value of FilterCriteria.LanguagesKnownMustAllExist.

FilterCriteria.LanguagesKnownMustAllExist optional bool

When true, all of the languages in FilterCriteria.LanguagesKnown must be found. By default, this is false, which means that at least one of the FilterCriteria.LanguagesKnown must be found.

FilterCriteria.Taxonomies optional string[]

Results must contain at least one of the specified best-fit taxonomy IDs or best-fit subtaxonomy IDs. A list of our built-in taxonomy IDs can be found here.

{
  "IndexIdsToSearchInto": [
    ""
  ],
  "PaginationSettings": {
    "Skip": 0,
    "Take": 0
  },
  "Settings": {
    "PositionTitlesMustHaveAnExactMatch": false,
    "PositionTitlesIgnoreSingleWordVariations": false
  },
  "FilterCriteria": {
    "RevisionDateRange": {
      "Minimum": "",
      "Maximum": ""
    },
    "DocumentIds": [
      ""
    ],
    "CustomValueIds": [
      ""
    ],
    "CustomValueIdsMustAllExist" : false,
    "LocationCriteria": {
      "Locations": [
        {
          "CountryCode": "",
          "Region": "",
          "Municipality": "",
          "PostalCode": "",
          "GeoPoint": {
            "Latitude": 0,
            "Longitude": 0
          }
        }
      ],
      "Distance": 0,
      "DistanceUnit": "Miles",
      "GeocodeProvider": "None",
      "GeocodeProviderKey": ""
    },
    "SearchExpression": "",
    "HasPatents": false,
    "HasSecurityCredentials": false,
    "SecurityCredentials": [
      ""
    ],
    "IsAuthor": false,
    "IsPublicSpeaker": false,
    "IsMilitary": false,
    "Educations": [
      {
        "SchoolName": "",
        "DegreeMajor": "",
        "DegreeName": "",
        "DegreeType": "",
        "MinimumGPA": 0
      }
    ],
    "SchoolNames": [
      ""
    ],
    "DegreeNames": [
      ""
    ],
    "DegreeTypes": [
      ""
    ],
    "Employers": [
      ""
    ],
    "EmployersMustAllBeCurrentEmployer": false,
    "MonthsExperience": {
      "Minimum": 0,
      "Maximum": 0
    },
    "DocumentLanguages": [
      ""
    ],
    "Skills": [
      {
        "SkillName": "",
        "ExperienceLevel" : "",
        "MonthsOfExperienceRange": {
          "Minimum": 0,
          "Maximum": 0
        },
        "IsCurrent": false
      }
    ],
    "SkillsMustAllExist" : false,
    "IsTopStudent" : false,
    "IsCurrentStudent" : false,
    "IsRecentGraduate" : false,
    "JobTitles": [
      {
        "Title": "",
        "IsCurrent": false
      }
    ],
    "ExecutiveType": [
      ""
    ],
    "Certifications": [
      ""
    ],
    "MonthsManagementExperience": {
        "Minimum": 0,
        "Maximum": 0
    },
    "CurrentManagementLevel" : "",
    "LanguagesKnown": [
      ""
    ],
    "LanguagesKnownMustAllExist" : false,
    "Taxonomies": [
      ""
    ]
  }
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Info.Code string

Info.Message optional string

This message further describes the code providing additional detail.

Value object

Contains response data for the transaction.

Show Child Properties

Value.Matches object[]

An object[] containing the results for each match result.

Show Child Properties

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

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "Matches": [
      {
        "Id": "",
        "IndexId": ""
      }
    ],
    "CurrentCount": 0,
    "TotalCount": 0,
    "ElapsedMilliseconds": 0,
    "CreditsRemaining": 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. The only supported value is `application/json`.

Request Body

SourceDocument required object

Parsed document to match against each of the target documents.

Show Child Properties

TargetDocuments required object[]

Array of parsed documents to be matched against the source document.

Show Child Properties

Settings optional object

Options to control variations of job titles.

Show Child Properties

CategoryWeights optional object[]

Show Child Properties

{
  "SourceDocument": {
    "Id": "",
    "FileText": ""
  },
  "TargetDocuments": [
    {
      "Id": "",
      "FileText": ""
    }
  ],
  "Settings": {
    "PositionTitlesMustHaveAnExactMatch": false,
    "PositionTitlesIgnoreSingleWordVariations": false
  },
  "CategoryWeights": [
    {
      "Category": "",
      "Weight": 0
    }
  ]
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

Contains response data for the transaction.

Show Child Properties

Value.Matches object[]

An object[] containing the results for each match result.

Show Child Properties

Value.Matches[i].Id string

Id of the matched document in the index.

Value.Matches[i].SovScore integer

An integer score representing the overall fit of the match. Results are sorted by this parameter in descending order.

Value.Matches[i].EnrichedScoreData object

Detailed information about the source to target match.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Languages object

Detailed match information for the Languages category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Certifications object

Detailed match information for the Certifications category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ExecutiveType object

Detailed match information for the ExecutiveType category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education object

Detailed match information for the Eduction category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Education.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Education.ExpectedEducation string

Requested level of education.

Value.Matches[i].EnrichedScoreData.Education.ActualEducation string

Actual level of education found.

Value.Matches[i].EnrichedScoreData.Education.Comparison string

Description of the relationship of ExpectedEducation and ActualEducation. This provides an easier value to key off of. Possible values are:

DoesNotMeetExpected
MeetsExpected
ExceedsExpected

Value.Matches[i].EnrichedScoreData.Taxonomies object

Detailed match information for the Taxonomies category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Taxonomies.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies object

Taxonomies found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.ActualTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies object

Taxonomies requested.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Taxonomies.DesiredTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles object

Detailed match information for the JobTitles category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.JobTitles.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.Found string[]

Array of Job Titles found in both documents.

Show Child Properties

Value.Matches[i].EnrichedScoreData.JobTitles.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedScoreData.Skills object

Detailed match information for the Skills category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.Skills.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.Found string[]

Array of Skills found in both documents.

Show Child Properties

Value.Matches[i].EnrichedScoreData.Skills.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedScoreData.ManagementLevel object

Detailed match information for the ManagementLevel category.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ManagementLevel.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedScoreData.ManagementLevel.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedScoreData.ManagementLevel.Actual string

Actual management level found.

Value.Matches[i].EnrichedScoreData.ManagementLevel.Desired string

Requested management level.

Value.Matches[i].EnrichedScoreData.ManagementLevel.AmountOfExperienceMatches bool

True when the duration of management level matches in the two documents.

Value.Matches[i].EnrichedRCSScoreData object

Detailed information about the target to source match.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Languages object

Detailed match information for the Languages category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Certifications object

Detailed match information for the Certifications category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ExecutiveType object

Detailed match information for the ExecutiveType category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education object

Detailed match information for the Eduction category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Education.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Education.ExpectedEducation string

Requested level of education.

Value.Matches[i].EnrichedRCSScoreData.Education.ActualEducation string

Actual level of education found.

Value.Matches[i].EnrichedRCSScoreData.Education.Comparison string

Description of the relationship of ExpectedEducation and ActualEducation. This provides an easier value to key off of. Possible values are:

DoesNotMeetExpected
MeetsExpected
ExceedsExpected

Value.Matches[i].EnrichedRCSScoreData.Taxonomies object

Detailed match information for the Taxonomies category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies object

Taxonomies found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.ActualTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies object

Taxonomies requested.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary object

Best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary.Taxonomy object

Best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Primary.Subtaxonomy object

Best fit sub-taxonomy

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary object

Second best fit taxonomy evidence.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary.Taxonomy object

Second best fit parent taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Taxonomies.DesiredTaxonomies.Secondary.Subtaxonomy object

Second best fit sub-taxonomy.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles object

Detailed match information for the JobTitles category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.JobTitles.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.Found string[]

Array of Job Titles found in both documents.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.JobTitles.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedRCSScoreData.Skills object

Detailed match information for the Skills category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.Skills.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.Found string[]

Array of Skills found in both documents.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.Skills.NotFound string[]

Array of terms requested, but not found.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel object

Detailed match information for the ManagementLevel category.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.UnweightedScore double

An unweighted score from 0-100. This is the percentage match of the specified category.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Evidence object[]

Detailed written explanation about each data point found or not found.

Show Child Properties

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Actual string

Actual management level found.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.Desired string

Requested management level.

Value.Matches[i].EnrichedRCSScoreData.ManagementLevel.AmountOfExperienceMatches bool

True when the duration of management level matches in the two documents.

Value.Matches[i].WeightedScore integer

Value.Matches[i].UnweightedCategoryScores object[]

Deprecated

Show Child Properties

Value.Matches[i].ReverseCompatibilityScore integer

Value.SuggestedCategoryWeights object[]

An object[] containing our suggested weights for each category based on the source document.

Show Child Properties

Value.CreditsRemaining decimal

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "Matches": [
      {
        "Id": "",
        "SovScore": 0,
        "EnrichedScoreData" : {
          "Languages" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Certifications" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "ExecutiveType" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Education" : {
            "UnweightedScore" : 0,
            "ExpectedEducation" : "",
            "ActualEducation" : "",
            "Comparison" : "",
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ]
          },
          "Taxonomies" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "ActualTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            },
            "DesiredTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            }
          },
          "JobTitles" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "RawTerm" : "",
                "VariationOf" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "Skills" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "Skill" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "ManagementLevel" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Actual" : "",
            "Desired" : "",
            "AmountOfExperienceMatches" : false,
          }
        },
        "EnrichedRCSScoreData" : {
          "Languages" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Certifications" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "ExecutiveType" : {
            "UnweightedScore" : 0,
            "Found" : [""],
            "NotFound" : [""],
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
          },
          "Education" : {
            "UnweightedScore" : 0,
            "ExpectedEducation" : "",
            "ActualEducation" : "",
            "Comparison" : "",
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ]
          },
          "Taxonomies" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "ActualTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            },
            "DesiredTaxonomies" : {
              "Primary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
              "Secondary" : {
                "Taxonomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
                "SubTaxnomy" : {
                  "Name" : "",
                  "Id" : "",
                  "Matched" : false
                },
              },
            }
          },
          "JobTitles" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "RawTerm" : "",
                "VariationOf" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "Skills" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Found" : [
              {
                "Skill" : "",
                "IsCurrent" : false,
              }
            ],
            "NotFound" : [""]
          },
          "ManagementLevel" : {
            "UnweightedScore" : 0,
            "Evidence" : [
              {
                "Fact" : "",
                "Type" : ""
              }
            ],
            "Actual" : "",
            "Desired" : "",
            "AmountOfExperienceMatches" : false,
          }
        },
        "WeightedScore": 0,
        "UnweightedCategoryScores": [
          {
            "Category": "",
            "UnweightedScore": 0,
            "TermsFound": [
              ""
            ]
          }
        ],
        "ReverseCompatibilityScore": 0
      }
    ],
    "SuggestedCategoryWeights": [
      {
        "Category": "",
        "Weight": 0
      }
    ],
    "CreditsRemaining": 0,
  }
}

Geocode and Index a Document

POST /v9/geocodeAndIndex

Geocodes a document and adds it 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 is `application/json`.

Request Body

ParsedDocument required string

Parsed JSON from the Sovren Resume or Job Order Parser.

IndexIfGeocodeFails optional bool

Indicates whether or not the document should still be added to the index if the geocode request fails. Default is false.

GeocodeOptions required object

Settings to determine the form of geocoding for the transaction.

Show Child Properties

GeocodeOptions.Provider optional string

The Provider you wish to use to geocode the postal address (current options are "Google" or "Bing"). If not specified, we will default to Google.
If passing a ProviderKey, this field is required.

GeocodeOptions.ProviderKey optional string

The Provider Key for the specified Provider. If using Bing you must specify your own provider key.

GeocodeOptions.PostalAddress optional object

Show Child Properties

GeocodeOptions.PostalAddress.CountryCode optional string

The ISO 3166-1 alpha-2 code indicating the country for the postal address.

GeocodeOptions.PostalAddress.PostalCode optional string

The postal code (or zip code) for the postal address

GeocodeOptions.PostalAddress.Region optional string

The region (i.e. State for U.S. addresses) for the postal address.

GeocodeOptions.PostalAddress.Municipality optional string

The municipality (i.e. City for U.S. addresses) for the postal address

GeocodeOptions.PostalAddress.AddressLine optional string

The address line (i.e. Street address for U.S. address) for the postal address

GeocodeOptions.GeoCoordinates optional object

Show Child Properties

IndexingOptions required object

Settings to specify where to store the document.

Show Child Properties

{
  "ParsedDocument": "",
  "IndexIfGeocodeFails": false,
  "GeocodeOptions": {
    "Provider": "",
    "ProviderKey": "",
    "PostalAddress": {
      "CountryCode": "",
      "PostalCode": "",
      "Region": "",
      "Municipality": "",
      "AddressLine": ""
    },
    "GeoCoordinates": {
      "Latitude": 0,
      "Longitude": 0
    }
  },
  "IndexingOptions": {
    "IndexId": "",
    "DocumentId": "",
    "CustomIds": [
      ""
    ]
  }
}

Request Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

Contains response data for the transaction.

Show Child Properties

Value.GeocodeResponse object

If Request.GeocodeOptions.IncludeGeocoding is set to true (thus geocoding is executed), this object will be populated with a response.

Show Child Properties

Value.IndexingResponse object

If Request.IndexingOptions contains any specified parameters, this object will be populated with a response.

Show Child Properties

Value.CreditsRemaining decimal


{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "GeocodeResponse": {
      "GeocodedParsedDocument": "",
      "Code": "",
      "Message": ""
    },
    "IndexingResponse": {
      "Code": "",
      "Message": ""
    },
    "CreditsRemaining": 0
  }
}

Generate the Matching UI

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.
CustomValueIds can be set in the FilterCriteria and passed through in the background ONLY if there are no CustomValuePicklists specified in the request.

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 is `application/json`.

Request Body

UIOptions optional object

Object representing various options for generating the UI.

Show Child Properties

UIOptions.Username optional string

The username of the current user. *If you do not provide this, the user will be required to login when they view the page.

UIOptions.ShowFilterCriteria optional boolean

Allow the user to see/modify the filter criteria.

UIOptions.ExecuteImmediately optional boolean

Execute the query as soon as the page loads.

UIOptions.ShowBanner optional boolean

Show the banner containing your account logo inside the matching UI.

UIOptions.ShowWeights optional boolean

Allow the user to see/modify the category weights.

UIOptions.ShowDetailsButton optional boolean

Show a button that opens the 'details' popup containing detailed job/resume info.

UIOptions.ShowFindSimilar optional boolean

Adds a button in the Actions menu that matches other jobs/resumes similar to the current one.

UIOptions.ShowWebSourcing optional boolean

Include Sovren custom web sourcing in search/match results. Cannot be used for bimetric scoring.

UIOptions.ShowJobBoards optional boolean

Allow job boards in search/match results. Cannot be used for bimetric scoring. Must add credentials at My Sovren Portal

UIOptions.DefaultJobBoards optional string[]

The job boards to include in search/match results initially. Users can override after the initial search/match. Cannot be used for bimetric scoring. Must add credentials at My Sovren Portal. Optional values are:

Monster
CareerBuilder
Nexxt
WhoKnows
Web

UIOptions.ShowSavedSearches optional boolean

Allow the user to save custom searches or select from premade criteria templates.

UIOptions.Hooks optional object

Contains all the User Action Hooks for this session.

Show Child Properties

UIOptions.Hooks.Client optional object[]

The client-side User Action Hooks for this session.

Show Child Properties

UIOptions.Hooks.Client[i].LinkText optional string

Text to display on the button for the user action.

UIOptions.Hooks.Client[i].IsBulk optional boolean

Allows users to select multiple documents and perform this action on all of them at once. Note that this can only be set to true when you use a JSAction. UrlActions are not supported. See here for more info.

UIOptions.Hooks.Client[i].UrlAction optional object

A URL action to perform when the user clicks the button.

Show Child Properties

UIOptions.Hooks.Client[i].JsAction optional object

A Javascript action to perform when the user clicks the button.

Show Child Properties

UIOptions.Hooks.Client[i].JsAction.Target optional string

One of parent or opener, depending if you use an iFrame to show the Matching UI in your system, or if you open it in a separate tab/window.

UIOptions.Hooks.Client[i].JsAction.TargetOrigin optional string

The 'targetOrigin' parameter for the window.postMessage() call. For more information see here.

UIOptions.Hooks.Client[i].JsAction.Data optional any

Any data you want to be sent (in addition to document information) in the 'message' parameter for the window.postMessage() call. For more information see here.

UIOptions.Hooks.Server optional object[]

The server-side (HTTP POST) User Action Hooks for this session.

Show Child Properties

UIOptions.Hooks.Server[i].LinkText optional string

The text to display on the button for the user action.

UIOptions.Hooks.Server[i].Url optional string

The URL for an HTTP POST call to perform some action in your system.

UIOptions.Hooks.Server[i].CustomInfo optional any

Any data from your system that you need to associate with this session/action. This is sent (in addition to document information) in the POST body. For more information see here.

UIOptions.Hooks.Server[i].IsBulk optional boolean

Allows users to select multiple documents and perform this action on all of them at once. See here for more info.

UIOptions.Hooks.Sourcing optional object[]

The Sourcing (HTTP POST) User Action Hooks for this session.

Show Child Properties

UIOptions.CustomValuePicklists optional object[]

An array of picklists populated with custom values for users to select from and filter on.

Show Child Properties

UIOptions.CustomValuePicklists[i].Label optional string

The label that will appear above the picklist in the UI.

UIOptions.CustomValuePicklists[i].Options optional object[]

An array of custom values to be used as the options in the picklist.

Show Child Properties

UIOptions.SkillsAutoCompleteCustomSkillsList optional string[]

String[] of your custom skills list names. The builtin Sovren skills lists are always included.

SaasRequest required object

The SaaS request that defines the match/search. See the AI Match and AI Search endpoints for details.

Show Child Properties

ParseOptions optional object

Object representing parsing options to use when parsing resumes from external sources, such as job boards and Sovren custom web sourcing.

Show Child Properties

ParseOptions.Configuration optional string

ParseOptions.SkillsData optional string[]

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 optional string

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 optional object

All of the parameters that are supported in the normal parsing geocode options requests are supported. See Parse a Resume for more details.

{
  "UIOptions": {
    "Username": "",
    "ShowFilterCriteria": true,
    "ExecuteImmediately": false,
    "ShowBanner": true,
    "ShowWeights": true,
    "ShowDetailsButton": true,
    "ShowFindSimilar": true,
    "ShowWebSourcing": true,
    "ShowJobBoards": true,
    "DefaultJobBoards": [""],
    "ShowSavedSearches": true,
    "Hooks": {
        "Client": [
          {
              "LinkText": "",
              "IsBulk": false,
              "UrlAction": {
                  "Url": "",
                  "Target": ""
              },
              "JsAction": {
                  "Target": "",
                  "TargetOrigin": "",
                  "Data": {}
              }
          }
        ],
        "Server": [
          {
              "LinkText": "",
              "Url": "",
              "CustomInfo": {},
              "IsBulk": false
          }
        ],
        "Sourcing": [
          {
              "LinkText": "",
              "Url": "",
              "CustomInfo": {},
          }
        ]
    },
    "CustomValuePicklists": [
      {
        "Label": "",
        "Options": [
            {
                "Value": "",
                "Text": ""
            }
        ]
      }
    ],
    "SkillsAutoCompleteCustomSkillsList" : [
      ""
    ]
  },
  "SaasRequest": {
    "IndexIdsToSearchInto": [
      ""
    ],
    //...
  },
  "ParseOptions" : {
    "Configuration": "",
    "SkillsData": [
      ""
    ],
    "NormalizerData": ""
   },
   "GeocodeOptions": {
     //...
   }
}

Response Body

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.

{
  "url": "",
  "expires_in": 0
}

Normalize a Parsed Resume

POST /v9/normalizer/resume

Normalize an existing JSON resume string.

This feature is not recommended and only available in special cases. Reach out to support@sovren.com for more information.

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 is `application/json`.

Request Body

ParsedDocument required string

The existing JSON parsed document to be normalized. This document must be output from the Sovren Resume Parser.

NormalizerData optional string

{
  "ParsedDocument": "",
  "NormalizerData": ""
}

Response Body

Info object

Information explaining the outcome of the transaction.

Show Child Properties

Value object

Contains response data for the transaction.

Show Child Properties

{
  "Info": {
    "Code": "",
    "Message": ""
  },
  "Value": {
    "NormalizedParsedDocument": "",
    "CreditsRemaining": 0,
    "NormalizerVersion": ""
  }
}

Geocode a Parsed Document

POST /v9/geocoder

Get or insert geocode coordinate values (latitude/longitude) for a parsed 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 is `application/json`.

Request Body

ParsedDocument required string

The existing parsed JSON text of either a Resume or a Job Order.

Provider conditional string

The Provider you wish to use to geocode the postal address (current options are "Google" or "Bing"). If not specified, we will default to Google.
If passing a ProviderKey, this field is required.

ProviderKey conditional string

The Provider Key for the specified Provider. If using Bing you must specify your own provider key.

PostalAddress optional object

Show Child Properties

GeoCoordinates optional object

Show Child Properties