API

API endpoints

All endpoints require authentication. Include your access token in the Authorization header: Authorization: Bearer your_access_token

InternalGET/v1/concept/{conceptScheme}/list

List All Concepts

Returns all available concepts for a given concept scheme. For example, to get all available skills, roles, or seniority levels.

Path Parameters

Name
conceptScheme
Type
string
Description
The type of concepts to retrieve. Valid values: role, skill, industry, organisation_size, organisation, seniority

Response

Name
version
Type
object
Description
Version information containing model and service versions.
Name
data
Type
array
Description
All available concepts for the requested scheme. Ordered alphabetically for text concepts (roles, skills) or by hierarchy for leveled concepts (seniority, organization size).

Request

GET

/v1/concept/{conceptScheme}/list

curl https://frontier.beamery.com/v1/concept/seniority/list \
  -H "Authorization: Bearer your_access_token"

Response

{
  "version": {
    "model_version": "1.0.0",
    "service_version": "4.9.250530.1844409513"
  },
  "data": [
    {
      "id": "seniority:intern",
      "label": "Intern",
      "level": 1
    },
    {
      "id": "seniority:junior",
      "label": "Junior",
      "level": 2
    },
    {
      "id": "seniority:mid-level",
      "label": "Mid-Level",
      "level": 3
    },
    {
      "id": "seniority:senior",
      "label": "Senior",
      "level": 4
    },
    {
      "id": "seniority:lead",
      "label": "Lead",
      "level": 5
    },
    {
      "id": "seniority:principal",
      "label": "Principal",
      "level": 6
    },
    {
      "id": "seniority:director",
      "label": "Director",
      "level": 7
    },
    {
      "id": "seniority:vp",
      "label": "VP",
      "level": 8
    },
    {
      "id": "seniority:c-level",
      "label": "C-Level",
      "level": 9
    }
  ]
}

InternalGET/v1/concept/{conceptScheme}/lookup

Lookup Concepts

Returns concepts by their IDs or labels. This endpoint allows you to retrieve specific concepts rather than listing all of them.

Path Parameters

Name
conceptScheme
Type
string
Description
The type of concepts to retrieve. Valid values: role, skill, industry, organisation_size, organisation, seniority

Query Parameters

Name
ids_or_labels
Type
array<string>
Description
Comma-separated list of concept IDs or labels to lookup. Case-insensitive. When using labels, reconciliation can help map unstructured input to canonical form.
Name
reconcile_labels
Type
boolean
Description
Whether to reconcile labels to canonical forms. Reconciliation adds additional fallback logic allowing effectively to map unstructured input data into canonical form.
Name
apply_job_architecture
Type
boolean
Description
Whether to apply Job Architecture translation. You should apply Job Architecture if you are working with vacancies or contacts who are KNOWN to work for Customer's organisation. Any processing of external contacts and candidates should not apply Job Architecture because people external to Customer's organisation don't use Customer-defined role/skill language.

Response

Name
version
Type
string
Description
Version of the service.
Name
data
Type
array<unknown>
Description
Concepts of concept-scheme type matching ids_or_labels on the input. Order of the output matches order of the input.

Request

GET

/v1/concept/{conceptScheme}/lookup

curl "https://frontier.beamery.com/v1/concept/role/lookup?ids_or_labels=Software%20Engineer,Data%20Scientist,role:product-manager&reconcile_labels=true&apply_job_architecture=true" \
  -H "Authorization: Bearer your_access_token"

Response

{
  "version": {
    "model_version": "1.0.0",
    "service_version": "4.9.250530.1844409513"
  },
  "data": [
    {
      "id": "role:software-engineer",
      "label": "Software Engineer",
      "type": "role",
      "canonical": true,
      "synonyms": ["Developer", "Programmer", "Software Developer"]
    },
    {
      "id": "role:data-scientist",
      "label": "Data Scientist",
      "type": "role",
      "canonical": true,
      "synonyms": ["ML Engineer", "Machine Learning Scientist"]
    },
    {
      "id": "role:product-manager",
      "label": "Product Manager",
      "type": "role",
      "canonical": true,
      "synonyms": ["PM", "Product Owner"]
    }
  ]
}

InternalPOST/v1/concept/{concept-scheme}/autocomplete

Autocomplete Suggestions

Provides auto-complete suggestions for concept-scheme concepts. Example is given for concept-scheme = skill.

Path Parameters

Name
concept-scheme
Type
enum: role, skill, industry, organisation_size, organisation, seniority
Description
No description

Request Body

Name
top_n
Type
integer
Description
Max number of suggested entities to return. Capped at 1000.
Name
query
Type
string
Description
Search query. This is direct user input to auto-complete.

Response

