Documentation Release Notes Downloads FAQs

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.

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. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Request Body

{
  "DocumentAsBase64String": "",
  "OutputHtml": false,
  "OutputRtf": false,
  "OutputCandidateImage": false,
  "OutputPdf": false,
  "Configuration": "",
  "RevisionDate": "",
  "SkillsData": [
    "string"
  ],
  "NormalizerData": "",
  "GeocodeOptions": {
    "IncludeGeocoding": false,
    "Provider": "",
    "ProviderKey": "",
    "PostalAddress": {
      "CountryCode": "",
      "PostalCode": "",
      "Region": "",
      "Municipality": "",
      "AddressLine": ""
    },
    "GeoCoordinates": {
      "Latitude": 0,
      "Longitude": 0
    }
  },
  "IndexingOptions": {
    "IndexId": "",
    "DocumentId": "",
    "CustomIds": [
      ""
    ]
  }
}
Field Data Type Required Description
DocumentAsBase64String string Yes 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.
Configuration string No 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.
RevisionDate string No Optional date, in YYYY-MM-DD format, representing the "current" or "as of" date used during parsing. This is useful when parsing older resumes.
OutputHtml boolean No When true, the original file is converted to HTML and stored in the Html property.
OutputRtf boolean No When true, the original file is converted to RTF and stored in the Rtf property.
OutputPdf boolean No When true, the original file is converted to PDF and stored in the Pdf property as a byte array.
OutputCandidateImage boolean No 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.
SkillsData string[] No 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 string No 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.IncludeGeocoding bool No 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.Provider string No 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.ProviderKey string No The Provider Key for the specified Provider. If using Bing you must specify your own provider key.
GeocodeOptions.PostalAddress object No 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.CountryCode string No The ISO 3166-1 alpha-2 code indicating the country for the postal address.
GeocodeOptions.PostalAddress.PostalCode string No The postal code (or zip code) for the postal address
GeocodeOptions.PostalAddress.Region string No The region (i.e. State for U.S. addresses) for the postal address.
GeocodeOptions.PostalAddress.Municipality string No The municipality (i.e. City for U.S. addresses) for the postal address
GeocodeOptions.PostalAddress.AddressLine string No The address line (i.e. Street address for U.S. address) for the postal address
GeocodeOptions.GeoCoordinates object No 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.Latitude float No The latitude coordinate value.
GeocodeOptions.GeoCoordinates.Longitude float No The longitude coordinate value.
IndexingOptions.IndexId string No 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.
IndexingOptions.DocumentId string No 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.
IndexingOptions.CustomIds string[] No The custom ids you want the document to have.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "CandidateImage": "",
        "CandidateImageExtension": "",
        "FileType": "",
        "Text": "",
        "TextCode": "",
        "Html": "",
        "HtmlCode": "",
        "Rtf": "",
        "RtfCode": "",
        "CreditsRemaining": 0,
        "FileExtension": "",
        "Pdf": "",
        "PdfCode": "",
        "ParsedDocument": "",
        "ScrubbedParsedDocument": "",
        "GeocodeResponse": {
            "Code": "",
            "Message": ""
        },
        "IndexingResponse": {
          "Code": "",
          "Message": ""
        }
    }
}
Field Data Type Description
Info.Code string 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 - A successful transaction that contains warnings in the parsed document result

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.Message string This message further describes the code providing additional detail.
Value.ParsedDocument string The parser results in XML or JSON string format. The type is determined by the ACCEPT header in the request.
Value.ScrubbedParsedDocument string This property is the Value.ParsedDocument with all of the PII scrubbed out.
Value.FileType string The input file type that was submitted through the ParseResumeRequest.
Value.Text string The plain text of the parsed resume.
Value.TextCode string A response code indicating the status of the conversion to text. See Document Conversion Result Codes for a complete list.
Value.Html string HTML version of the input file, if OutputHtml was set to true.
Value.HtmlCode string A response code indicating the status of the conversion to HTML. See Document Conversion Result Codes for a complete list.
Value.Rtf string RTF version of the input file, if OutputRtf was set to true.
Value.RtfCode string A response code indicating the status of the conversion to RTF. See Document Conversion Result Codes for a complete list.
Value.Pdf string The base 64 encoded string of the PDF version of the input file, if OutputPdf was set to true.
Value.PdfCode string A response code indicating the status of the conversion to PDF. See Document Conversion Result Codes for a complete list.
Value.CreditsRemaining decimal 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.FileExtension string The recommended file extension of the input file.
Value.CandidateImage string If a candidate photo was extracted, it will be output in this field as a base 64 encoded string of the byte array.
Value.CandidateImageExtension string If a candidate photo was extracted, the appropriate file extension for the photo will be output for this field (e.g. ".png").
Value.GeocodeResponse object If Request.GeocodeOptions.IncludeGeocoding is set to true (thus geocoding is executed), this object will be populated with a response.
Value.GeocodeResponse.Code string Maps to the Response.Code parameter of a Geocode Transaction.
Value.GeocodeResponse.Message string Maps to the Response.Message parameter of a Geocode Transaction.
Value.IndexingResponse object If Request.IndexingOptions contains any specified paramters, this object will be populated with a response.
Value.IndexingResponse.Code string Maps to the Response.Code parameter of a Index a Document Transaction.
Value.IndexingResponse.Message string Maps to the Response.Message parameter of a Index a Document Transaction.

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.

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. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Request Body

