Release Notes Downloads FAQs

Sovren REST API

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);

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.

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.
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, ConversionException An unexpected issue occurred, or was unable to convert the document to text (these are extremely rare)