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 /v10/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.
DocumentLastModifiedrequiredstring
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.
OutputHtmloptionalboolean
When true, the original file is converted to HTML and stored in the Html property.
OutputRtfoptionalboolean
When true, the original file is converted to RTF and stored in the Rtf property.
OutputPdfoptionalboolean
When true, the original file is converted to PDF and stored in the Pdf property as a byte array.
Configurationoptionalobject
Options that influence parser behavior.
Configuration.CountryCodeoptionalstring
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.Languageoptionalstring
An ISO 639-1 two letter language code indicating the language to be assumed in cases where the language cannot be automatically detected.
Configuration.KnownTypeoptionalstring
Optionally specify a known type to enable special processing. Possible values include:
  • Indeed
  • Stride
  • JOB_SUBMISSION_REPLY_TO_CANDIDATE
Configuration.IncludeRecruitingTermsoptionalboolean
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.IncludeSupplementalTextoptionalboolean
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.PreferShorterJobTitlesoptionalboolean
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".
SkillsDataoptionalstring[]
Unavailable except in special cases. Please reach out tosupport@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.
GeocodeOptionsoptionalobject
Get or insert geocode coordinate values (latitude/longitude) during the parse transaction.
GeocodeOptions.IncludeGeocodingoptionalbool
When set to true we will automatically geocode the address that is parsed out leveraging an api call to our/geocodeendpoint,and thus will be charged accordingly. This parameter defaults to false.
GeocodeOptions.Provideroptionalstring
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.
GeocodeOptions.ProviderKeyoptionalstring
The Provider Key for the specified Provider. If using Bing you must specify your own provider key.
GeocodeOptions.PostalAddressoptionalobject
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.CountryCodeoptionalstring
The ISO 3166-1 alpha-2 code indicating the country for the postal address.
GeocodeOptions.PostalAddress.PostalCodeoptionalstring
The postal code (or zip code) for the postal address
GeocodeOptions.PostalAddress.Regionoptionalstring
The region (i.e. State for U.S. addresses) for the postal address.
GeocodeOptions.PostalAddress.Municipalityoptionalstring
The municipality (i.e. City for U.S. addresses) for the postal address
GeocodeOptions.PostalAddress.AddressLineoptionalstring
The address line (i.e. Street address for U.S. address) for the postal address
GeocodeOptions.GeoCoordinatesoptionalobject
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. 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.Latitudeoptionalfloat
The latitude coordinate value.
GeocodeOptions.GeoCoordinates.Longitudeoptionalfloat
The longitude coordinate value.
IndexingOptionsoptionalobject
When your account is enabled for Matching/Searching you can automatically index documents during the parse transactions.
IndexingOptions.IndexIdoptionalstring
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.DocumentIdoptionalstring
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.UserDefinedTagsoptionalstring[]
The user-defined tags you want the document to have.

Sample Request

