Skip to main

API Technical Specs

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

Parse a Resume

POST /v9/parser/resume

Parse a single Resume/CV.

Notes

  • You can try this endpoint out in your Swagger page https://(your-server)/swagger/ui/index#!/Parser/Parser_ParseResume
  • 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.
  • 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 Body

DocumentAsBase64Stringrequiredstring
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.
RevisionDaterequiredstring
Mandatorydate, 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.
OutputHtmloptionalbool
When true, the original file is converted to HTML and stored in the Html property.
OutputRtfoptionalbool
When true, the original file is converted to RTF and stored in the Rtf property.
OutputPdfoptionalbool
When true, the original file is converted to PDF and stored in the Pdf property as a byte array.
OutputCandidateImageoptionalbool
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.
Configurationoptionalstring
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.
SkillsDataoptionalstring[]
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.
NormalizerDataoptionalstring
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).

Sample Request

{ ... 
"DocumentAsBase64String" :  "","RevisionDate" :  "","OutputHtml" :  false,"OutputRtf" :  false,"OutputPdf" :  false,"OutputCandidateImage" :  false,"Configuration" :  "",[ ... 
""
],
"NormalizerData" :  ""
}

Response Body

Infoobject
Explains the outcome of the transaction.
Info.Codestring
A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

WarningsFoundDuringParsing - Parsing was successful. This is not an error code. This is an advanced level message about the document, not about the parsing. For more information, refer to the ResumeQuality section in the parsed document output and to the documentation here.

PossibleTruncationFromTimeout - The timeout occurred before the document was finished parsing which can result in truncation

ConversionException - There was an issue converting the document

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided
Info.Messagestring
This message further describes the code providing additional detail.
Valueobject
Contains response data for the transaction.
Value.ParsedDocumentstring
The parser results in JSON string format.
Value.ScrubbedParsedDocumentstring
This property is the Value.ParsedDocument with all of the Personally Identifiable Information (PII) fields such as first name, last name, email addresses, phone numbers, etc. scrubbed out.
Value.FileTypestring
The input file type that was submitted through the ParseResumeRequest.
Value.Textstring
The plain text of the parsed resume.
Value.TextCodestring
A response code indicating the status of the conversion to text. See Document Conversion Result Codes for a complete list.
Value.Htmlstring
HTML version of the input file, if OutputHtml was set to true.
Value.HtmlCodestring
A response code indicating the status of the conversion to HTML. See Document Conversion Result Codes for a complete list.
Value.Rtfstring
RTF version of the input file, if OutputRtf was set to true.
Value.RtfCodestring
A response code indicating the status of the conversion to RTF. See Document Conversion Result Codes for a complete list.
Value.Pdfstring
The base 64 encoded string of the PDF version of the input file, if OutputPdf was set to true.
Value.PdfCodestring
A response code indicating the status of the conversion to PDF. See Document Conversion Result Codes for a complete list.
Value.CandidateImagestring
If a candidate photo was extracted, it will be output in this field as a base 64 encoded string of the byte array.
Value.CandidateImageExtensionstring
If a candidate photo was extracted, the appropriate file extension for the photo will be output for this field (e.g. ".png").
Value.FileExtensionstring
The recommended file extension of the input file.
Value.CreditsRemainingdecimal
Not used - always returns 0.

Sample Response

{ ... 
{ ... 
"Code" :  "","Message" :  ""
},
{ ... 
"ParsedDocument" :  "","ScrubbedParsedDocument" :  "","FileType" :  "","Text" :  "","TextCode" :  "","Html" :  "","HtmlCode" :  "","Rtf" :  "","RtfCode" :  "","Pdf" :  "","PdfCode" :  "","CandidateImage" :  "","CandidateImageExtension" :  "","FileExtension" :  "","CreditsRemaining" :  0
}
}