Skip to main

API Technical Specs

Learn how to configure and leverage our services to achieve your toughest recruiting needs.
SaaS     |

Getting Started

Legacy SOAP documentation can be found here. Deprecated

First Steps

  1. This documentation is for technical details about the API only. Before starting your integration, you should read the Product Documentation for the products you plan to integrate with. We will show you the most important information on how to create a quick and successful integration.
  2. Then, read 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 Software Disclosure.
  3. Review the code samples in the section below.

Code Samples

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

  • c#
  • javascript
  • python
  • ruby
  • java
  • php
  • node
//go to https://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 https://sovren.com/technical-specs/v9/rest-api/resume-parser/api/)
};
   
//use https://eu-rest.resumeparsing.com/v9/parser/resume if your account is in the EU data center
//for self-hosted use https://{your-server}/v9/parser/resume
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 https://sovren.com/technical-specs/latest/rest-api/resume-parser/api/
    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);
All above code samples are provided without warranty and are not necessarily indicative of best practices.

Standard Transaction Cost

EndpointCost
POST /v9/parser/resume1 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/joborder1 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/bimetric1 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/searcherFree 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/geocodeAndIndex0.5 credits (if you use your own provider key, or specify your own latitude and longitude the transaction is free).
GET /v9/index/(indexId)/count1 credit. There should never be a need to call this endpoint. You control when documents are added/deleted from your indexes, so you should always know how many documents are in any given index.
Deprecated GET /v9/index/(indexId)1 credit (as of December 1, 2020). There should never be a need to call this endpoint. You should be keeping track of what indexes you have created and deleted. Adding a document to an index that doesn't exist will return a 404 - Not Found error.
GET /v9/index10 credits (as of December 1, 2020). There should never be a need to call this endpoint. You should be keeping track of what indexes you have created and deleted. Adding a document to an index that doesn't exist will return a 404 - Not Found error.
GET /v9/account1 credit (as of December 1, 2020). You should only call this endpoint if you are batch parsing, and you should only call it in compliance with our Acceptable Use Policy.

Note: Credit cost is increased 15% when Sovren Sourcing is enabled.

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

Endpoints

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 CenterEU Data Center
HTTPShttps://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.


Request Headers

HeaderData TypeRequiredDescription
Sovren-AccountIdstringYesThe Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKeystringYesThe Service key that is provided to you for access to your account’s available credits.
Content-TypestringYesIndicates the media type of the incoming request body. The only supported value is application/json.
Sovren-TrackingTagstringNoAn optional value that you can use for tracking API usage in the Customer Portal. Comma-separated values are accepted here, and the max length is 100 characters.

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-left 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 four 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.
  • Beta - this version is currently in beta-testing. There may be some final minor tweaks before the official release.
  • 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 VersionStatusNotes
Version 10Suggested (new customers/projects)This is the same as v9 under-the-hood, but features an entirely new/modern input/output structure and official SDKs. For more information see Version 9 vs Version 10. Release notes can be found here.
Version 9Suggested (existing customers/projects)This version is still receiving updates and is fully supported. Full release notes can be found here.
Version 7.5Deprecated (6/26/2018)If you're still using the version 7.5 of the API we recommend upgrading straight to version 10. Reach out to support@sovren.com to start the conversation.

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 CodeInfo.CodeDescription
200 - OKSuccess, WarningsFoundDuringParsing, PossibleTruncationFromTimeout, SomeErrorsThe transaction was successful
400 - Bad RequestMissingParameter, InvalidParameter, InsufficientData, DataNotFound, CoordinatesNotFound, ConstraintErrorUnable to process request
401 - UnauthorizedAuthenticationError, UnauthorizedThe AccountId and/or ServiceKey were invalid
403 - ForbiddenN/AThe request was made using http instead of https.
404 - Not FoundDataNotFoundThe requested asset wasn't found.
409 - ConflictDuplicateAssetThe request could not be completed due to a conflict with the current state of the target resource.
413 - Payload Too LargeRequestTooLargeThe request is too large to be processed by the server. The max file size is ~6MB on disk. Files larger than this are either not resumes/jobs, or are scanned images of resumes/jobs. Scanned images are not supported by Sovren, so they need to be OCR'ed prior to sending to Sovren to parse.
422 - Unprocessable EntityConversionExceptionThe request made was syntactically correct, but the provided document was unable to be converted to text.
429 - Too Many RequestsTooManyRequestsYour 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 ErrorUnhandledExceptionAn unexpected issue occurred (these are extremely rare).