Skip to main

API Technical Specs

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

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 | AU 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 Body

DocumentAsBase64Stringrequiredstring
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.
RevisionDaterequiredstring
Mandatorydate, 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.
OutputHtmlrequiredboolean
When true, the original file is converted to HTML and stored in the Html property.
OutputRtfrequiredboolean
When true, the original file is converted to RTF and stored in the Rtf property.
OutputPdfrequiredboolean
When true, the original file is converted to PDF and stored in the Pdf property as a byte array.
Configurationrequiredobject
Options that influence parser behavior.
Configuration.CountryCoderequiredstring
A 2-letter ISO 3166 code (or comma-delimited list of such codes) indicating the country to be assumed in cases where the location cannot be automatically detected. If multiple codes are specified, the first one is given the highest priority.
Configuration.Languagerequiredstring
An ISO 639-1 two letter language code indicating the language to be assumed in cases where the language cannot be automatically detected.
Configuration.KnownTyperequiredstring
Optionally specify a known type to enable special processing. Possible values include:
  • Indeed
  • Stride
  • JOB_SUBMISSION_REPLY_TO_CANDIDATE
Configuration.IncludeRecruitingTermsrequiredboolean
Recruiting terms in skills and job titles are ignored by default, because these terms often appear in job orders that are unrelated to recruiting. If this job order is for a recruiting or human resources position, then set this to true.
Configuration.IncludeSupplementalTextrequiredboolean
The parser defaults to extracting data from only the text that precedes the place in job orders where they transition from describing the job itself to describing the company, hiring policies, background checks, benefits, etc. This division of text normally works well, but in some job orders it can occur in the wrong place. Set this to true to allow the parser to extract data from all of the text.
Configuration.PreferShorterJobTitlesrequiredboolean
The parser defaults to returning full job titles. Setting this option to true will shorten job titles by excluding trailing phrases that do not include job words, so that "Vice President" would be returned instead of "Vice President, Information Systems".
SkillsDatarequiredstring[]
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.
NormalizerDatarequiredstring
Will be used in a future release.
GeocodeOptionsrequiredobject
Get or insert geocode coordinate values (latitude/longitude) during the parse transaction.
GeocodeOptions.IncludeGeocodingrequiredbool
When set to true we will automatically geocode the address that is parsed out leveraging an api call to our/geocode endpoint, and thus will be charged accordingly. This parameter defaults to false.
GeocodeOptions.Providerrequiredstring
The Provider you wish to use to geocode the postal address (current options are "Google", "Bing", or "None"). If not specified, we will default to Google. If you are just trying to update the postal address in the document, please set this to "None".
If passing "Google" or "Bing", ProviderKey is requried.
GeocodeOptions.ProviderKeyrequiredstring
The Provider Key for the specified Provider. If using Bing you must specify your own provider key.
GeocodeOptions.PostalAddressrequiredobject
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.
GeocodeOptions.PostalAddress.CountryCoderequiredstring
The ISO 3166-1 alpha-2 code indicating the country for the postal address.
GeocodeOptions.PostalAddress.PostalCoderequiredstring
The postal code (or zip code) for the postal address
GeocodeOptions.PostalAddress.Regionrequiredstring
The region (i.e. State for U.S. addresses) for the postal address.
GeocodeOptions.PostalAddress.Municipalityrequiredstring
The municipality (i.e. City for U.S. addresses) for the postal address
GeocodeOptions.PostalAddress.AddressLinerequiredstring
The address line (i.e. Street address for U.S. address) for the postal address
GeocodeOptions.GeoCoordinatesrequiredobject
The geographic coordinates (latitude/longitude) for your postal address. Use this if you already have latitude/longitude coordinatesand simply wish to add them to your parsed document. If provided, these values will be inserted into your ParsedDocument and the address included in the ParsedDocument (if present), will not be modified.
GeocodeOptions.GeoCoordinates.Latituderequiredfloat
The latitude coordinate value.
GeocodeOptions.GeoCoordinates.Longituderequiredfloat
The longitude coordinate value.
IndexingOptionsrequiredobject
When your account is enabled for Matching/Searching you can automatically index documents during the parse transactions.
IndexingOptions.IndexIdrequiredstring
When your account is enabled for Matching/Searching you can automatically index documents during the parse transactions. This determines what index to place the parsed document in. This is case-insensitive.
IndexingOptions.DocumentIdrequiredstring
When your account is enabled for Matching/Searching you can automatically index documents during the parse transactions. This determines what id to give to the parsed document. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.
IndexingOptions.CustomIdsrequiredstring[]
The custom ids you want the document to have.

Sample Request

{ ... 
"DocumentAsBase64String" :  "","RevisionDate" :  "","OutputHtml" :  false,"OutputRtf" :  false,"OutputPdf" :  false,{ ... 
"CountryCode" :  "","Language" :  "","KnownType" :  "","IncludeRecruitingTerms" :  false,"IncludeSupplementalText" :  false,"PreferShorterJobTitles" :  false
},
[ ... 
""
],
"NormalizerData" :  "",{ ... 
"IncludeGeocoding" :  false,"Provider" :  "","ProviderKey" :  "",{ ... 
"CountryCode" :  "","PostalCode" :  "","Region" :  "","Municipality" :  "","AddressLine" :  ""
},
{ ... 
"Latitude" :  0,"Longitude" :  0
}
},
{ ... 
"IndexId" :  "","DocumentId" :  "",[ ... 
""
]
}
}

Response Body

Infoobject
Information explaining 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

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.FileTypestring
The input file type that was submitted through the ParseJobOrderRequest.
Value.Textstring
The plain text of the parsed job order.
Value.TextCodestring
A response code indicating the status of the conversion to Text.
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.
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.
Value.Pdfstring
The PDF version of the input file, if OutputPdf was set to true. The file bytes are in a Base64-encoded string.
Value.PdfCodestring
A response code indicating the status of the conversion to PDF.
Value.FileExtensionstring
The recommended file extension of the input file.
Value.CreditsRemainingdecimal
The number of remaining credits is returned with every response. Please ensure that you set up monitoring of this value to ensure that you don't experience an outage by letting your credits reach 0.
Value.GeocodeResponseobject
If Request.GeocodeOptions.IncludeGeocoding is set to true (thus geocoding is executed), this object will be populated with a response.
Value.GeocodeResponse.Codestring
Maps to the Response.Code parameter of a Geocode Transaction.
Value.GeocodeResponse.Messagestring
Maps to the Response.Message parameter of a Geocode Transaction.
Value.IndexingResponseobject
If Request.IndexingOptions contains any specified parameters, this object will be populated with a response.
Value.IndexingResponse.Codestring
Maps to the Response.Code parameter of a Index a Document Transaction.
Value.IndexingResponse.Messagestring
Maps to the Response.Message parameter of a Index a Document Transaction.

Sample Response

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