{ ... 
DocumentAsBase64String :  "",DocumentLastModified :  "",OutputHtml :  false,OutputRtf :  false,OutputPdf :  false,{ ... 
CountryCode :  "",Language :  "",KnownType :  "",IncludeRecruitingTerms :  false,IncludeSupplementalText :  false,PreferShorterJobTitles :  false,
},
[ ... 
"",
],
{ ... 
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.Codeoptionalstring
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.Messageoptionalstring
This message further describes the code providing additional detail.
Info.TransactionIdstring
The (GUID) id for a specific API transaction. Use this when contacting support@sovren.com about issues.
Info.EngineVersionstring
The version of the parsing/matching engine running under-the-hood.
Info.ApiVersionstring
The version of the API.
Info.TotalElapsedMillisecondsinteger
How long the transaction took on Sovren's server, in milliseconds. If the transaction takes longer to complete on the client side, that extra duration is solely network latency.
Info.TransactionCostdecimal
How many credits the transaction costs.How many credits the transaction costs.
Info.CustomerDetailsobject
Information about the customer who made the API call.
Value.CustomerDetails.AccountIdstring
The AccountId for the account.
Value.CustomerDetails.Namestring
The customer name on the account.
Value.CustomerDetails.IPAddressstring
The client IP Address where the API call originated.
Value.CustomerDetails.Regionstring
The region for the account, also known as the 'Data Center'.
Value.CustomerDetails.CreditsRemainingdecimal
The number of credits remaining to be used by the account.
Value.CustomerDetails.CreditsUseddecimal
The number of credits used by the account.
Value.CustomerDetails.MaximumConcurrentRequestsinteger
The number of requests that can be made at one time. If using sub-accounts, this is the maximum number of concurent requests across all accounts, not just this single sub-account.
Value.CustomerDetails.ExpirationDatedate
The date that the current credits expire.
Valueobject
Contains response data for the transaction.
Value.ParsingResponseobject
The status of the parse transaction.
Value.ParsingResponse.Codestring
Value.ParsingResponse.Messagestring
A short human-readable description explaining the Code value.
Value.GeocodeResponseobject
If geocoding was requested in the ParseOptions.GeocodeOptions the status of the geocode transaction will be output here.
Value.GeocodeResponse.Codestring
Value.GeocodeResponse.Messagestring
A short human-readable description explaining the Code value.
Value.IndexingResponseobject
If indexing was requested in the ParseOptions.IndexingOptions the status of the index transaction will be output here.
Value.IndexingResponse.Codestring
Value.IndexingResponse.Messagestring
A short human-readable description explaining the Code value.
Value.JobDataoptionalobject
The main output from the Sovren Job Parser.
Value.JobData.CurrentJobIsManagementbool
Whether or not the job is a management position. Used by Sovren for AI Matching.
Value.JobData.HighestManagementScoreobject
The management score, or null. Used by Sovren for AI Matching.
Value.JobData.HighestManagementScore.Valueinteger
The management score.
Value.JobData.ManagementLevelstring
The management level. Used by Sovren for AI Matching. One of:
  • None
  • Low
  • Mid
  • High
Value.JobData.ExecutiveTypestring
What kind of executive position the job is, if any. Used by Sovren for AI Matching. One of:
  • NONE
  • ADMIN
  • ACCOUNTING
  • BUSINESS_DEV
  • EXECUTIVE
  • FINANCIAL
  • GENERAL
  • IT
  • LEARNING
  • MARKETING
  • OPERATIONS
Value.JobData.MinimumYearsobject
The minimum years experience for the job, or null. Used by Sovren for AI Matching.
Value.JobData.MinimumYears.Valueinteger
The minimum years experience for the job.
Value.JobData.MaximumYearsobject
The maximum years experience for the job, or null. Used by Sovren for AI Matching.
Value.JobData.MaximumYears.Valueinteger
The maximum years experience for the job.
Value.JobData.MinimumYearsManagementobject
The minimum years of management experience, or null. Used by Sovren for AI Matching.
Value.JobData.MinimumYearsManagement.Valueinteger
The minimum years of management experience.
Value.JobData.MaximumYearsManagementobject
The maximum years of management experience, or null. Used by Sovren for AI Matching.
Value.JobData.MaximumYearsManagement.Valueinteger
The maximum years of management experience.
Value.JobData.RequiredDegreestring
The required educational degree, if listed. Used by Sovren for AI Matching.
Value.JobData.StartDateobject
The start date for the job, or null.
Value.JobData.StartDate.Valuedate
The start date for the job.
Value.JobData.EndDateobject
The end date for the job, or null.
Value.JobData.EndDate.Valuedate
The end date for the job.
Value.JobData.BillRateobject
The bill rate for the job, if listed.
Value.JobData.BillRate.Amountdecimal
The amount per UnitOfTime
Value.JobData.BillRate.Currencystring
The currency code. For example: "USD"
Value.JobData.BillRate.UnitOfTimestring
One of:
  • hour
  • day
  • week
  • month
  • year
Value.JobData.PayRateobject
The bill rate for the job, if listed.
Value.JobData.PayRate.Amountdecimal
The amount per UnitOfTime
Value.JobData.PayRate.Currencystring
The currency code. For example: "USD"
Value.JobData.PayRate.UnitOfTimestring
One of:
  • hour
  • day
  • week
  • month
  • year
Value.JobData.JobDescriptionstring
The full job description.
Value.JobData.JobRequirementsstring
Any requirement listed by the job.
Value.JobData.JobTitlesobject
The job titles found in the job. Used by Sovren for AI Matching.
Value.JobData.JobTitles.MainJobTitlestring
The main/overall job title.
Value.JobData.JobTitles.JobTitlestring[]
All job titles found in the job description.
Value.JobData.EmployerNamesobject
The employer names found in the job.
Value.JobData.EmployerNames.MainEmployerNamestring
The main/overall employer name.
Value.JobData.EmployerNames.EmployerNamestring[]
All employer names found in a job description.
Value.JobData.Degreesobject[]
The educational degrees found listed in the job. Used by Sovren for AI Matching.
Value.JobData.Degrees[i].Namestring
The name of the educational degree.
Value.JobData.Degrees[i].Typestring
The type of the educational degree.
Value.JobData.SchoolNamesstring[]
Any school names listed in the job.
Value.JobData.CertificationsAndLicensesstring[]
Any certifications/licenses listed in the job. Used by Sovren for AI Matching.
Value.JobData.LanguageCodesstring[]
Any languages listed in the job. Used by Sovren for AI Matching.
Value.JobData.CurrentLocationobject
The location of the job, if listed. Used by Sovren for AI Matching.
Value.JobData.CurrentLocation.CountryCodestring
The 2-letter ISO 3166 country code.
Value.JobData.CurrentLocation.PostalCodestring
The Postal or Zip code.
Value.JobData.CurrentLocation.Regionsstring[]
The Regions/Districts/States.
Value.JobData.CurrentLocation.Municipalitystring
The City/Municipality/Town.
Value.JobData.CurrentLocation.StreetAddressLinesstring
Street address lines.
Value.JobData.CurrentLocation.GeoCoordinatesobject
If geocoding has been done, this is the lat/lon for the location.
Value.JobData.CurrentLocation.GeoCoordinates.Latitudedecimal
The latitude, in degrees.
Value.JobData.CurrentLocation.GeoCoordinates.Longitudedecimal
The longitude, in degrees.
Value.JobData.CurrentLocation.GeoCoordinates.Sourcestring
The geocoding source, such as Google or Bing.
Value.JobData.TermsOfIntereststring[]
Terms of interest listed in the job.
Value.JobData.Ownersstring[]
Any owners of the job posting, if listed.
Value.JobData.SkillsDataobject[]
The skills found in the job. Used by Sovren for AI Matching.
Value.JobData.SkillsData[i].Rootstring
The name of the skills list that these taxonomies belong to.
Value.JobData.SkillsData[i].Taxonomiesobject[]
The skills taxonomies found in a resume.
Value.JobData.SkillsData[i].Taxonomies[j].Idstring
The id of the skills taxonomy.
Value.JobData.SkillsData[i].Taxonomies[j].Namestring
The human-readable name.
Value.JobData.SkillsData[i].Taxonomies[j].PercentOfOverallinteger
The percent (0-100) of skills found in the document that belong to this taxonomy.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomiesobject[]
The subtaxonomy children of this taxonomy (more specific groupings of skills).
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].SubTaxonomyIdstring
The id of the subtaxonomy.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].SubTaxonomyNamestring
The human-readable name of the subtaxonomy.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].PercentOfOverallinteger
The percent (0-100) of skills found in the subtaxonomy compared to all subtaxonomies.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].PercentOfParentinteger
The percent (0-100) of skills found in the subtaxonomy compared to other subtaxonomies in the parent taxonomy
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skillsobject[]
The skills from the subtaxonomy that were found.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Requiredbool
True if this skill was listed as 'required' on the job description.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Idstring
The Id of the skill.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Namestring
The name of the skill.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].ExistsInTextstring
Whether or not this skill was found verbatim in the text.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variationsobject[]
The variations (synonyms) of this skill that were found.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].Requiredbool
True if this skill was listed as 'required' on the job description.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].Idstring
The Id of the skill.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].Namestring
The name of the skill.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].ExistsInTextstring
Whether or not this skill was found verbatim in the text.
Value.JobData.JobMetadataobject
Metadata about the parsed job
Value.JobData.JobMetadata.PlainTextstring
The plain text that was used for parsing.
Value.JobData.JobMetadata.DocumentLanguagestring
The two-letter ISO 639-1 code for the language the document was written in.
Value.JobData.JobMetadata.DocumentCulturestring
The xx-XX language/culture value for the parsed document.
Value.JobData.JobMetadata.ParserSettingsstring
The full parser settings that were used during parsing.
Value.JobData.JobMetadata.DocumentLastModifieddate
The last-revised/last-modified date that was provided for the document. This was used to calculate all of the important metrics about skills and jobs.
Value.JobData.JobMetadata.SovrenSignaturestring[]
A digital signature used to ensure there is no tampering between parsing and indexing. This prevents Sovren from storing any PII in the AI Matching engine.
Value.JobData.UserDefinedTagsstring[]
A list of user-defined tags that are assigned to this resume. These are used to filter search/match queries in the AI Matching Engine.

