APIs

HireLayer Skills

Normalize free-text skills against the HireLayer catalog, one at a time or in batches of 100, and download the catalog.

Endpoints: POST /api/v1/skills/match · GET /api/v1/skills
Input: JSON · one skill, or up to 100
Output: Closest catalog skills with a similarity score
Billing: 1 credit per successful call, single or batch

Match skills to the catalog

POST/api/v1/skills/match

Map free-text skills, one or up to 100 at a time, to the closest catalog skills.

Authentication: X-API-Key header
Billing: 1 credit per successful call, single or batch
Client timeout: Client timeout ≥ 65 s

Request body

Content type application/json

Send exactly one of skill or skills.

skillstring
One free-text skill. Send skill or skills, not both.
non-empty
skillsstring[]
Batch of free-text skills. Non-string items are converted with String().
1–100 items
top_kinteger
Matches per skill. Defaults to 5 with skill, 3 with skills.
1–50

Response

200Single mode (skill).

query_skillstring
Your skill, trimmed.
total_resultsinteger
Number of results, at most top_k.
resultsSkillMatch[]
Closest catalog skills, best first.
›Show 5 child fieldsHide child fields
- rankinteger
  Position, 1 is the closest.
  ≥ 1
- skillstring
  Catalog label.
- similarity_scorenumber
  Cosine similarity rounded to 4 decimals. 1 for an exact label or synonym match.
  ≤ 1
- domainstring
  Catalog domain, e.g. Technologie.
- subcategorystring
  Catalog subcategory. Empty string when the skill has none.

200Batch mode (skills).

total_queriesinteger
Number of skills sent.
successful_matchesinteger
Number of items with success: true.
resultsSkillBatchItem[]
One item per input skill, in input order. Duplicates are kept.
›Show 4 child fieldsHide child fields
- query_skillstring
  The input skill.
- successboolean
- resultsSkillMatch[]may be absent
  Present when success is true.
  ›Show 5 child fieldsHide child fields
  rankinteger
  Position, 1 is the closest.
  ≥ 1
  skillstring
  Catalog label.
  similarity_scorenumber
  Cosine similarity rounded to 4 decimals. 1 for an exact label or synonym match.
  ≤ 1
  domainstring
  Catalog domain, e.g. Technologie.
  subcategorystring
  Catalog subcategory. Empty string when the skill has none.
- errorstringmay be absent
  Present when success is false: Empty skill, or The AI processing step failed. Please try again later. when matching failed (retry this skill).

Errors

400
Provide either 'skill' or 'skills', not both
Both keys are present, even if one is null.
Do not retry
400
The 'skill' or 'skills' field is required
Neither key is present.
Do not retry
400
The 'skill' field is required
skill is not a string.
Do not retry
400
Skill cannot be empty
skill is empty after trimming.
Do not retry
400
The 'skills' (list) field is required
skills is not an array.
Do not retry
400
The 'skills' field must be a non-empty list
skills is [].
Do not retry
400
Maximum 100 skills per batch request
skills has more than 100 items.
Do not retry
400
top_k must be an integer between 1 and 50
top_k is not a JSON integer from 1 to 50 ("5" and null are rejected).
Do not retry
400
Request body must be a JSON object
The body is missing, is a JSON array, or Content-Type is not application/json.
Do not retry
401
Missing API Key
The X-API-Key header is absent. Authorization: Bearer is not accepted.
Do not retry
401
Invalid API Key
The key is malformed, unknown or revoked. Rotating a key revokes the previous one immediately.
Do not retry
403
Insufficient credits available
The account has no credit left. availableCredits is the current balance.
Fix, then retry
500
Internal server error
Unexpected gateway failure.
Retry with backoff
500
Internal server error. Please try again later.
The body is not valid JSON, is a JSON primitive or exceeds 10 MB, or the service failed unexpectedly. Check the payload: if it is valid, retry.
Retry with backoff
502
Upstream API unavailable
The service did not answer within 60 seconds, or could not be reached.
Retry with backoff
503
Credit service temporarily unavailable
Credits could not be checked or deducted. No credit is consumed, including when the operation itself had completed.
Retry with backoff

Behavior

Latency: Synchronous. The gateway waits up to 60 seconds; use a client timeout of at least 65 seconds.
Exact matches: When the normalized text (case, accents and punctuation ignored) equals a catalog label or synonym, that skill is ranked first with similarity_score: 1. Other results come from semantic similarity.
Thresholds: Results are always returned, even weak ones. Choose your own similarity_score threshold; HireLayer CV Extract uses 0.75 to mark a skill as normalized.
Unknown fields: Unlike the other endpoints, unknown body fields are ignored.

Request

curl -X POST https://onlineresumeparser.com/api/v1/skills/match \
  -H "X-API-Key: $HIRELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skill": "react js",
    "top_k": 3
  }'

import os

import requests

response = requests.post(
    "https://onlineresumeparser.com/api/v1/skills/match",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    json={
        "skill": "react js",
        "top_k": 3,
    },
    timeout=65,
)
response.raise_for_status()

data = response.json()
print(data["results"])