{
  "DocumentAsBase64String": "",
  "Configuration": {
    "CountryCode": "",
    "Language": "",
    "KnownType": "",
    "IncludeRecruitingTerms": false,
    "IncludeSupplementalText": false,
    "PreferShorterJobTitles": false
  },
  "OutputHtml": false,
  "OutputRtf": false,
  "OutputPdf": false,
  "RevisionDate": "",
  "SkillsData": [
    ""
  ],
  "NormalizerData": "",
  "GeocodeOptions": {
    "IncludeGeocoding": false,
    "Provider": "",
    "ProviderKey": "",
    "PostalAddress": {
      "CountryCode": "",
      "PostalCode": "",
      "Region": "",
      "Municipality": "",
      "AddressLine": ""
    },
    "GeoCoordinates": {
      "Latitude": 0,
      "Longitude": 0
    }
  },
  "IndexingOptions": {
    "IndexId": "",
    "DocumentId": "",
    "CustomIds": [
      ""
    ]
  }
}
Field Data Type Required Description
DocumentAsBase64String string Yes 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.
Configuration.CountryCode string No 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.Language string No An ISO 639-1 two letter language code indicating the language to be assumed in cases where the language cannot be automatically detected.
Configuration.KnownType string No Optionally specify a known type to enable special processing. Possible values include: Indeed, Stride, JOB_SUBMISSION_REPLY_TO_CANDIDATE
Configuration.IncludeRecruitingTerms boolean No 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.IncludeSupplementalText boolean No 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.PreferShorterJobTitles boolean No 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".
OutputHtml boolean No When true, the original file is converted to HTML and stored in the Html property.
OutputRtf boolean No When true, the original file is converted to RTF and stored in the Rtf property.
OutputPdf boolean No When true, the original file is converted to PDF and stored in the Pdf property as a byte array.
RevisionDate string No Optional date, in YYYY-MM-DD format, representing the "current" or "as of" date used during parsing. This is useful when parsing older documents.
SkillsData string[] No 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 string No Will be used in a future release.
GeocodeOptions.IncludeGeocoding bool No 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.Provider string No 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.ProviderKey string No The Provider Key for the specified Provider. If using Bing you must specify your own provider key.
GeocodeOptions.PostalAddress object No 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.CountryCode string No The ISO 3166-1 alpha-2 code indicating the country for the postal address.
GeocodeOptions.PostalAddress.PostalCode string No The postal code (or zip code) for the postal address
GeocodeOptions.PostalAddress.Region string No The region (i.e. State for U.S. addresses) for the postal address.
GeocodeOptions.PostalAddress.Municipality string No The municipality (i.e. City for U.S. addresses) for the postal address
GeocodeOptions.PostalAddress.AddressLine string No The address line (i.e. Street address for U.S. address) for the postal address
GeocodeOptions.GeoCoordinates object No 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.Latitude float No The latitude coordinate value.
GeocodeOptions.GeoCoordinates.Longitude float No The longitude coordinate value.
IndexingOptions.IndexId string No 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.
IndexingOptions.DocumentId string No 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.
IndexingOptions.CustomIds string[] No The custom ids you want the document to have.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "FileType": "",
        "Text": "",
        "TextCode": "",
        "Html": "",
        "HtmlCode": "",
        "Rtf": "",
        "RtfCode": "",
        "CreditsRemaining": 0,
        "FileExtension": "",
        "Pdf": "",
        "PdfCode": "",
        "ParsedDocument": "",
        "GeocodeResponse": {
            "Code": "",
            "Message": ""
        },
        "IndexingResponse": {
          "Code": "",
          "Message": ""
        }
    }
}
Field Data Type Description
Info.Code string 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.Message string This message further describes the code providing additional detail.
Value.FileType string The input file type that was submitted through the ParseJobOrderRequest.
Value.ParsedDocument string The parser results in XML or JSON string format. The type is determined by the ACCEPT header in the request.
Value.Text string The plain text of the parsed job order.
Value.TextCode string A response code indicating the status of the conversion to Text.
Value.Html string HTML version of the input file, if OutputHtml was set to true.
Value.HtmlCode string A response code indicating the status of the conversion to HTML.
Value.Rtf string RTF version of the input file, if OutputRtf was set to true.
Value.RtfCode string A response code indicating the status of the conversion to RTF.
Value.Pdf string The PDF version of the input file, if OutputPdf was set to true. The file bytes are in a Base64-encoded string.
Value.PdfCode string A response code indicating the status of the conversion to PDF.
Value.CreditsRemaining decimal 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.FileExtension string The recommended file extension of the input file.
Value.GeocodeResponse object If Request.GeocodeOptions.IncludeGeocoding is set to true (thus geocoding is executed), this object will be populated with a response.
Value.GeocodeResponse.Code string Maps to the Response.Code parameter of a Geocode Transaction.
Value.GeocodeResponse.Message string Maps to the Response.Message parameter of a Geocode Transaction.
Value.IndexingResponse object If Request.IndexingOptions contains any specified paramters, this object will be populated with a response.
Value.IndexingResponse.Code string Maps to the Response.Code parameter of a Index a Document Transaction.
Value.IndexingResponse.Message string Maps to the Response.Message parameter of a Index a Document Transaction.