NOTE: you may add/remove these prior to indexing. This is the only property you may modify prior to indexing.
Value.ConversionMetadataobject
Information about converting the document to plain text
Value.ConversionMetadata.DetectedTypestring
The file type that was detected.
Value.ConversionMetadata.SuggestedFileExtensionstring
The suggested extension based on the DetectedType.
Value.ConversionMetadata.OutputValidityCodestring
The computed validity based on the source text. This will indicate whether a document looks like a legitimate resume or not. See here for more details.
Value.ConversionMetadata.ElapsedMillisecondsstring
How long the document conversion took, in milliseconds.
Value.ConversionMetadata.DocumentHashstring
The MD5 hash of the document bytes.
Value.Conversionsobject
Any additional conversions you requested will be here (eg: PDF or HTML).
Value.Conversions.PDFstring
If requested by ParseOptions.OutputPdf, this is the document converted to a PDF. This is a byte[] as a Base64-encoded string.
Value.Conversions.HTMLstring
If requested by ParseOptions.OutputHtml, this is the document converted to HTML.
Value.Conversions.RTFstring
If requested by ParseOptions.OutputRtf, this is the document converted to RTF.
Value.Conversions.CandidateImagestring
If a candidate photo was extracted, it will be output here. This is a byte[] as a Base64-encoded string.
Value.Conversions.CandidateImageExtensionstring
If a candidate photo was extracted, the appropriate file extension for the photo will be output for this field (e.g. ".png").
Value.ParsingMetadataobject
Information about the parsing transaction.
Value.ParsingMetadata.ElapsedMillisecondsstring
How long it took to parse the document, in milliseconds.
Value.ParsingMetadata.TimedOutbool
Whether or not the transaction timed out. If this is true, the returned data may be incomplete.
Value.ParsingMetadata.TimedOutAtMillisecondsobject
If TimedOut is true, this is how much time was spent parsing before the timeout occurred. Otherwise null.
Value.ParsingMetadata.TimedOutAtMilliseconds.Valueinteger
If TimedOut is true, this is how much time was spent parsing before the timeout occurred.

