APIs

HireLayer Skills

Resolve free-text skills, from one skill to a whole resume section, to a taxonomy of 11,061 skills with families and domains, and download the taxonomy.

Endpoints: POST /api/v1/skills/resolve · GET /api/v1/skills
Input: JSON · free text up to 5,000 characters, French or English
Output: Taxonomy skills with stable ids, families and domains
Billing: 1 credit per successful call

Resolve skills

POST/api/v1/skills/resolve

Turn free text, from one skill to a whole skills section, into taxonomy skills with their families and domains.

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

Request body

Content type application/json

textstringrequired
Free text in French or English: one skill (MS Excel), a compound string (Pack Office (Word, Excel)) or a whole skills section (lines, bullets, ;, comma lists).
1–5,000 characters
languagestring
fr (default) or en.
"fr""en"

Response

200Skills found in the text.

languagestring
Language of the names returned.
"fr""en"
skillsResolvedSkill[]
Taxonomy skills named in the text, in the order of the text.
›Show 7 child fieldsHide child fields
- idstring
  Stable skill id, e.g. excel. Store and filter on it.
- namestring
  Canonical name in the requested language.
- typestring
  "hard""software""certification""soft""language"
- familiesSkillFamilyRef[]
  Families of the skill, the primary one first.
  ›Show 3 child fieldsHide child fields
  idstring
  Stable family id, e.g. office_software.
  namestring
  Family name in the requested language.
  domain_idstring
  Id of the domain the family belongs to.
- domainsSkillDomainRef[]
  Domains of those families, the primary one first.
  ›Show 2 child fieldsHide child fields
  idstring
  Stable domain id, e.g. data_ai.
  namestring
  Domain name in the requested language.
- broaderBroaderSkill | null
  A more general skill to widen a search to (Excel → Microsoft Office), or null.
  ›Show 2 child fieldsHide child fields
  idstring
  namestring
- mentionstring
  The part of the text the skill was found in.
unresolvedUnresolvedSkill[]
Parts of the text that match no taxonomy skill.
›Show 2 child fieldsHide child fields
- textstring
  Part of the text matching no skill.
- family_hintsobject[]
  Families it probably belongs to, possibly none. No skill is guessed.
  ›Show 2 child fieldsHide child fields
  idstring
  namestring
taxonomy_versionstring
Taxonomy version (v1, v2…). Results stored with an older version should be resolved again.

Errors

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
400
Unknown field(s): unexpected_field. Accepted: 'text' and optional 'language'
The body contains another field than text and language (for example skill, skills or top_k); the message names them.
Do not retry
400
The 'text' field (string) is required
text is missing or not a string.
Do not retry
400
Text cannot be empty
text is empty after trimming.
Do not retry
400
'text' must be at most 5000 characters
text is longer than 5,000 characters.
Do not retry
400
'language' must be 'fr' or 'en'
language is present but is not fr or en (case-sensitive; null is rejected).
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. Most calls answer in well under a second; a long skills section can take 10 seconds or more. The gateway waits up to 60 seconds; use a client timeout of at least 65 seconds.
Resolution: There is no score and no threshold: every part of the text is either resolved to taxonomy skills or listed in unresolved. A compound mention can yield several skills (Pack Office (Word, Excel) gives Microsoft Office, Word and Excel), and a skill named twice is returned once.
Storage: Store id rather than name: names depend on language, ids do not. Keep taxonomy_version with your results and resolve them again when it changes.
Strict body: Only text and language are accepted. The former /api/v1/skills/match fields (skill, skills, top_k) are rejected, and POST /api/v1/skills/match now answers 410.

Request

curl -X POST https://hirelayer.co/api/v1/skills/resolve \
  -H "X-API-Key: $HIRELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Google Sheet/Excel",
    "language": "fr"
  }'

import os

import requests