const response = await fetch('https://onlineresumeparser.com/api/v1/skills/match', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    skill: 'react js',
    top_k: 3,
  }),
  signal: AbortSignal.timeout(65_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

const data = await response.json()
console.log(data.results)

Response

{
  "query_skill": "react js",
  "total_results": 3,
  "results": [
    {
      "rank": 1,
      "skill": "React",
      "similarity_score": 0.8712,
      "domain": "Technologie",
      "subcategory": "Languages & Frameworks"
    },
    {
      "rank": 2,
      "skill": "React Native",
      "similarity_score": 0.7934,
      "domain": "Technologie",
      "subcategory": "Languages & Frameworks"
    },
    {
      "rank": 3,
      "skill": "Javascript",
      "similarity_score": 0.7121,
      "domain": "Technologie",
      "subcategory": "Languages & Frameworks"
    }
  ]
}

{
  "success": false,
  "error": "Provide either 'skill' or 'skills', not both"
}

Batch. Send skills to match up to 100 values in one call. Each item succeeds or fails on its own; the HTTP status stays 200.

Batch request

curl -X POST https://onlineresumeparser.com/api/v1/skills/match \
  -H "X-API-Key: $HIRELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skills": [
      "python",
      "gestion de projets",
      " "
    ],
    "top_k": 1
  }'

import os

import requests

response = requests.post(
    "https://onlineresumeparser.com/api/v1/skills/match",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    json={
        "skills": [
            "python",
            "gestion de projets",
            " ",
        ],
        "top_k": 1,
    },
    timeout=65,
)
response.raise_for_status()

data = response.json()
print(data["results"])

const response = await fetch('https://onlineresumeparser.com/api/v1/skills/match', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    skills: [
      'python',
      'gestion de projets',
      ' ',
    ],
    top_k: 1,
  }),
  signal: AbortSignal.timeout(65_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

const data = await response.json()
console.log(data.results)

Batch response

{
  "total_queries": 3,
  "successful_matches": 2,
  "results": [
    {
      "query_skill": "python",
      "success": true,
      "results": [
        {
          "rank": 1,
          "skill": "Python",
          "similarity_score": 1,
          "domain": "Technologie",
          "subcategory": "Languages & Frameworks"
        }
      ]
    },
    {
      "query_skill": "gestion de projets",
      "success": true,
      "results": [
        {
          "rank": 1,
          "skill": "Gestion de projet - PMO",
          "similarity_score": 1,
          "domain": "Business",
          "subcategory": ""
        }
      ]
    },
    {
      "query_skill": " ",
      "success": false,
      "error": "Empty skill"
    }
  ]
}

List the skill catalog

GET/api/v1/skills

Download the whole reference catalog used for matching.

Authentication: X-API-Key header
Billing: 1 credit per successful call
Client timeout: Client timeout ≥ 65 s

Response

200The catalog.

total_skillsinteger
Number of skills in the catalog.
skillsCatalogSkill[]
The whole catalog. There is no pagination.
›Show 4 child fieldsHide child fields
- skillstring
  Catalog label.
- domainstring
  Catalog domain, e.g. Technologie.
- subcategorystring
  Catalog subcategory. Empty string when the skill has none.
- rankinteger
  1-based position in the catalog. Not a relevance score.
  ≥ 1

Errors

401
Missing API Key
The X-API-Key header is absent. Authorization: Bearer is not accepted.
Do not retry
401
Invalid API Key
The key is malformed, unknown or revoked. Rotating a key revokes the previous one immediately.
Do not retry
403
Insufficient credits available
The account has no credit left. availableCredits is the current balance.
Fix, then retry
500
Internal server error
Unexpected gateway failure.
Retry with backoff
502
Upstream API unavailable
The service did not answer within 60 seconds, or could not be reached.
Retry with backoff
503
Credit service temporarily unavailable
Credits could not be checked or deducted. No credit is consumed, including when the operation itself had completed.
Retry with backoff

Behavior

Caching: The catalog changes rarely and each call costs a credit: cache it on your side, for example once a day.
Labels: Labels and domains are mostly French (Technologie, Ressources Humaines, Design & Contenu…). Query parameters are ignored.

Request

curl https://onlineresumeparser.com/api/v1/skills \
  -H "X-API-Key: $HIRELAYER_API_KEY"

import os

import requests

response = requests.get(
    "https://onlineresumeparser.com/api/v1/skills",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    timeout=65,
)
response.raise_for_status()

data = response.json()
print(data["total_skills"])

const response = await fetch('https://onlineresumeparser.com/api/v1/skills', {
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
  },
  signal: AbortSignal.timeout(65_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

const data = await response.json()
console.log(data.total_skills)

Response

{
  "total_skills": 664,
  "skills": [
    {
      "skill": "GMAO",
      "domain": "Business",
      "subcategory": "",
      "rank": 1
    },
    {
      "skill": "Gantt",
      "domain": "Business",
      "subcategory": "",
      "rank": 2
    },
    {
      "skill": "Figma",
      "domain": "Design & Contenu",
      "subcategory": "Logiciel",
      "rank": 180
    },
    {
      "skill": "React",
      "domain": "Technologie",
      "subcategory": "Languages & Frameworks",
      "rank": 499
    }
  ]
}

{
  "error": "Missing API Key"
}