Sample Response

{ ... 
{ ... 
Code :  "string",Message :  "string",TransactionId :  "string",EngineVersion :  "string",ApiVersion :  "string",TotalElapsedMilliseconds :  0,TransactionCost :  0,{ ... 
AccountId :  "string",Name :  "string",IPAddress :  "string",Region :  "string",CreditsRemaining :  0,CreditsUsed :  0,ExpirationDate :  "2021-12-31",MaximumConcurrentRequests :  0,
},
},
{ ... 
{ ... 
CurrentJobIsManagement :  true,{ ... 
Value :  0,
},
ManagementLevel :  "string",ExecutiveType :  "string",{ ... 
Value :  0,
},
{ ... 
Value :  0,
},
{ ... 
Value :  0,
},
{ ... 
Value :  0,
},
RequiredDegree :  "string",{ ... 
Value :  "2020-11-02",
},
{ ... 
Value :  "2020-11-02",
},
{ ... 
Amount :  0,Currency :  "string",UnitOfTime :  "string",
},
{ ... 
Amount :  0,Currency :  "string",UnitOfTime :  "string",
},
JobDescription :  "string",JobRequirements :  "string",{ ... 
MainJobTitle :  "string",[ ... 
"string",
],
},
{ ... 
MainEmployerName :  "string",[ ... 
"string",
],
},
[ ... 
{
Name :  "string",Type :  "string",
},
],
[ ... 
"string",
],
[ ... 
"string",
],
[ ... 
"string",
],
{ ... 
CountryCode :  "string",PostalCode :  "string",[ ... 
"string",
],
Municipality :  "string",[ ... 
"string",
],
{ ... 
Latitude :  0,Longitude :  0,Source :  "string",
},
},
[ ... 
"string",
],
[ ... 
"string",
],
[ ... 
{
Root :  "string",[ ... 
{
Id :  "string",Name :  "string",PercentOfOverall :  0,[ ... 
{
PercentOfOverall :  0,PercentOfParent :  0,SubTaxonomyId :  "string",SubTaxonomyName :  "string",[ ... 
{
Id :  "string",Name :  "string",ExistsInText :  true,Required :  true,[ ... 
{
Id :  "string",Name :  "string",ExistsInText :  true,Required :  true,
},
],
},
],
},
],
},
],
},
],
{ ... 
PlainText :  "string",DocumentLanguage :  "string",DocumentCulture :  "string",ParserSettings :  "string",DocumentLastModified :  "2020-11-02",[ ... 
"string",
],
},
[ ... 
"string",
],
},
{ ... 
Code :  "Success",Message :  "string",
},
{ ... 
Code :  "Success",Message :  "string",
},
{ ... 
Code :  "Success",Message :  "string",
},
{ ... 
DetectedType :  "string",SuggestedFileExtension :  "string",OutputValidityCode :  "string",ElapsedMilliseconds :  0,DocumentHash :  "string",
},
{ ... 
PDF :  "string",HTML :  "string",RTF :  "string",CandidateImage :  "string",CandidateImageExtension :  "string",
},
{ ... 
ElapsedMilliseconds :  0,TimedOut :  true,{ ... 
Value :  0,
},
},
},
}