Skip to main

API Technical Specs

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

Geocode and Index a Job Order

POST /v10/geocodeAndIndex/joborder

Geocodes a document and adds it to an index.

Request Body

JobDatarequiredobject
The parsed JobData from the Sovren Job Order Parser. See Parse a Job Order
IndexIfGeocodeFailsoptionalbool
Indicates whether or not the document should still be added to the index if the geocode request fails. Default is false.
GeocodeOptionsrequiredobject
Settings to determine the form of geocoding for the transaction.
GeocodeOptions.Provideroptionalstring
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.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 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.Latitudeoptionalfloat
The latitude coordinate value.
GeocodeOptions.GeoCoordinates.Longitudeoptionalfloat
The longitude coordinate value.
IndexingOptionsrequiredobject
Settings to specify where to store the document.

Skills Normalization must be included to index documents using V2 Skills Taxonomy. These algorithms ignore raw skills and only consider the normalized skill concepts for skills category scoring. This leads to improved scoring and ranking because normalization produces less false negatives than simple exact keyword matching.
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.UserDefinedTagsoptionalstring[]
The user-defined tags you want the document to have.

Sample Request

{ ... 
"JobData" :  "...","IndexIfGeocodeFails" :  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

MissingParameter- A required parameter wasn't provided

InvalidParameter- A parameter was incorrectly specified

AuthenticationError- An error occurred with the credentials provided

Unauthorized- Your account doesn't have permission to perform this operation

DataNotFound- Data with the specified name wasn't found
Info.Messagestring
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.JobDataoptionalobject
The main output from the Sovren Job Parser containing the geocoded coordinates.
Value.JobData.CurrentJobIsManagementbool
Whether or not the job is a management position. Used by Sovren for AI Matching.
Value.JobData.HighestManagementScoreinteger
The management score. Used by Sovren for AI Matching.
Value.JobData.ManagementLevelbool
The management level. Used by Sovren for AI Matching.
Value.JobData.ExecutiveTypebool
What kind of executive position the job is, if any. Used by Sovren for AI Matching.
Value.JobData.MinimumYearsinteger
The minimum years experience for the job, if listed. Used by Sovren for AI Matching.
Value.JobData.MaximumYearsinteger
The maximum years experience for the job, if listed. Used by Sovren for AI Matching.
Value.JobData.MinimumYearsManagementinteger
The minimum years of management experience, if listed. Used by Sovren for AI Matching.
Value.JobData.MaximumYearsManagementinteger
The maximum years of management experience, if listed. Used by Sovren for AI Matching.
Value.JobData.RequiredDegreestring
The required educational degree, if listed. Used by Sovren for AI Matching.
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].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].FoundInstring
Where the skill was found.
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].FoundInstring
Where the skill was found.
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.SkillsData[i].Taxonomies[j].PercentOfOverallinteger
The percent (0-100) of skills found in the document that belong to this taxonomy.
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.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.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 Job Order.
Value.GeocodeResponse.Messagestring
Maps to the Response.Message parameter of a Geocode Job Order.
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 Job Order Transaction.
Value.IndexingResponse.Messagestring
Maps to the Response.Message parameter of a Index a Job Order Transaction.

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,"HighestManagementScore" :  0,"ManagementLevel" :  "string","ExecutiveType" :  "string","MinimumYears" :  0,"MaximumYears" :  0,"MinimumYearsManagement" :  0,"MaximumYearsManagement" :  0,"RequiredDegree" :  "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",[ ... 
{
[ ... 
{
[ ... 
{
"Required" :  true,[ ... 
{
"Required" :  true,"Id" :  "string","Name" :  "string","FoundIn" :  "string","ExistsInText" :  true
}
],
"Id" :  "string","Name" :  "string","FoundIn" :  "string","ExistsInText" :  true
}
],
"PercentOfOverall" :  0,"PercentOfParent" :  0,"SubTaxonomyId" :  "string","SubTaxonomyName" :  "string"
}
],
"Id" :  "string","Name" :  "string","PercentOfOverall" :  0
}
]
}
],
{ ... 
"PlainText" :  "string","DocumentLanguage" :  "string","DocumentCulture" :  "string","ParserSettings" :  "string","DocumentLastModified" :  "2020-11-02"
},
[ ... 
"string"
]
},
{ ... 
"Code" :  "","Message" :  ""
},
{ ... 
"Code" :  "","Message" :  ""
}
}
}