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.

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

//using Newtonsoft.Json;
//go to /Downloads/v9/Schemas/ResumeSchema.zip to download necessary Resume.cs file

byte[] fileBytes = File.ReadAllBytes("resume.docx"); 
dynamic data = new 
{ 
    DocumentAsBase64String = Convert.ToBase64String(fileBytes)
    //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 = JsonConvert.SerializeObject(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 = 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);
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.
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.

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)