HireLayer Skills Normalizer · Skills Matching API
Skills Matching API that resolves free-text skills to a taxonomy
Send one skill, a compound string or a whole CV skills section. HireLayer Skills Normalizer returns every taxonomy skill the text names, in order, each with a stable id, a type, families and domains, and lists what it cannot resolve instead of guessing.
- Endpoints
- POST /skills/normalize · GET /skills
- Input
- Free text up to 5,000 characters
- Taxonomy
- 11,061 skills · 25 domains
- Billing
- 1 credit per call
What the Skills Matching API normalizes
Problems it solves
The same skill, many wordings
Candidates, recruiters and job ads describe one competency with different spellings, abbreviations and phrasings.
Search misses relevant profiles
An exact-match filter on free-text skills leaves out people who describe a skill differently.
Taxonomies are costly to maintain
Building and updating your own skill reference, with families and domains, is a project in itself.
01
One skill or a whole section
Send one skill, a compound string such as “Google Sheet/Excel” or a CV skills section with lines, bullets and lists, up to 5,000 characters.
02
Every skill, in text order
Each taxonomy skill named in the text comes back in the order of the text, with mention: the part of the text it was found in.
03
Resolved or unresolved, never guessed
There is no score or threshold to tune. A part of the text that matches no skill is listed in unresolved, with family hints.
04
Stable ids and types
Store and filter on id, such as excel. Each skill is typed hard, software, certification, soft or language, and named in French or English.
05
Families, domains and a broader skill
Skills sit in families and domains, the primary one first, and can name a broader skill to widen a search, such as Excel to Microsoft Office.
06
The whole taxonomy in one call
GET /api/v4/skills returns all 11,061 skills, most frequent in CVs first, across 25 domains and 236 families. Cache it on your side.
One skill or a whole skills section, in one request
| Input | text | skills[].name |
|---|---|---|
| One skill | react js | React |
| Compound string | Google Sheet/Excel | Google Sheets · Excel |
| Compound mention | MS Office (Word, Excel) | Microsoft Office · Word · Excel |
| Mixed list | React, Node, Cobol, project management | React · Node.js · COBOL · Project management |
Resolved, in text order
Each taxonomy skill comes back with a stable id and its mention, the part of the text it was found in.
Never guessed
No score or threshold: a part of the text that matches no skill is listed in unresolved, with family_hints.
{
"text": "Skills:\n- MS Office (Word, Excel, PowerPoint)\n- Payroll (ADP, Payfit)\n- Fluent English\n- Driving licence B\n- Attention to detail and organisation",
"language": "en"
}[
"Word", "Excel", "PowerPoint",
"Payroll", "ADP", "PayFit",
"English", "Driving licence B",
"Attention to detail", "Organization"
]Resolve a free-text skill string
Values below come from the API reference example. Field names and shapes match the live contract.
curl -X POST https://hirelayer.co/api/v4/skills/normalize \
-H "X-API-Key: $HIRELAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Google Sheet/Excel","language":"en"}'{
"language": "en",
"skills": [
{
"id": "google_sheets",
"name": "Google Sheets",
"type": "software",
"mention": "Google Sheet",
"families": [
{ "id": "office_software", "name": "Office software", "domain_id": "administration_office" },
{ "id": "data_analysis", "name": "Data analysis", "domain_id": "data_ai" },
{ "id": "business_intelligence", "name": "Business intelligence & data visualization", "domain_id": "data_ai" }
],
"domains": [
{ "id": "administration_office", "name": "Administration & Office" },
{ "id": "data_ai", "name": "Data & AI" }
],
"broader": null
},
{
"id": "excel",
"name": "Excel",
"type": "software",
"mention": "Excel",
"families": [
{ "id": "office_software", "name": "Office software", "domain_id": "administration_office" },
{ "id": "data_analysis", "name": "Data analysis", "domain_id": "data_ai" }
],
"domains": [
{ "id": "administration_office", "name": "Administration & Office" },
{ "id": "data_ai", "name": "Data & AI" }
],
"broader": { "id": "microsoft_office", "name": "Microsoft Office" }
}
],
"unresolved": [],
"taxonomy_version": "v1",
"credits_used": 1
}- skills[].id
- Stable id to store and filter on; name is the canonical name in the requested language.
- skills[].mention
- The part of the text each skill was found in. Skills follow the order of the text.
- skills[].broader
- A more general skill to widen a search, here Microsoft Office for Excel, or null.
- unresolved[]
- Parts of the text that match no taxonomy skill, with family_hints. Nothing is guessed.
Where teams normalize skills
HireLayer Skills Normalizer is used by recruiting software and recruiting services. Each use case links to the full workflow.
- 01
Normalize recruiter search queries
Resolve what a recruiter types to skill ids before searching profiles saved in your sourcing product, and widen with broader when needed.
Skills Normalizer for Sourcing tools - 02
Consistent skill tags across profiles
Store the skill id next to the original wording on candidate or employee records in your HR product.
Skills Normalizer for HR software & SaaS - 03
Skill facets on a job board
Group candidate and job skills by family and domain to power filters both sides understand.
Skills Normalizer for Job boards & career sites
Integrate skill normalization in your data flow
Call the API from your backend and keep the key server-side. Your product keeps its records, interface and review process.
STEP 01
Collect skill text
Use the skills section of a CV, the skills returned by HireLayer Resume Parser, terms from job criteria, or what users type in your interface.
STEP 02
Resolve it in one call
Send it as one text of up to 5,000 characters. Each taxonomy skill comes back in order; review what is listed in unresolved.
STEP 03
Store both values
Keep the original wording for display and the skill id, families and domains for search and facets.
Technical specifications
- Authentication
- X-API-Key header
- Content-Type
- application/json
- text
- Required · up to 5,000 characters
- language
- fr (default) or en, for returned names
- Other fields
- Rejected with HTTP 400
- Taxonomy
- GET /api/v4/skills · 11,061 skills, about 4 MB
- Billing
- 1 credit per call
No backend to write? Use Skills Normalizer from Make, Power Automate, ChatGPT, Claude, Google Sheets or your ATS.
Where Skills Normalizer fits in the HireLayer pipeline
Each product works on its own. Chain them when a workflow needs CV data, job criteria, a search and a decision aid together.
- CV filePDF, DOCX, image…Resume ParserResume Parsing API→ application_id · resumeJob RecommendationsJob Recommendation APIresume → closest open jobsResume ScorerCandidate & Job Matching APIjob + resumes → score · verdict
- Job descriptionText or fileJob Criteria ExtractorJob Parsing API→ job_id · criteria[]Talent Pool SearchTalent Pool Search APIjob → closest stored resumesResume ScorerCandidate & Job Matching API+ precise_ranking → ranking_reason
- Free-text skillsFrom CVs, jobs or usersSkills NormalizerSkills Matching API→ taxonomy skill ids
Store skill ids on profiles and jobs for search and facets.
Resume Parser and Job Criteria Extractor store what they read. The searches find the closest resumes or jobs; Resume Scorer explains the fit. One API key and one credit balance cover every call.
Skills Matching API questions
Answers based on the current API contract.
What can I send in text?
Which API extracts and normalizes skills from resumes and job descriptions?
How many skills can I resolve in one request?
Can I browse the skill taxonomy?
What happens to text that matches no skill?
Make your first call to HireLayer Skills Normalizer today.
Create an account to get an API key. Credits are shared across all six HireLayer products.
Related HireLayer products
- Resume Parsing APIHireLayer Resume ParserTurn CV files into structured candidate JSON.
- Job Parsing APIHireLayer Job Criteria ExtractorTurn job descriptions into typed, weighted criteria.
- Candidate & Job Matching APIHireLayer Resume ScorerScore resumes against a job, criterion by criterion.