Name
version
Type
string
Description
Version of the service.
Name
data
Type
array
Description
Suggested best-fuzzy-matching entities for the query.

Request

POST

/v1/concept/{concept-scheme}/autocomplete

curl https://frontier.beamery.com/v1/concept/skill/autocomplete \
  -X POST \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
            "top_n": 10,
        "query": "pyth"
    }'

Response

{
  "version": {
    "model_version": "1.0.0",
    "service_version": "4.9.250530.1844409513"
  },
  "data": [
    {
      "id": "skill:python",
      "label": "Python",
      "type": "skill",
      "match_score": 1.0
    },
    {
      "id": "skill:python-django",
      "label": "Python Django",
      "type": "skill",
      "match_score": 0.95
    },
    {
      "id": "skill:python-flask",
      "label": "Python Flask",
      "type": "skill",
      "match_score": 0.94
    },
    {
      "id": "skill:python-pandas",
      "label": "Python Pandas",
      "type": "skill",
      "match_score": 0.93
    },
    {
      "id": "skill:python-numpy",
      "label": "Python NumPy",
      "type": "skill",
      "match_score": 0.92
    },
    {
      "id": "skill:pytorch",
      "label": "PyTorch",
      "type": "skill",
      "match_score": 0.85
    },
    {
      "id": "skill:python-scripting",
      "label": "Python Scripting",
      "type": "skill",
      "match_score": 0.84
    },
    {
      "id": "skill:python-testing",
      "label": "Python Testing",
      "type": "skill",
      "match_score": 0.83
    },
    {
      "id": "skill:python-data-analysis",
      "label": "Python Data Analysis",
      "type": "skill",
      "match_score": 0.82
    },
    {
      "id": "skill:python-web-development",
      "label": "Python Web Development",
      "type": "skill",
      "match_score": 0.81
    }
  ]
}

InternalGET/v1/concept/{sourceConceptScheme}/recommend/concept/{targetConceptScheme}

Recommends targetConceptScheme concepts related to sourceConceptScheme concepts. Recommended concepts are always canonical as of today. Example is given for sourceConceptScheme = role and targetConceptScheme = skill.

Path Parameters

Name
sourceConceptScheme
Type
string
Description
The source concept type. Valid values: role, skill
Name
targetConceptScheme
Type
string
Description
The target concept type to recommend. Valid values: role, skill, industry, seniority

Query Parameters

Name
ids_or_labels
Type
array<string>
Description
Comma-separated list of concept IDs or labels for recommendations. The format of the entities is unspecified (just pass anything reasonable): we execute concept reconciliation prior to generating recommendations.
Name
min_score
Type
number
Description
Minimum score threshold for recommendations. If no results match this criterion, empty arrays will be returned in the response. Must be in [0, 1] range.
Name
top_n
Type
integer
Description
Maximum number of recommendations to return. Capped at 100.
Name
apply_job_architecture
Type
boolean
Description
Whether to apply Job Architecture translation. You should apply Job Architecture if you are working with vacancies or contacts who are KNOWN to work for Customer's organisation. Any processing of external contacts and candidates should not apply Job Architecture because people external to Customer's organisation don't use Customer-defined role/skill language.

Response

Name
version
Type
string
Description
Version of the service.
Name
data
Type
array<unknown>
Description
Reconciled concepts of concept-scheme type matching ids_or_labels on the input. Order of the output matches order of the input.

Request

GET

/v1/concept/{sourceConceptScheme}/recommend/concept/{targetConceptScheme}

curl "https://frontier.beamery.com/v1/concept/role/recommend/concept/skill?ids_or_labels=Software%20Engineer,Data%20Scientist&min_score=0.7&top_n=10&apply_job_architecture=true" \
  -H "Authorization: Bearer your_access_token"

Response