response = requests.post(
    "https://hirelayer.co/api/v1/skills/resolve",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    json={
        "text": "Google Sheet/Excel",
        "language": "fr",
    },
    timeout=65,
)
response.raise_for_status()

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

const response = await fetch('https://hirelayer.co/api/v1/skills/resolve', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Google Sheet/Excel',
    language: 'fr',
  }),
  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.skills)

Response

{
  "language": "fr",
  "skills": [
    {
      "id": "google_sheets",
      "name": "Google Sheets",
      "type": "software",
      "mention": "Google Sheet",
      "families": [
        {
          "id": "office_software",
          "name": "Bureautique",
          "domain_id": "administration_office"
        },
        {
          "id": "data_analysis",
          "name": "Analyse de données",
          "domain_id": "data_ai"
        },
        {
          "id": "business_intelligence",
          "name": "Business Intelligence & dataviz",
          "domain_id": "data_ai"
        }
      ],
      "domains": [
        {
          "id": "administration_office",
          "name": "Administration & Bureautique"
        },
        {
          "id": "data_ai",
          "name": "Data & Intelligence artificielle"
        }
      ],
      "broader": null
    },
    {
      "id": "excel",
      "name": "Excel",
      "type": "software",
      "mention": "Excel",
      "families": [
        {
          "id": "office_software",
          "name": "Bureautique",
          "domain_id": "administration_office"
        },
        {
          "id": "data_analysis",
          "name": "Analyse de données",
          "domain_id": "data_ai"
        }
      ],
      "domains": [
        {
          "id": "administration_office",
          "name": "Administration & Bureautique"
        },
        {
          "id": "data_ai",
          "name": "Data & Intelligence artificielle"
        }
      ],
      "broader": {
        "id": "microsoft_office",
        "name": "Microsoft Office"
      }
    }
  ],
  "unresolved": [],
  "taxonomy_version": "v1"
}

{
  "success": false,
  "error": "Request body must be a JSON object"
}

Skills section, names in English. Send a whole list in one call: each skill comes back once, in the order of the text. With language: "en", names are returned in English whatever the language of the text.

Skills section, names in English request

curl -X POST https://hirelayer.co/api/v1/skills/resolve \
  -H "X-API-Key: $HIRELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "React, Node, Cobol, gestion de projet",
    "language": "en"
  }'

import os

import requests

response = requests.post(
    "https://hirelayer.co/api/v1/skills/resolve",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    json={
        "text": "React, Node, Cobol, gestion de projet",
        "language": "en",
    },
    timeout=65,
)
response.raise_for_status()

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

const response = await fetch('https://hirelayer.co/api/v1/skills/resolve', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'React, Node, Cobol, gestion de projet',
    language: 'en',
  }),
  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.skills)

Skills section, names in English response

{
  "language": "en",
  "skills": [
    {
      "id": "react",
      "name": "React",
      "type": "software",
      "mention": "React",
      "families": [
        {
          "id": "frontend_development",
          "name": "Frontend development",
          "domain_id": "software_development"
        }
      ],
      "domains": [
        {
          "id": "software_development",
          "name": "Software Development"
        }
      ],
      "broader": null
    },
    {
      "id": "node_js",
      "name": "Node.js",
      "type": "software",
      "mention": "Node",
      "families": [
        {
          "id": "backend_development",
          "name": "Backend development",
          "domain_id": "software_development"
        },
        {
          "id": "programming_languages",
          "name": "Programming languages",
          "domain_id": "software_development"
        }
      ],
      "domains": [
        {
          "id": "software_development",
          "name": "Software Development"
        }
      ],
      "broader": null
    },
    {
      "id": "cobol",
      "name": "COBOL",
      "type": "software",
      "mention": "Cobol",
      "families": [
        {
          "id": "programming_languages",
          "name": "Programming languages",
          "domain_id": "software_development"
        },
        {
          "id": "backend_development",
          "name": "Backend development",
          "domain_id": "software_development"
        }
      ],
      "domains": [
        {
          "id": "software_development",
          "name": "Software Development"
        }
      ],
      "broader": null
    },
    {
      "id": "project_management",
      "name": "Project management",
      "type": "hard",
      "mention": "gestion de projet",
      "families": [
        {
          "id": "project_management",
          "name": "Project management",
          "domain_id": "management_strategy"
        }
      ],
      "domains": [
        {
          "id": "management_strategy",
          "name": "Management, Projects & Strategy"
        }
      ],
      "broader": null
    }
  ],
  "unresolved": [],
  "taxonomy_version": "v1"
}

List the skills taxonomy

GET/api/v1/skills

Download every skill of the taxonomy with its families, domains and broader skill.

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

Query parameters

languagestring
fr (default) or en.
"fr""en"

Response

200The taxonomy (first two of 11,061 skills shown).

languagestring
Language of the names returned.
"fr""en"
totalinteger
Number of skills in the taxonomy.
skillsTaxonomySkill[]
The whole taxonomy, most frequent in resumes first. There is no pagination.
›Show 6 child fieldsHide child fields
- idstring
  Stable skill id, e.g. excel. Store and filter on it.
- namestring
  Canonical name in the requested language.
- typestring
  "hard""software""certification""soft""language"
- familiesSkillFamilyRef[]
  Families of the skill, the primary one first.
  ›Show 3 child fieldsHide child fields
  idstring
  Stable family id, e.g. office_software.
  namestring
  Family name in the requested language.
  domain_idstring
  Id of the domain the family belongs to.
- domainsSkillDomainRef[]
  Domains of those families, the primary one first.
  ›Show 2 child fieldsHide child fields
  idstring
  Stable domain id, e.g. data_ai.
  namestring
  Domain name in the requested language.
- broaderBroaderSkill | null
  A more general skill to widen a search to (Excel → Microsoft Office), or null.
  ›Show 2 child fieldsHide child fields
  idstring
  namestring
taxonomy_versionstring
Taxonomy version (v1, v2…). Results stored with an older version should be resolved again.

Errors

400
'language' must be 'fr' or 'en'
The language query parameter is present but is not fr or en (case-sensitive).
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
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

Language: Add ?language=en for English names; French is the default.
Size and caching: The response holds the whole taxonomy (about 4 MB) and costs a credit: cache it on your side, for example once a day, and refresh it when taxonomy_version changes.

Request

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

import os

import requests

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

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

const response = await fetch('https://hirelayer.co/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)

Response

{
  "language": "fr",
  "total": 11061,
  "skills": [
    {
      "id": "teamwork",
      "name": "Travail en équipe",
      "type": "soft",
      "families": [
        {
          "id": "teamwork",
          "name": "Travail en équipe & coopération",
          "domain_id": "soft_skills"
        }
      ],
      "domains": [
        {
          "id": "soft_skills",
          "name": "Compétences comportementales"
        }
      ],
      "broader": null
    },
    {
      "id": "microsoft_office",
      "name": "Microsoft Office",
      "type": "software",
      "families": [
        {
          "id": "office_software",
          "name": "Bureautique",
          "domain_id": "administration_office"
        }
      ],
      "domains": [
        {
          "id": "administration_office",
          "name": "Administration & Bureautique"
        }
      ],
      "broader": null
    }
  ],
  "taxonomy_version": "v1"
}

{
  "success": false,
  "error": "'language' must be 'fr' or 'en'"
}

Migrating from /skills/match

/skills/match	/skills/resolve
`skill`, or `skills` (up to 100)	`text`: one skill or a whole list (lines, bullets, commas), up to 5,000 characters
`top_k`, `similarity_score`	None: each part of the text is resolved or listed in `unresolved`
`results[].skill`	`skills[].name`, and `skills[].id` to store
`domain`, `subcategory`	`families` and `domains`, the primary one first
One result list per input skill	`mention`: the part of the text each skill comes from