API Technical Specs
Getting Started
First Steps
- 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.
- 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.
- 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.
Programming Language | GitHub |
---|---|
C# | https://github.com/sovren/sovren-dotnet |
Java | https://github.com/sovren/sovren-java |
Code Samples
Here we have a few code samples to get you up and running quickly:
- c#
- javascript
- python
- ruby
- java
- php
- node
//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
Endpoint | Base Cost** |
---|---|
POST /v10/parser/* | 1 credit |
POST /v10/index/{indexid}/* | 1 credit per document |
POST /v10/scorer/bimetric | 1 credit + ((number of target documents - 1) * 0.1) |
POST /v10/matcher/* | Free when initiated by a human end-user for a single transaction. For more details see the Acceptable Use Policy. |
POST /v10/searcher | Free when initiated by a human end-user for a single transaction. For more details see the Acceptable Use Policy. |
POST /v10/geocoder/* | 1 credit if using the default options 0.1 credits if you specify your own provider key |
POST /v10/geocodeAndIndex/* | 2 credit if using the default options 1.1 credits if you specify you own provider key 1 credit if you specify the latitude/longitude |
GET /v10/index/{indexId}/count | 1 credit |
GET /v10/index | 10 credits |
GET /v10/account | 1 credit. You should only call this endpoint if you are batch parsing, and you should only call it in compliance with our Acceptable Use Policy. |
POST /v10/formatter/resume | 0.5 credits |
Data Enrichment APIs | |
POST /v10/skills/extract | 0.1 credits + (0.04 per 1k characters) |
POST /v10/*/normalize | 0.1 credits * number of input items |
POST /v10/*/autocomplete | 0.1 credits |
POST /v10/*/lookup | 0.1 credits |
GET /v10/*/taxonomy | 1 credit |
POST /v10/ontology/* | 10 credits |
Customer Portal Only | |
Download Indexed Documents | (100 credits + 1 per 5k documents) for each index selected |
**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
Add-On/Feature | Cost | Applicable Endpoints |
---|---|---|
Job Title Normalization | 0.2 credits | POST /v10/parser/* POST /v10/searcher |
Skills Normalization | 0.1 credits, does not apply when using V1 taxonomy | POST /v10/parser/* |
Geocoding | 1 credit with the default options † 0.1 credits if you specify your own provider key † | POST /v10/parser/* POST /v10/matcher/* POST /v10/searcher |
† While matching and searching, each location included in the FilterCriteria will be charged the specified add-on cost.
Endpoints
Data Center | ||
---|---|---|
US | https://rest.resumeparsing.com/v10/ | |
EU | https://eu-rest.resumeparsing.com/v10/ | |
AU | https://au-rest.resumeparsing.com/v10/ |
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
It is unnecessary to include these headers when using the Sovren SDK. Your AccountId and ServiceKey will be entered when creating aSovrenClient
Header | Data Type | Required | Description |
---|---|---|---|
Sovren-AccountId | string | Yes | The Account ID that is provided to you when establishing your Service Account. |
Sovren-ServiceKey | string | Yes | The Service key that is provided to you for access to your account’s available credits. |
Content-Type | string | Yes | Indicates the media type of the incoming request body. The only supported value is application/json . |
Sovren-TrackingTag | string | No | An 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 of our documentation site you can change the API version of the documentation.
Release notes can be found here.
API Version | Status | Notes |
---|---|---|
Version 10 | Suggested (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 9 | Suggested (existing customers/projects) | This version is still receiving updates and is fully supported. Full release notes 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. |
408 - Request Timeout | Timeout | The transaction reached its timeout limit. |
409 - Conflict | DuplicateAsset | The request could not be completed due to a conflict with the current state of the target resource. |
413 - Payload Too Large | RequestTooLarge | The 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 Entity | ConversionException | The request made was syntactically correct, but the provided document was unable to be converted to text. |
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 | An unexpected issue occurred (these are extremely rare). |