CvDeepMatchRequirements

The matching engine's position-config contract — the requirements object inside the submitted config. Mirrors the Position Metadata Specification that the engine consumes.

workExperience and skills are required; education is optional at submit (auto-filled with safe defaults when omitted), but if you send it you must send the full block — see the Position config reference guide for the routing rules, the 1–5 importance scale, and the cardinality limits.

Every importance field anywhere in this schema is an integer 1–5. The engine divides it by 5 to derive a weight; 0, negative, fractional, or >5 values do not error at this layer but produce silently-wrong match scores.

workExperience objectrequired

How the candidate's professional history is scored: the experience window, which dimensions matter, and which industries / roles / companies count as relevant.

fromintegerrequired

Required. Minimum years of relevant experience the role requires. Must satisfy from ≤ to. The engine converts this to months internally (from × 12).

Possible values: >= 0

Example: 5

tointegerrequired

Required. Upper bound in years — beyond it a candidate may be considered overqualified. Convention: when the JD names only a minimum and no maximum, set to to 15 rather than capping low. Must satisfy from ≤ to.

Possible values: >= 0

Example: 10

importanceintegerrequired

Required. Weight of the qualitative work-experience dimension (how relevant the candidate's roles are), integer 1–5.

Possible values: >= 1 and <= 5

Example: 5

time_importanceinteger

Weight of the quantitative (time / recency) dimension — how much total relevant years and recency of experience matter versus pure role relevance. Integer 1–5.

Possible values: >= 1 and <= 5

Example: 3

transferable_skillsboolean

Whether experience from adjacent roles / industries should count as transferable toward this position. true widens what the engine treats as relevant experience.

Example: true

minimum_job_experience_durationinteger

Minimum duration, in months, that a single job must have lasted for it to be counted as a relevant experience. Filters out very short stints. Typical value: 3–6.

Possible values: >= 0

Example: 4

threshold_for_one_exp_relevanceinteger

Threshold, in months, above which a single long experience can satisfy the relevance requirement on its own (fast-path). Convention default: 84 (= 7 years).

Possible values: >= 0

Example: 84

relevant_rolesstring[]

Role / job titles considered closely related to the target position (e.g. "Backend Engineer", "Platform Engineer"). May be an empty array. This is where job-title relatedness belongs — not in skills or qualifications.

Example: ["Backend Engineer","Platform Engineer"]

relevant_companiesstring[]

Company names whose experience is considered especially relevant (e.g. direct competitors, recognised industry leaders). May be an empty array.

Example: ["Stripe","Datadog"]

relevant_industriesstring[]required

Required, 1–3 items, non-empty. Broad market-recognised industry labels the role belongs to. An empty list breaks the reasoning prompt; more than 3 dilutes industry-correlation scoring. Each entry should also appear in industries_config.

Possible values: >= 1, <= 3

Example: ["SaaS","Fintech"]

industries_config object[]required

Required. Per-industry importance weights — one entry per relevant_industries entry (same count, mirroring names). Carries the weight used in the scoring layer; the bare relevant_industries list is what the reasoning step reads.

Possible values: >= 1, <= 3

Array [

namestringrequired

Industry name — should match an entry in relevant_industries.

Possible values: non-empty

Example: SaaS

importanceintegerrequired

How much this industry weighs, integer 1–5.

Possible values: >= 1 and <= 5

Example: 5

]

skills objectrequired

How the candidate's skills and competencies are scored. Skills split into concrete hard/soft skills and broader minimal/preferable qualifications. Languages never go here — they belong in language_skills_config.

importanceintegerrequired

Required. Weight of the whole skills dimension in the overall score, integer 1–5.

Possible values: >= 1 and <= 5

Example: 5

skills_config objectrequired

The structured skills payload. Each skill list is an array of CvDeepMatchSkillItem objects ({name, importance, id?} — see its own schema page). All lists are optional except the requirements toggle block.

hard_skills object[]

Concrete, CV-visible technical skills, tools, systems, or methods (e.g. "PostgreSQL", "Kubernetes"). Max 5; hard_skills + soft_skills combined must be ≤ 10. Use the cap to force prioritisation — over-long lists collapse scores across all candidates.

Possible values: <= 5

Array [

namestringrequired

The skill / qualification label, e.g. "PostgreSQL", "Customer-Centric Communication". Non-empty string. This is the exact phrase the matching engine reasons about against the CV, so keep it concise and recognisable — not a full sentence.

Possible values: non-empty

Example: PostgreSQL

importanceintegerrequired

How much this individual entry weighs, integer 1–5. 1 = nice-to-have, 5 = critical. The engine divides this by 5 to get a weight, so values outside 1–5 break scoring (see the Position config reference guide for the full importance scale).

Possible values: >= 1 and <= 5

Example: 5

idstring

Optional stable identifier for your own correlation (e.g. "hard_skill_001"). Not used by the matching engine — purely a convenience for round-tripping the config in your system.

]

soft_skills object[]

Behavioural / interpersonal traits evidenced on a CV (e.g. "Problem-Solving", "Stakeholder Communication"). Max 5; hard_skills + soft_skills combined ≤ 10.

Possible values: <= 5

Array [

namestringrequired

Possible values: non-empty

Example: PostgreSQL

importanceintegerrequired

Possible values: >= 1 and <= 5

Example: 5

idstring

Optional stable identifier for your own correlation (e.g. "hard_skill_001"). Not used by the matching engine — purely a convenience for round-tripping the config in your system.

]

minimal_qualifications object[]

Essential broad competencies that cannot be reduced to a single hard/soft skill label and describe capability depth (e.g. "Demonstrated experience managing high-volume customer interactions with measurable outcomes"). Max 3. Do not put employment conditions, availability, willingness statements, or time-based requirements here — see the Position config reference guide for the routing rules.

Possible values: <= 3

Array [

namestringrequired

Possible values: non-empty

Example: PostgreSQL

importanceintegerrequired

Possible values: >= 1 and <= 5

Example: 5

idstring

Optional stable identifier for your own correlation (e.g. "hard_skill_001"). Not used by the matching engine — purely a convenience for round-tripping the config in your system.

]

preferable_qualifications object[]

Advantageous (nice-to-have) broad competencies, same semantics and constraints as minimal_qualifications. Max 3.

Possible values: <= 3

Array [

namestringrequired

Possible values: non-empty

Example: PostgreSQL

importanceintegerrequired

Possible values: >= 1 and <= 5

Example: 5

idstring

Optional stable identifier for your own correlation (e.g. "hard_skill_001"). Not used by the matching engine — purely a convenience for round-tripping the config in your system.

]

requirements objectrequired

Required toggle block. Whether the engine scores the qualification lists at all. Both boolean keys must be present.

minimal_qualificationsbooleanrequired

Whether to score minimal_qualifications.

Example: true

preferable_qualificationsbooleanrequired

Whether to score preferable_qualifications.

Example: true

language_skills_config object

Optional (auto-filled when omitted). The only place language requirements belong — never in hard_skills / soft_skills / qualifications. Use plain language names with no proficiency suffix ("English" ✓, "English (B2+)" ✗); express proficiency in your own explanations block.

requiredboolean

Whether language is part of scoring.

Example: true

required_languagesstring[]

Plain names of languages the role requires. No proficiency suffixes, parentheses, brackets, or slashes — those are rejected with INVALID_INPUT.

Example: ["English"]

prefered_languagesstring[]

Plain names of nice-to-have languages. Note the spelling — one r (prefered_languages) is the exact key the engine reads; preferred_languages is silently ignored.

Example: ["Spanish"]

target_countriesstring[]

Countries where work/living experience demonstrates real-world use of the language (e.g. for English: "United States", "United Kingdom"). Not the job's location. Leave empty if the JD does not value it.

Example: ["United States","United Kingdom"]

importanceinteger

Weight of the language dimension, integer 1–5.

Possible values: >= 1 and <= 5

Example: 5

education object

Optional at submit — auto-filled with safe defaults when omitted. If you send it, send the full block: to disable education scoring set is_enabled: false (do not drop the block — the engine still reads its structure). Controls academic (degree) and non-academic (licenses/certifications) scoring.

is_enabledboolean

Master toggle for whether education is scored at all. When false, education contributes zero — but the full block must still be present.

Example: false

importanceinteger

Weight of the whole education dimension, integer 1–5.

Possible values: >= 1 and <= 5

Example: 2

academic object

Degree / formal-education scoring.

importanceinteger

Weight of the academic sub-dimension, integer 1–5. Keep low (1–2) for roles where a degree is not critical; reserve 4–5 for roles where it genuinely is.

Possible values: >= 1 and <= 5

Example: 2

requiredboolean

Whether a matching degree is mandatory.

Example: false

degree_levelstringnullable

Target degree level, e.g. "Bachelor", "Master", "High School", or null for no specific level.

Example: Bachelor

fields_of_studystring[]

Relevant fields of study, e.g. "Computer Science".

Example: ["Computer Science","Software Engineering"]

relevant_institutionsstring[]

Institutions whose graduates are considered especially relevant. Usually empty.

Example: []

study_statusstring

Which study stage qualifies — case-sensitive, one of Both, Undergraduate, Graduate. Any other value (e.g. "Graduated") is rejected and would short-circuit academic scoring downstream.

Possible values: [Both, Undergraduate, Graduate]

Example: Both

expected_graduation_datestringnullable

Expected graduation date for candidates still studying, or null. Free-form date string.

Example: null

non_academic object

Licenses / certifications scoring.

importanceinteger

Weight of the non-academic sub-dimension, integer 1–5.

Possible values: >= 1 and <= 5

Example: 3

requiredboolean

Whether non-academic credentials are mandatory.

Example: false

include_licenses_and_certificationsboolean

Whether to score licenses & certifications at all. Must be present whenever the education block is sent.

Example: false

licenses_and_certificationsstring[]

Relevant licenses / certifications, e.g. "AWS Solutions Architect". Usually empty unless the role requires them.

Example: []

licenses_and_certifications_importanceinteger

Weight of the licenses/certifications signal, integer 1–5.

Possible values: >= 1 and <= 5

Example: 3

namestring

Optional inside requirements (usually set at the top level of config). The target position name; position_name is accepted as an alias and normalised to name.

position_idstring

Optional echo of the job identifier (charset [A-Za-z0-9._-], 1–28 chars). Normally supplied as the multipart position_id field, not inside config.

application_idstring

Optional, free-form. Stored for your traceability; not used by the matching engine.

job_descriptionstring

Optional echo of the JD text. Normally supplied as the multipart job_description field rather than inside config.

CvDeepMatchRequirements
{
  "workExperience": {
    "from": 5,
    "to": 10,
    "importance": 5,
    "time_importance": 3,
    "transferable_skills": true,
    "minimum_job_experience_duration": 4,
    "threshold_for_one_exp_relevance": 84,
    "relevant_roles": [
      "Backend Engineer",
      "Platform Engineer"
    ],
    "relevant_companies": [
      "Stripe",
      "Datadog"
    ],
    "relevant_industries": [
      "SaaS",
      "Fintech"
    ],
    "industries_config": [
      {
        "name": "SaaS",
        "importance": 5
      }
    ]
  },
  "skills": {
    "importance": 5,
    "skills_config": {
      "hard_skills": [
        {
          "name": "PostgreSQL",
          "importance": 5,
          "id": "string"
        }
      ],
      "soft_skills": [
        {
          "name": "PostgreSQL",
          "importance": 5,
          "id": "string"
        }
      ],
      "minimal_qualifications": [
        {
          "name": "PostgreSQL",
          "importance": 5,
          "id": "string"
        }
      ],
      "preferable_qualifications": [
        {
          "name": "PostgreSQL",
          "importance": 5,
          "id": "string"
        }
      ],
      "requirements": {
        "minimal_qualifications": true,
        "preferable_qualifications": true
      }
    },
    "language_skills_config": {
      "required": true,
      "required_languages": [
        "English"
      ],
      "prefered_languages": [
        "Spanish"
      ],
      "target_countries": [
        "United States",
        "United Kingdom"
      ],
      "importance": 5
    }
  },
  "education": {
    "is_enabled": false,
    "importance": 2,
    "academic": {
      "importance": 2,
      "required": false,
      "degree_level": "Bachelor",
      "fields_of_study": [
        "Computer Science",
        "Software Engineering"
      ],
      "relevant_institutions": [],
      "study_status": "Both",
      "expected_graduation_date": null
    },
    "non_academic": {
      "importance": 3,
      "required": false,
      "include_licenses_and_certifications": false,
      "licenses_and_certifications": [],
      "licenses_and_certifications_importance": 3
    }
  },
  "name": "string",
  "position_id": "string",
  "application_id": "string",
  "job_description": "string"
}