{
  "version": {
    "model_version": "1.0.0",
    "service_version": "4.9.250530.1844409513"
  },
  "data": [
    {
      "input": "Software Engineer",
      "recommendations": [
        {
          "id": "skill:python",
          "label": "Python",
          "score": 0.95
        },
        {
          "id": "skill:javascript",
          "label": "JavaScript",
          "score": 0.93
        },
        {
          "id": "skill:java",
          "label": "Java",
          "score": 0.91
        },
        {
          "id": "skill:git",
          "label": "Git",
          "score": 0.90
        },
        {
          "id": "skill:docker",
          "label": "Docker",
          "score": 0.88
        },
        {
          "id": "skill:kubernetes",
          "label": "Kubernetes",
          "score": 0.85
        },
        {
          "id": "skill:sql",
          "label": "SQL",
          "score": 0.84
        },
        {
          "id": "skill:react",
          "label": "React",
          "score": 0.82
        },
        {
          "id": "skill:aws",
          "label": "AWS",
          "score": 0.80
        },
        {
          "id": "skill:agile",
          "label": "Agile",
          "score": 0.78
        }
      ]
    },
    {
      "input": "Data Scientist",
      "recommendations": [
        {
          "id": "skill:python",
          "label": "Python",
          "score": 0.98
        },
        {
          "id": "skill:machine-learning",
          "label": "Machine Learning",
          "score": 0.96
        },
        {
          "id": "skill:r",
          "label": "R",
          "score": 0.92
        },
        {
          "id": "skill:sql",
          "label": "SQL",
          "score": 0.90
        },
        {
          "id": "skill:statistics",
          "label": "Statistics",
          "score": 0.89
        },
        {
          "id": "skill:tensorflow",
          "label": "TensorFlow",
          "score": 0.87
        },
        {
          "id": "skill:pandas",
          "label": "Pandas",
          "score": 0.86
        },
        {
          "id": "skill:numpy",
          "label": "NumPy",
          "score": 0.85
        },
        {
          "id": "skill:deep-learning",
          "label": "Deep Learning",
          "score": 0.83
        },
        {
          "id": "skill:data-visualization",
          "label": "Data Visualization",
          "score": 0.80
        }
      ]
    }
  ]
}

InternalGET/v1/concept/{conceptScheme}/reconcile

Reconcile Concepts

Reconciles conceptScheme concepts into their canonical form. Example is given for conceptScheme = skill. Please note that reconciliation may fail for some records. Whenever this happens, concepts corresponding to the failed entities will be absent in the response completely.

Path Parameters

Name
conceptScheme
Type
string
Description
The type of concepts to reconcile. Valid values: role, skill, organisation

Query Parameters

Name
ids_or_labels
Type
array<string>
Description
Comma-separated list of concept IDs or labels to reconcile. The format of the entities is unspecified: API designed to guess it automatically. Untrusted input from third-party systems allowed here.
Name
top_n
Type
integer
Description
Maximum number of reconciliation candidates to return per input. Capped at 100.
Name
apply_job_architecture
Type
boolean
Description
Whether to apply Job Architecture translation. You should apply Job Architecture if you are working with vacancies or contacts who are KNOWN to work for Customer's organisation. Any processing of external contacts and candidates should not apply Job Architecture because people external to Customer's organisation don't use Customer-defined role/skill language.

Response

Name
version
Type
string
Description
Version of the service.
Name
data
Type
array<unknown>
Description
Reconciled concepts of concept-scheme type matching ids_or_labels on the input. Please note that reconciliation may fail for some records. Whenever this happens, concepts corresponding to the failed entities will be absent in the response completely.

Request

GET

/v1/concept/{conceptScheme}/reconcile

curl "https://frontier.beamery.com/v1/concept/skill/reconcile?ids_or_labels=python%20programming,javascript/typescript,machine%20learning%20ML,data%20sci&top_n=5&apply_job_architecture=false" \
  -H "Authorization: Bearer your_access_token"

Response

{
  "version": {
    "model_version": "1.0.0",
    "service_version": "4.9.250530.1844409513"
  },
  "data": [
    [
      {
        "id": "skill:python",
        "label": "Python",
        "type": "skill",
        "score": 1.0
      }
    ],
    [
      {
        "id": "skill:javascript",
        "label": "JavaScript",
        "type": "skill",
        "score": 0.95
      },
      {
        "id": "skill:typescript",
        "label": "TypeScript",
        "type": "skill",
        "score": 0.90
      }
    ],
    [
      {
        "id": "skill:machine-learning",
        "label": "Machine Learning",
        "type": "skill",
        "score": 0.98
      },
      {
        "id": "skill:ml",
        "label": "ML",
        "type": "skill",
        "score": 0.85
      }
    ],
    [
      {
        "id": "skill:data-science",
        "label": "Data Science",
        "type": "skill",
        "score": 0.92
      }
    ]
  ]
}

API

_Taxonomy

List All Concepts

Path Parameters

Response

Request

Response

Lookup Concepts

Path Parameters

Query Parameters

Response

Request

Response

Autocomplete Suggestions

Path Parameters

Request Body

Response

Request

Response

_Recommendation & Inference

Path Parameters

Query Parameters

Response

Request

Response

Reconcile Concepts

Path Parameters

Query Parameters

Response

Request

Response

API

_Taxonomy

List All Concepts

Path Parameters

Response

Request

Response

Lookup Concepts

Path Parameters

Query Parameters

Response

Request

Response

Autocomplete Suggestions

Path Parameters

Request Body

Response

Request

Response

_Recommendation & Inference

Recommend Concepts

Path Parameters

Query Parameters

Response

Request

Response

Reconcile Concepts

Path Parameters

Query Parameters

Response

Request

Response