API FAQs Downloads

Sovren REST API

Legacy SOAP documentation can be found here. Deprecated

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.

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

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

//go to http://docs.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 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 = 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 http://docs.sovren.com/API/Rest/Parsing
    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.

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
Deprecated GET /v9/index/{indexId} 1 credit (as of December 1, 2020)
GET /v9/index 10 credits (as of December 1, 2020)
GET /v9/account 1 credit (as of December 1, 2020)

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.

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 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. Full release notes can be found here.
Version 8 Deprecated and do not integrate to this (6/26/2018) Do not integrate to v8. If you are using v8, click here to view the upgrade path.
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. The upgrade path 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.
409 - Conflict DuplicateAsset The request could not be completed due to a conflict with the current state of the target resource.
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).

Parse a Resume

POST /v9/parser/resume

Parse a single Resume/CV.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • This service is designed to parse resumes/CVs. It assumes that all files passed to it are resumes/CVs. It does not attempt to detect whether a document is a resume/CV or not. It should not be used to try to extract information from other types of documents.
  • This service supports all commercially viable document formats used for text documents (image formats are not supported). The service does not support parsing of image files (such as TIFF, JPG) or scanned images within supported document file formats. Always send the original file, not the result of copy/paste, not a conversion by some other software, not a scanned image, and not a version marked up with recruiter notes or other non-resume information. Be aware that if you pass garbage into the service, then you are likely to get garbage out. The best results are always obtained by parsing the original resume/CV file.
  • If you are running batch transactions (i.e. iterating through files in a folder), make sure that you do not try to reparse a file if you get an exception back from the service since you will get the same result each time and credits will be deducted from your account.
  • Batch transactions must adhere to our Acceptable Use Policy.
  • Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

Request Headers

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.

Request Body

DocumentAsBase64String required string
A Base64 encoded string of the resume file bytes. This should use the standard 'base64' encoding as defined in RFC 4648 Section 4 (not the 'base64url' variant). .NET users can use the Convert.ToBase64String(byte[]) method.
RevisionDate required string
Mandatory date, in YYYY-MM-DD format, so that the Parser knows how to interpret dates in the document that are expressed as "current" or "as of" or similar. To find out why this is so important and how to calculate/find it, read here. Failing to pass a RevisionDate, or passing RevisionDates that are clearly improbable, may result in rejection of data and/or additional charges, and will utterly decimate the usefulness of AI Matching. Use of the RevisionDate field is subject to the Acceptable Use Policy.
OutputHtml optional bool
When true, the original file is converted to HTML and stored in the Html property.
OutputRtf optional bool
When true, the original file is converted to RTF and stored in the Rtf property.
OutputPdf optional bool
When true, the original file is converted to PDF and stored in the Pdf property as a byte array.
OutputCandidateImage optional bool
When true, if the document contains inline images, the image that is most likely to be a photo of the candidate is returned as a byte array.
Configuration optional string
Optional parser configuration string to be used for parsing. If not specified, the default parser configuration will be used. For more information regarding the parser configuration string and assistance generating one, refer to the Parser Configuration Documentation.
SkillsData optional string[]
Unavailable except in special cases. Please reach out to support@sovren.com. String[] of your custom skills list names and the Sovren "builtin" skills list. If no list is provided the Sovren builtin skills list will be used. The parser automatically detects language and looks for a corresponding skills list in that language, if no match is found this list is ignored.
NormalizerData optional string
Unavailable except in special cases. Please reach out to support@sovren.com. Name of your custom normalization data file. If no list is provided the Sovren builtin skills list will be used (english only). When using custom normalization files the language to be used is determined by the Parser (the default fall back language is English if the Parser cannot find a match).
GeocodeOptions optional object
Get or insert geocode coordinate values (latitude/longitude) during the parse transaction.
Show Child Properties
IndexingOptions optional object
When your account is enabled for Matching/Searching you can automatically index documents during the parse transactions.
Show Child Properties

Response Body

Info object
Explains the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Parse a Job Order

POST /v9/parser/joborder

