Skip to main

API Technical Specs

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

Getting Started

Data Enrichment

The Data Enrichment APIs provide various functionalities around Sovren's knowledge base of professions and skills. The API can be used to:

  • Extract and normalize skills from any HR-related text to pre-populate skill profiles.
  • Improve analytics by standardizing skill and job data to Sovren's comprehensive, cross-lingual taxonomies.
  • Import Sovren's taxonomies of skills and professions in your organization's tools and processes.
  • Create smart matching solutions by leveraging Sovren's extensive knowledge base on synonyms and profession-skill relations.
  • Automatically enrich job architectures and job catalogues with suggestions of relevant skills.
  • Generate skill-based recommendations of (non-obvious) job transitions.
  • Understand the skill gap between two professions, or between a current skill set and an aspired next role.
  • Extract skills from training descriptions, and leverage those for targeted upskilling recommendations.

Skills API

Has the following functionality:

  • extract skills from any text
  • normalize skill descriptions to Sovren's V2 Skills Taxonomy
  • autocomplete user input to skills in the taxonomy
  • export the structure of the taxonomy
  • translate skills between any of the supported languages

Professions API

Has the following functionality:

  • normalize job titles to Sovren's Professions Taxonomy, and to external standards such as O*NET and ISCO
  • autocomplete user input to professions in the taxonomy
  • export the structure of the taxonomy
  • translate professions between any of the supported languages

Ontology API

Has the following functionality:

  • suggest relevant skills for a given a profession
  • suggest relevant professions for a given a skill set
  • infer the skill gap between two professions, or between a skill set and a profession

Rate Limits

Unlike Sovren's other APIs, the Data Enrichment APIs are rate-limited on a number-of-requests-per-time-period basis. This means that any given second/minute/hour you are allowed to have N requests. Any requests after the limit of N is reached are rejected until the time period elapses and you are allowed to have N more requests for the next time period. The specific values for each endpoint are provided below:

EndpointRequest LimitTime Period
POST /v10/skills/extract81 second
POST /v10/skills/normalize161 second
POST /v10/professions/normalize131 second
POST /v10/*/autocomplete161 second
POST /v10/*/lookup161 second
GET /v10/*/taxonomy101 hour
GET /v10/*/metadata101 hour
POST /v10/ontology/*161 second


Sovren's Skills API provides various ways to interact with the Skills Taxonomy:

  • Extract and normalize skills from any provided text
  • Autocomplete to skills in the taxonomy
  • Download the full skills taxonomy (synonyms excluded)
  • Lookup translations of a skill

Supported Languages

These are the supported languages, their coverage level and the corresponding ISO code for API requests/responses.

LanguageTierISO Code
Chinese (Simplified)3zh
Chinese (Traditional)3zh_TW

Coverage Per Tier

TierLanguage SkillsIT SkillsProfessional and Soft Skills

Full means all skills have a translation and the coverage of synonyms is extensive.

High means all common skills have a translation and the most common synonyms are covered.

Basic means all common skills have a translation and the coverage of synonyms is lower than the other tiers.

Context validation is only applied for Tier 1 languages.

About the Skills Taxonomy

Definition of a Skill

Skills are defined broadly as any kind of capability, knowledge or behavior that contributes directly to professional performance.

Structure of the Skills Taxonomy

The taxonomy has three layers: categories, skills and synonyms/variations.

The categories layer represents the following distinction:

  • Professional skills include professional activities, techniques, tools, as well as areas of knowledge and specializations.
  • IT skills include programming languages as wel as software tooling.
  • Soft skills include personality traits and behaviors relevant to professional performance.
  • Languages are simply knowledge of individual languages.

The skills layer represents skill 'concepts', each of which has an ID and a translation in the supported languages (see the Translations section below for details). This layer is language-independent; it contains the skills themselves, not the various terms and phrases through which they are described.

The synonyms/variations layer contains the various terms and phrases that can be used to denote a skill in a given language. This layer is language-specific. Each skill is linked to one or more synonyms in each of the supported languages.

Concept Granularity and Concise Descriptions

The taxonomy is designed for usage in natural language processing software. It therefore contains concise skill descriptions (usually 1-3 words), which are likely to match skill descriptions in CVs and vacancies. For the same reason, the taxonomy contains skills with various levels of granularity (e.g. both Finance and Real Estate Finance). Skill descriptions are generally noun phrases, as treating all activities related to an area of expertise as separate skills would introduce too much granularity. So instead of distinguishing three separate skills for Running/Training/Tuning Machine Learning Models, there is just a single skill called Machine Learning. Similarly, to keep the descriptions concise, prefixes like Working with or Expertise in are omitted. So Working with Gas Pipelines simply becomes Gas Pipelines.


All skills have descriptions in Tier 1 languages, except those that represent country-specific certifications (US-only).

Taxonomy Updates

The taxonomy is updated four times per year: March, June, September and December. There might be patch releases in between, but these will only concern the synonym-level, so the structure of the taxonomy won't be affected.


Sovren's Professions API helps organizing job data according to established, international taxonomies of professions. It deals with spelling variations, synonyms and noise removal. Thus, it enables reliable analytics and effective matching of people and jobs.

Purposes of Job Title Normalization

Normalizing job title data to a taxonomy makes it possible to:

  • Correlate talent data from different sources and different languages
  • Reliably compare data from different sources, for instance your talent pool versus market demand
  • Match people and jobs based on a standard vocabulary, thereby increasing conversion

Supported Taxonomies

Job titles can be mapped onto the following taxonomies:

  • Sovren's Profession Normalization Taxonomy (an established, cross-lingual, data-driven taxonomy)
  • ISCO-2008
  • KLDB-2020
  • ONET-2019
  • (Deprecated) ONET-2010
  • UK-SOC-2010

Supported Languages

These are the supported languages for the Professions API and their corresponding ISO code for use in API requests/responses.

LanguageISO Codes for API InputISO Codes for API Output (OutputLanguage request parameter)
Englishenen, en_US, en_GB
Portugueseptpt, pt_BR, pt_PT


The Ontology API provides insights into the relations of objects from our Sovren's knowledge graph, in particular professions and skills. It works in combination with Sovren's Professions API and Skills API, which provide functionalities around extraction, normalization and autocompletion for profession and skill data. The endpoints of the Ontology API operate on the level of IDs; they do not return the descriptions of professions and skills. To translate IDs into descriptions, and vice versa, the Professions API and Skills API can be used.

Supported Languages

The Ontology API is language agnostic. The language support is therefore limited to those languages that are supported by both the Skills API and Professions APIs. These are currently:

  • English
  • French
  • German
  • Dutch
  • Spanish
  • Italian
  • Portuguese
  • Polish
  • Japanese
  • Chinese