HireLayer logoHireLayer

HireLayer Skills · Skills Matching API

Skills Matching API that maps free-text skills to a catalog

Send one skill or a batch of up to 100. HireLayer Skills returns the closest entries from its reference catalog, each with a similarity score, a domain and a subcategory, so different wordings land on consistent terms.

Start for freeRead the API docs
Schedule a demo
Endpoints
POST /skills/match · GET /skills
Batch
Up to 100 skills
Results
top_k from 1 to 50
Billing
1 credit per request

HireLayer Skills

POST /api/v1/skills/match

200 OK
The query “web development” returns three ranked catalog skills with similarity scores and their domain and subcategory. Values come from the documented API example.

Capabilities

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 domains and categories, is a project in itself.

  • 01

    Single query or batch

    Send skill for one term (top_k defaults to 5) or skills for up to 100 terms (top_k defaults to 3).

  • 02

    Similarity score per match

    Results are ranked and each one carries a similarity_score, so you choose the threshold that suits your product.

  • 03

    Domain and subcategory

    Every catalog entry is grouped by domain and subcategory, ready for facets and skill clusters.

  • 04

    A browsable catalog

    GET /api/v1/skills lists the loaded catalog with each entry’s domain, subcategory and rank.

  • 05

    Per-query results in a batch

    Each input gets its own success flag with results or an error, so one bad value does not fail the batch.

  • 06

    One credit for a whole batch

    A request of up to 100 skills consumes one credit when it succeeds.

Under the hood

Single skill or batch: two request modes

PropertySingle skillBatch
Selectorskill: stringskills: array of 1–100
Default top_k53
Responsequery_skill · total_results · resultstotal_queries · successful_matches · results[]
Invalid valueHTTP 400 for an empty skillPer-query error; the batch continues
Credits1 per request1 per request
Batch requestPOST /api/v1/skills/match
{
  "skills": ["python", "react", ""],
  "top_k": 1
}
Batch responseIllustrative values
{
  "total_queries": 3,
  "successful_matches": 2,
  "results": [
    {
      "query_skill": "python",
      "success": true,
      "results": [
        { "rank": 1, "skill": "Python", "similarity_score": 0.98,
          "domain": "Engineering", "subcategory": "Programming languages" }
      ]
    },
    {
      "query_skill": "react",
      "success": true,
      "results": [
        { "rank": 1, "skill": "React", "similarity_score": 0.97,
          "domain": "Engineering", "subcategory": "Frontend" }
      ]
    },
    { "query_skill": "", "success": false, "error": "…" }
  ]
}

Request and response

Match a free-text skill

Values below come from the API reference example. Field names and shapes match the live contract.

HireLayer Skills docs
RequestPOST /api/v1/skills/match
curl -X POST https://onlineresumeparser.com/api/v1/skills/match \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"skill":"web development","top_k":3}'
Response200 OK · application/json
{
  "query_skill": "web development",
  "total_results": 3,
  "results": [
    {
      "rank": 1,
      "skill": "Web development",
      "similarity_score": 0.96,
      "domain": "Engineering",
      "subcategory": "Web"
    },
    {
      "rank": 2,
      "skill": "Web application development",
      "similarity_score": 0.91,
      "domain": "Engineering",
      "subcategory": "Web"
    },
    {
      "rank": 3,
      "skill": "Frontend development",
      "similarity_score": 0.86,
      "domain": "Engineering",
      "subcategory": "Frontend"
    }
  ]
}
results[].skill
The catalog term to store next to the original text.
results[].similarity_score
Closeness between the query and the catalog entry.
results[].domain · subcategory
Grouping fields for facets and clusters.
total_results
Number of matches returned, bounded by top_k.

Use cases

Where teams normalize skills

HireLayer Skills is used by recruiting software and recruiting services. Each use case links to the full workflow.

  1. 01

    Normalize recruiter search queries

    Map what a recruiter types to catalog terms before searching profiles saved in your sourcing product.

    Skills for Sourcing tools
  2. 02

    Consistent skill tags across profiles

    Store the catalog term next to the original wording on candidate or employee records in your HR product.

    Skills for HR software & SaaS
  3. 03

    Skill facets on a job board

    Group candidate and job skills by domain and subcategory to power filters both sides understand.

    Skills for Job boards & career sites

Integration

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.

  1. STEP 01

    Collect skill text

    Use raw skills from HireLayer CV Extract, terms from job criteria, or what users type in your interface.

  2. STEP 02

    Match in batches

    Send up to 100 terms per request and keep the top result above the similarity threshold you choose.

  3. STEP 03

    Store both values

    Keep the original wording for display and the catalog term, domain and subcategory for search and facets.

Technical specifications

Authentication
X-API-Key header
Content-Type
application/json
Selector
skill or skills, never both
Batch size
1 to 100 values, converted to strings
top_k
Integer from 1 to 50
Catalog
GET /api/v1/skills · size in total_skills
Billing
1 credit per successful request

Where Skills fits in the HireLayer pipeline

Each API works on its own. Chain them when a workflow needs CV data, job criteria and a decision aid together.

  1. CV filePDF, DOCX, image…
    CV ExtractResume Parsing API→ info_resume.text · skills[]MatchCandidate & Job Matching APIjob_text + candidate_text + matching_criteria
  2. Job descriptionPlain job_text
    Job ExtractJob Parsing API→ matching_criteria[]RankCandidate Ranking APIjob_text + up to 10 candidate_text
  3. Free-text skillsFrom CVs, jobs or users
    SkillsSkills Matching API→ catalog skill terms

    Store normalized terms on profiles and jobs for search and facets.

Match takes criteria from Job Extract and CV text from Extract. Rank only needs the job text and each candidate’s CV text. One API key and one credit balance cover every call.

Questions

Skills Matching API questions

Answers based on the current API contract.

What is the difference between skill and skills?

skill takes one string and returns query_skill, total_results and results. skills takes an array of 1 to 100 values and returns total_queries, successful_matches and one result object per input. Send one of them, never both.

How many skills can I match in one request?

Up to 100 in the skills array. A successful request consumes one credit, whatever the batch size.

Can I browse the skill catalog?

Yes. GET /api/v1/skills returns the loaded catalog with each skill’s domain, subcategory and rank, plus total_skills.

Which similarity score should I accept?

The API returns ranked matches with their scores; your application sets the threshold. Many teams auto-accept high scores and ask a user to confirm the rest.

HireLayer Skills

Make your first HireLayer Skills call today.

Create an account to get an API key. Credits are shared across all five HireLayer APIs.

Create an API accountHireLayer Skills docsSchedule a demo

Works well with

Related HireLayer APIs

All products

Solutions using Skills