Parse a single Job Order.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • This service is designed to parse job orders. It assumes that all files passed to it are job orders. It does not attempt to detect whether a document is a job order or not. It should not be used to try to extract information from other types of documents.
  • This service supports all commercially viable document formats used for text documents (image formats are not supported). The service does not support parsing of image files (such as TIFF, JPG) or scanned images within supported document file formats. Always send the original file, not the result of copy/paste, not a conversion by some other software, not a scanned image, and not a version marked up with recruiter notes or other non-job order information. Be aware that if you pass garbage into the service, then you are likely to get garbage out. The best results are always obtained by parsing the original job order file.
  • If you are running batch transactions (i.e. iterating through files in a folder), make sure that you do not try to reparse a file if you get an exception back from the service since you will get the same result each time and credits will be deducted from your account.
  • Batch transactions must adhere to our Acceptable Use Policy.
  • Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

Request Headers

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.

Request Body

DocumentAsBase64String required string
A Base64 encoded string of the job order file bytes. This should use the standard 'base64' encoding as defined in RFC 4648 Section 4 (not the 'base64url' variant). .NET users can use the Convert.ToBase64String(byte[]) method.
RevisionDate required string
Mandatory date, in YYYY-MM-DD format, representing the "current" or "as of" date used during parsing. This is useful when parsing older documents. Read more about this here.
OutputHtml optional boolean
When true, the original file is converted to HTML and stored in the Html property.
OutputRtf optional boolean
When true, the original file is converted to RTF and stored in the Rtf property.
OutputPdf optional boolean
When true, the original file is converted to PDF and stored in the Pdf property as a byte array.
Configuration optional object
Options that influence parser behavior.
Show Child Properties
SkillsData optional string[]
Unavailable except in special cases. Please reach out to support@sovren.com. String[] of your custom skills list names and the Sovren "builtin" skills list. If no list is provided the Sovren builtin skills list will be used. The parser automatically detects language and looks for a corresponding skills list in that language, if no match is found this list is ignored.
NormalizerData optional string
Will be used in a future release.
GeocodeOptions optional object
Get or insert geocode coordinate values (latitude/longitude) during the parse transaction.
Show Child Properties
IndexingOptions optional object
When your account is enabled for Matching/Searching you can automatically index documents during the parse transactions.
Show Child Properties

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Get Account Info

GET /v9/account

Retrieve your account's current information.

Notes

Request Headers

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.

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Create an Index

POST /v9/index/{indexId}

Creates an index.

Notes

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id to assign to the new index. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.

Request Body

IndexType required string
The type of the index. One of: {"Resume", "Job"}

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
An empty object.

Get an Index

Deprecated GET /v9/index/{indexId}

Retrieves information about a single index.

Notes

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id of the index (case-insensitive).

Response Body

Infp object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Get All Indexes

GET /v9/index

Retrieves information about all the indexes associated with your account.

Notes

Request Headers

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.

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object[]
Contains response data for the transaction.
Show Child Properties

Get Index Document Count

GET /v9/index/{indexId}/count

Retrieve the number of documents in a single index.

Notes

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id of the index (case-insensitive).

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Delete an Index

DELETE /v9/index/{indexId}

Delete an index.

Notes

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id of the index to delete (case-insensitive).

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
An empty object.

Index a Document

POST /v9/index/{indexId}/documents/{documentId}

Adds a single document to an index.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id for the index where the document should be added (case-insensitive).
documentId string The id to assign to the new document. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.

Request Body

ParsedDocument required string
Parsed JSON from the Sovren Resume or Job Order Parser.
CustomIds optional string[]
The custom ids you want the document to have.

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
An empty object.

Index Multiple Document

POST /v9/index/{indexId}/documents

Adds multiple documents to an index.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id for the index where the documents should be added (case-insensitive).

Request Body

DocumentId required string
The id of the current document. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.
ParsedDocument required string
Parsed JSON from the Sovren Resume or Job Order Parser.
CustomIds optional string[]
The custom ids you want the current document to have.

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object[]
An array of objects representing the individual document add responses. This is used to determine which documents failed in the event of an error.
Show Child Properties

Get a Document

GET /v9/index/{indexId}/documents/{documentId}

Retrieves a single document from an index.

