API Technical Specs

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.
   • Resume Parsing
   • Job Parsing
   • AI Matching/Searching
   • Bimetric Scoring
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. If programming in Java or C#, install the Sovren SDK using the links in the section below. Otherwise, review the code samples and endpoint documentation throughout the rest of this page.

Sovren SDK

The easiest and fastest way to get started programming your integration to the Version 10 API is by using our SDKs. We currently offer SDKs in C# and Java, with others to follow. This is, by far, the best way to use our software. You can parse a document with as little as 3 lines of code!

Each GitHub link below has installation instructions, documentation, and many code examples to help get you started. The SDKs can also be found directly using your preferred package manager.

Code Samples

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

//this code uses the official SDK (see https://github.com/sovren/sovren-dotnet)
SovrenClient client = new SovrenClient("12345678", "abcdefghijklmnopqrstuvwxyz", DataCenter.US);
 
//A Document is an unparsed File (PDF, Word Doc, etc)
Document doc = new Document("resume.docx");
 
//when you create a ParseRequest, you can specify many configuration settings
//in the ParseOptions. See https://sovren.com/technical-specs/latest/rest-api/resume-parser/api/
ParseRequest request = new ParseRequest(doc, new ParseOptions());
 
try
{
    ParseResumeResponse response = await client.ParseResume(request);
    //if we get here, it was 200-OK and all operations succeeded
 
    //now we can use the response from Sovren to ouput some of the data from the resume
    Console.WriteLine("Name: " + response.EasyAccess().GetCandidateName()?.FormattedName);
    Console.WriteLine("Email: " + response.EasyAccess().GetEmailAddresses()?.FirstOrDefault());
    Console.WriteLine("Phone: " + response.EasyAccess().GetPhoneNumbers()?.FirstOrDefault());
}
catch (SovrenException e)
{
    //this was an outright failure, always try/catch for SovrenExceptions when using the SovrenClient
    Console.WriteLine($"Error: {e.SovrenErrorCode}, Message: {e.Message}");
}

Standard Transaction Cost

**Note: Additional costs may be incurred if any of the following scenarios apply:

• Any of the add-ons described in the table below are enabled/used for the transaction.
• Sovren Sourcing is enabled (credit cost is increased 15%).
• You use a deprecated version of the API as per the Terms of Service.

Add-On Cost Per Transaction

^† While matching and searching, each location included in the FilterCriteria will be charged the specified add-on cost.

Endpoints

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

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: