Skip to content

Products

HireLayer Skills Normalizer

HireLayer Skills Normalizer extracts the skills named in a resume or job description and normalizes them to 11,061 taxonomy skills with stable ids.

HireLayer Skills Normalizer is an API that extracts the skills named in a resume or a job description and normalizes them to a taxonomy of 11,061 skills, so different wordings of one skill come back under one stable id. One JSON POST /api/v4/skills/normalize call takes up to 5,000 characters, such as a resume skills section or the requirements of a job ad, and returns every skill it names in text order, with its type, families, domains and the part of the text it was found in, for 1 credit. A part that matches no skill is listed as unresolved instead of guessed, and nothing is stored. For a resume file, the Resume Parser returns the skills already resolved to the same taxonomy.

  • id: a stable skill id such as excel, to store and filter on whatever wording the text used.
  • name: the canonical name, in the language you ask for (fr or en).
  • type: hard, software, certification, soft or language.
  • families and domains: where the skill sits in the taxonomy, the primary one first.
  • broader: a more general skill to widen a search to (Excel → Microsoft Office), or null.
Endpoint
POST /api/v4/skills/normalize
Input
JSON text, up to 5,000 characters
Output
Taxonomy skills with stable ids, families and domains
Price
1 credit
POST/api/v4/skills/normalize

Maps the skills named in a free text to the HireLayer taxonomy. Nothing is stored.

Authentication
X-API-Key header
Billing
1 credit
Client timeout
Client timeout ≥ 60 s

Request body

Content type application/json

  • textstringrequired

    1–5,000 characters

  • languagestring
    "fr""en"

Response

200The taxonomy skills named in the text, in the order of the text.

  • request_idstringmay be absent

    The call's id, also in the HireLayer-Request-Id header. Quote it when contacting support.

  • languagestring

    Language of the names returned.

    "fr""en"
  • skillsResolvedSkill[]

    Taxonomy skills named in the text, in the order of the text.

    ›Show 7 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 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 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 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 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 fields
      • idstring
      • namestring
  • taxonomy_versionstring

    Taxonomy version (v1, v2…). Results stored with an older version should be resolved again.

  • credits_usedinteger

    Credits this call cost.

    ≥ 0

Errors

  • 400
    invalid_requesttext is required.

    param: text. No text, or an empty one.

    Fix, then retry

  • 400
    invalid_requesttext must be a string.

    param: text. text is not a string.

    Fix, then retry

  • 400
    invalid_requestlanguage must be fr or en.

    param: language. language is not fr or en.

    Fix, then retry

  • 400
    invalid_requestUnknown field lang.

    param: lang. A field the call does not take.

    Fix, then retry

  • 400
    invalid_requestThe request body is not valid JSON.

    The body is not valid JSON, not an object, or not sent as application/json.

    Fix, then retry

  • 401
    missing_api_keyThe X-API-Key header is missing.

    No X-API-Key header.

    Fix, then retry

  • 401
    missing_api_keyAuthorization: Bearer is not accepted: send the key in the X-API-Key header.

    The key sent as Authorization: Bearer: it goes in X-API-Key.

    Fix, then retry

  • 401
    missing_api_keyThe key goes in the X-API-Key header, not in the URL.

    The key sent in the URL: it goes in X-API-Key.

    Fix, then retry

  • 401
    invalid_api_keyInvalid API key: it is unknown, malformed or revoked.

    The key is unknown, malformed or revoked.

    Fix, then retry

  • 403
    insufficient_creditsThis call needs 1 credit and none is left. Nothing was processed or billed.

    No credit left.

    Fix, then retry

  • 413
    payload_too_largetext must be 5,000 characters or less.

    param: text. The text is over 5,000 characters.

    Fix, then retry

  • 500
    internal_errorInternal error: retry later. If it persists, contact support with the request_id.

    An unexpected error.

    Retry with backoff

  • 502
    model_unavailableThe analysis did not complete after several attempts. Nothing was stored or billed: retry with backoff.

    The analysis did not complete.

    Retry with backoff

  • 502
    internal_errorThe service could not be reached: retry later.

    The service could not be reached.

    Retry with backoff

  • 503
    internal_errorThe credit service is briefly unavailable: retry in a second.

    The credit service is briefly unavailable. Header Retry-After: <seconds>.

    Retry with backoff

  • 504
    internal_errorThe service did not answer in time. The change may still be applied: read it before sending it again.

    No answer in time.

    Retry with backoff

Behavior

Credits
1.
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"
  }'
import os

import requests

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

data = response.json()
print(data["skills"])
const response = await fetch('https://hirelayer.co/api/v4/skills/normalize', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Google Sheet/Excel',
    language: 'en',
  }),
  signal: AbortSignal.timeout(60_000),
})

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

const data = await response.json()
console.log(data.skills)
{
  "request_id": "1cb1ef90-21a8-43f5-ac73-87b7377c4951",
  "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
}
{
  "error": {
    "code": "invalid_request",
    "message": "text is required.",
    "param": "text",
    "doc_url": "https://hirelayer.co/api-docs/errors#invalid_request"
  },
  "request_id": "6f1c2a4e-1d2b-4c3a-9e8f-0a1b2c3d4e5f"
}
GET/api/v4/skills

The whole taxonomy, most frequent in resumes first. 1 credit.

Authentication
X-API-Key header
Billing
1 credit
Client timeout
Client timeout ≥ 30 s

Query parameters

  • languagestring

    fr (default) or en.

    "fr""en"

Response

200The taxonomy.

  • request_idstringmay be absent

    The call's id, also in the HireLayer-Request-Id header. Quote it when contacting support.

  • 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 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 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 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 fields
      • idstring
      • namestring
  • taxonomy_versionstring

    Taxonomy version (v1, v2…). Results stored with an older version should be resolved again.

  • credits_usedinteger

    Credits this call cost.

    ≥ 0

Errors

  • 400
    invalid_requestlanguage must be fr or en.

    param: language. language is not fr or en.

    Fix, then retry

  • 401
    missing_api_keyThe X-API-Key header is missing.

    No X-API-Key header.

    Fix, then retry

  • 401
    missing_api_keyAuthorization: Bearer is not accepted: send the key in the X-API-Key header.

    The key sent as Authorization: Bearer: it goes in X-API-Key.

    Fix, then retry

  • 401
    missing_api_keyThe key goes in the X-API-Key header, not in the URL.

    The key sent in the URL: it goes in X-API-Key.

    Fix, then retry

  • 401
    invalid_api_keyInvalid API key: it is unknown, malformed or revoked.

    The key is unknown, malformed or revoked.

    Fix, then retry

  • 403
    insufficient_creditsThis call needs 1 credit and none is left. Nothing was processed or billed.

    No credit left.

    Fix, then retry

  • 500
    internal_errorInternal error: retry later. If it persists, contact support with the request_id.

    An unexpected error.

    Retry with backoff

  • 502
    internal_errorThe service could not be reached: retry later.

    The service could not be reached.

    Retry with backoff

  • 503
    internal_errorThe credit service is briefly unavailable: retry in a second.

    The credit service is briefly unavailable. Header Retry-After: <seconds>.

    Retry with backoff

  • 504
    internal_errorThe service did not answer in time. The change may still be applied: read it before sending it again.

    No answer in time.

    Retry with backoff

curl -g "https://hirelayer.co/api/v4/skills?language=en" \
  -H "X-API-Key: $HIRELAYER_API_KEY"
import os

import requests

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

data = response.json()
print(data["total"])
const response = await fetch('https://hirelayer.co/api/v4/skills?language=en', {
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
  },
  signal: AbortSignal.timeout(30_000),
})

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

const data = await response.json()
console.log(data.total)
{
  "request_id": "b42c2d25-5b88-4404-82b6-817da5b49cca",
  "language": "en",
  "total": 11061,
  "skills": [
    {
      "id": "teamwork",
      "name": "Teamwork",
      "type": "soft",
      "families": [
        {
          "id": "teamwork",
          "name": "Teamwork & collaboration",
          "domain_id": "soft_skills"
        }
      ],
      "domains": [
        {
          "id": "soft_skills",
          "name": "Soft Skills"
        }
      ],
      "broader": null
    },
    {
      "id": "microsoft_office",
      "name": "Microsoft Office",
      "type": "software",
      "families": [
        {
          "id": "office_software",
          "name": "Office software",
          "domain_id": "administration_office"
        }
      ],
      "domains": [
        {
          "id": "administration_office",
          "name": "Administration & Office"
        }
      ],
      "broader": null
    }
  ],
  "taxonomy_version": "v1",
  "credits_used": 1
}
{
  "error": {
    "code": "invalid_request",
    "message": "language must be fr or en.",
    "param": "language",
    "doc_url": "https://hirelayer.co/api-docs/errors#invalid_request"
  },
  "request_id": "6f1c2a4e-1d2b-4c3a-9e8f-0a1b2c3d4e5f"
}