Notes

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id for the index that contains the document (case-insensitive).
documentId string The id of the document to retrieve (case-insensitive).

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value string
The JSON document in string format.

Check if a Document Exists

HEAD /v9/index/{indexId}/documents/{documentId}

Check id a document exists in an index.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • This endpoint is not enabled for customers by default, as customers should track documents in their system.

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id for the index that contains the document (case-insensitive).
documentId string The id of the document to retrieve (case-insensitive).

Response

This api call has no reponse body, and utilizes the HttpStatusCode to specify success or failure.

Http Status Code Description
200 The document exists in the index
404 The document doesn't exist in the index
500 An unexpected error occured

Update Custom Values

PATCH /v9/index/{indexId}/documents/{documentId}

Updates the custom value ids for a document.

Notes

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id for the index that contains the document (case-insensitive).
documentId string The id of the document to update (case-insensitive).

Request Body

CustomValues required string[]
The custom value ids to add/remove/overwrite in the document.
Method required string
One of: "Delete", "Add", "Overwrite"

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
An empty object.

Delete a Document

DELETE /v9/index/{indexId}/documents/{documentId}

Delete a single document from an index.

Notes

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id for the index that contains the document (case-insensitive).
documentId string The id of the document to delete (case-insensitive).

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
An empty object.

Delete Multiple Documents

DELETE /v9/index/{indexId}/documents

Delete multiple documents from an index.

Notes

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string The id for the index that contains the documents (case-insensitive).

Request Body

Body required string[]
Each item in the array is the id of a document to delete from the index (case-insensitive).

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
An empty object.

Match by Document

POST /v9/matcher/documents

Match a parsed resume/job to resumes/jobs in certain indexes.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

Request Headers

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.

Request Body

ParsedDocument required string
Parsed JSON from the Sovren Resume or Job Order Parser.
IndexIdsToSearchInto required string[]
The ids of the indexes in which you want to find results (case-insensitive).
Take optional integer
The number of results to return.
CategoryWeights optional object[]
List of categories with weights that determine how the WeightedScore is calculated. It's important to specify these before the match so the query returns the top results using these weights. Only the categories included in this list will be used to calculate the WeightedScore.
Show Child Properties
Settings optional object
Options to control variations of job titles.
Show Child Properties
FilterCriteria optional object
Additional criteria for the result set.
Show Child Properties

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Match by Document Id

POST /v9/matcher/indexes/{indexId}/documents/{documentId}

Match a parsed resume/job to resumes/jobs in certain indexes.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • Documents parsed by an account without AI Matching enabled will never be able to be used for matching/searching. For more information on enabling AI Matching reach out to sales@sovren.com

Request Headers

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.

Path Parameters

Parameter Data Type Description
indexId string Id of the index that the source document is located in.
documentId string Id of the document to use as the source for matching (case-insensitive).

Request Body

IndexIdsToSearchInto required string[]
The ids of the indexes in which you want to find results (case-insensitive).
Take optional integer
The number of results to return.
CategoryWeights optional object[]
List of categories with weights that determine how the WeightedScore is calculated. It's important to specify these before the match so the query returns the top results using these weights. Only the categories included in this list will be used to calculate the WeightedScore.
Show Child Properties
Settings optional object
Options to control variations of job titles.
Show Child Properties
FilterCriteria optional object
Additional criteria for the result set.
Show Child Properties

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Search

POST /v9/searcher

Semantic search for resumes/jobs in certain indexes.

Notes

Request Headers

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.

Request Body

IndexIdsToSearchInto required string[]
The ids of the indexes in which you want to find results (case-insensitive).
PaginationSettings optional object
Choose which results to return from the list.
Show Child Properties
Settings optional object
Options to control variations of job titles.
Show Child Properties
FilterCriteria optional object
Additional criteria for the result set.
Show Child Properties

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Score a Set of Documents

POST /v9/scorer/bimetric

Score a parsed resume/job order to a group of resumes/job orders that aren't indexed. It's highly recommended to index all of your documents and leverage the speed and power of the AI Matching Engine and use one of the AI Match endpoints. This will also reduce your overall cost as the bimetric scoring is a higher charge per transaction.

