Documentation Release Notes Downloads FAQs

Sovren REST API

Getting Started

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

//using Newtonsoft.Json;
//click here to download necessary Resume.cs file

var fileBytes = File.ReadAllBytes("resume.docx"); 
dynamic data = new 
{ 
    DocumentAsBase64String = Convert.ToBase64String(fileBytes)
    //other options here
};

string url = "https://rest.resumeparsing.com/v9/parser/resume"; 
string json = JsonConvert.SerializeObject(data); 

string strResume = "";

using (var 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);
    strResume = JsonConvert.DeserializeObject<dynamic>(result).Value.ParsedDocument;
}

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);
var serializer = new XmlSerializer(typeof(Sovren.External.Resume));
using (var sr = new StringReader(node.InnerXml))
{
    resume = serializer.Deserialize(sr) as Sovren.External.Resume;
}

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

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 https://eu-rest.resumeparsing.com

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.
Version 8 Deprecated and do not integrate to this (6/26/2018) Version 9 is very similar to version 8, but a few bug fixes required breaking changes. Full release notes can be found here.
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.

Data Format

Our REST API accepts and returns content in JSON or XML. The Content-Type header is required, and indicates your request's content type. Our API supports JSON (application/json) and XML (application/xml). The Accept header controls what data format the response will be returned in. Our API defaults to JSON (application/json) but also supports XML (application/xml).

Notes

  • The AI Matching endpoints only support JSON (application/json) in both the Content-Type and Accept headers.

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 returning ≤ 100 results. After the first 100 results it costs 1 credit for each 50 results. For example returning 200 results would cost 2 credits. (Additional credits can be consumed when geocoding is enabled that follow the same structure as the POST /geocoder endpoint))
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/apply/session 1 credit (2 credits with matching enabled)

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

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