Normalize a Parsed Resume

POST /v9/normalizer/resume

Normalize an existing XML or JSON resume string.

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. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Request Body

{
  "ParsedDocument": "",
  "NormalizerData": ""
}
Field Data Type Required Description
ParsedDocument string Yes The existing XML or JSON parsed document to be normalized. This document must be output from the Sovren Resume Parser.
NormalizerData string No 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": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "NormalizedParsedDocument": "",
        "CreditsRemaining": 0,
        "NormalizerVersion": ""
    }
}
Field Data Type Description
Info.Code string 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

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided
Info.Message string This message further describes the code providing additional detail.
Value.NormalizedParsedDocument string The normalized Parsed Document
Value.CreditsRemaining decimal 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.NormalizerVersion string The version of the normalizer that was used

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. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Request Body

{
  "Provider": "",
  "ProviderKey": "",
  "ParsedDocument": "",
  "PostalAddress": {
    "CountryCode": "",
    "PostalCode": "",
    "Region": "",
    "Municipality": "",
    "AddressLine": ""
  },
  "GeoCoordinates": {
    "Latitude": 0,
    "Longitude": 0
  }
}
Field Data Type Required Description
Provider string Conditional 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 string Conditional The Provider Key for the specified Provider. If using Bing you must specify your own provider key.
ParsedDocument string Yes The existing parsed XML or JSON text of either a Resume or a Job Order.

You must specify either a ParsedDocument or a PostalAddress in your GeoCodeRequest.
PostalAddress object No 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.
PostalAddress.CountryCode string No The ISO 3166-1 alpha-2 code indicating the country for the postal address.
PostalAddress.PostalCode string No The postal code (or zip code) for the postal address.
PostalAddress.Region string No The region (i.e. State for U.S. addresses) for the postal address.
PostalAddress.Municipality string No The municipality (i.e. City for U.S. addresses) for the postal address
PostalAddress.AddressLine string No The address line (i.e. Street address for U.S. address) for the postal address
GeoCoordinates object No 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.
GeoCoordinates.Latitude float No The latitude coordinate value.
GeoCoordinates.Longitude float No The longitude coordinate value.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "GeoCodeResult": "",
        "CreditsRemaining": 0
    }
}
Field Data Type Description
Info.Code string 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

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

InsufficientData - The address provided doesn't have enough granularity to be geocoded effectively

CoordinatesNotFound - The geocoding provider couldn't find any coordinates matching the provided address
Info.Message string This message further describes the code providing additional detail.
Value.GeoCodeResult string The results of the geocoding transaction. The result will be your ParsedDocument (either Resume or Job Order) with the geocoding results embedded in it.
Value.CreditsRemaining decimal 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.