Notes

Request Headers

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.

Request Body

SourceDocument required object
Parsed document to match against each of the target documents.
Show Child Properties
TargetDocuments required object[]
Array of parsed documents to be matched against the source document.
Show Child Properties
Settings optional object
Options to control variations of job titles.
Show Child Properties
CategoryWeights optional object[]
List of categories with weights that determine how the WeightedScore is calculated. It's important to specify these before the match so the query returns the top results using these weights. Only the categories included in this list will be used to calculate the WeightedScore.
Show Child Properties

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Geocode and Index a Document

POST /v9/geocodeAndIndex

Geocodes a document and adds it to an index.

Notes

Request Headers

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.

Request Body

ParsedDocument required string
Parsed JSON from the Sovren Resume or Job Order Parser.
IndexIfGeocodeFails optional bool
Indicates whether or not the document should still be added to the index if the geocode request fails. Default is false.
GeocodeOptions required object
Settings to determine the form of geocoding for the transaction.
Show Child Properties
IndexingOptions required object
Settings to specify where to store the document.
Show Child Properties

Request Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Generate the Matching UI

POST /ui/v9/matcher/documents
POST /ui/v9/matcher/indexes/{indexId}/documents/{documentId}
POST /ui/v9/searcher
POST /ui/v9/scorer/bimetric

Generate an HTML user interface for matching/searching that can be consumed in your client application.

Notes

  • Pagination settings in the SaasRequest such as Take or Skip will be ignored in the Matching UI results.
  • CustomValueIds can be set in the FilterCriteria and passed through in the background ONLY if there are no CustomValuePicklists specified in the request.

Request Headers

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.

Request Body

UIOptions optional object
Object representing various options for generating the UI.
Show Child Properties
SaasRequest required object
The SaaS request that defines the match/search. See the AI Match and AI Search endpoints for details.
Show Child Properties
ParseOptions optional object
Object representing parsing options to use when parsing resumes from external sources, such as job boards and Sovren custom web sourcing.
Show Child Properties
GeocodeOptions optional object
All of the parameters that are supported in the normal parsing geocode options requests are supported. See Parse a Resume for more details.

Response Body

url string
The endpoint to hit to get the generated Matching UI. The first request to this endpoint will automatically authenticate the user. Subsequent requests (who are not already authenticated) will require a login. This url will be valid for at least 24 hours.
expires_in integer
The number of seconds until the url auto-authentication expires.

Normalize a Parsed Resume

POST /v9/normalizer/resume

Normalize an existing JSON resume string.

This feature is not recommended and only available in special cases. Reach out to support@sovren.com for more information.

Notes

Request Headers

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.

Request Body

ParsedDocument required string
The existing JSON parsed document to be normalized. This document must be output from the Sovren Resume Parser.
NormalizerData optional string
Name of your custom normalization data file. If no list is provided the Sovren builtin skills list will be used (english only). When using custom normalization files the language to be used is determined by the Parser (the default fall back language is English if the Parser cannot find a match).

Response Body

Info object
Information explaining the outcome of the transaction.
Show Child Properties
Value object
Contains response data for the transaction.
Show Child Properties

Geocode a Parsed Document

POST /v9/geocoder

Get or insert geocode coordinate values (latitude/longitude) for a parsed document.

Notes

Request Headers

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.

Request Body

ParsedDocument required string
The existing parsed JSON text of either a Resume or a Job Order.
Provider conditional string
The Provider you wish to use to geocode the postal address (current options are "Google" or "Bing"). If not specified, we will default to Google.
If passing a ProviderKey, this field is required.
ProviderKey conditional string
The Provider Key for the specified Provider. If using Bing you must specify your own provider key.
PostalAddress optional object
The postal address you wish to geocode. For best results, specify as many of the PostalAddress fields as possible. If provided, this address will be used to get the geocode coordinates instead of the address included in the ParsedDocument (if present), however, the address in the ParsedDocument will not be modified.
Show Child Properties
GeoCoordinates optional object
The geographic coordinates (latitude/longitude) for your postal address. Use this if you already have latitude/longitude coordinates and simply wish to add them to your parsed document.