--- updatedAt: 2026-05-22T10:56:26.000Z agentTools: projectIndex: https://docs.oysterhr.com/v0.1/llms.txt --- # Fetch the dynamic hiring form for an employment Returns the country-specific dynamic hiring form (e.g. CBA level) for an employment. Returns an empty sections array when no dynamic form exists for the employment's country. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Endpoints", "version": "v0.1" }, "components": { "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } }, "schemas": { "dynamicForm": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "fields": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/textField" }, { "$ref": "#/components/schemas/dateField" }, { "$ref": "#/components/schemas/selectField" }, { "$ref": "#/components/schemas/countryField" }, { "$ref": "#/components/schemas/subdivisionField" }, { "$ref": "#/components/schemas/groupField" } ] } } }, "required": [ "title", "fields" ] } }, "state": { "type": "string", "enum": [ "DRAFT", "UNSTARTED", "COMPLETED" ] } }, "required": [ "sections" ] }, "textField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT" ] }, "value": { "oneOf": [ { "type": "string", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "dateField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DATE" ] }, "value": { "oneOf": [ { "type": "string", "format": "date", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "selectField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SELECT" ] }, "mode": { "type": "string", "enum": [ "RADIO", "DROPDOWN", "CHECKBOX" ] }, "select": { "type": "string", "enum": [ "ONE", "MULTI" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "value": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "label", "mode", "select", "options", "value" ] } ] }, "countryField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY" ] }, "value": { "oneOf": [ { "type": "string", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "subdivisionField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SUBDIVISION" ] }, "value": { "oneOf": [ { "type": "string", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "groupField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "GROUP" ] }, "title": { "oneOf": [ { "type": "string" } ] }, "fields": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/textField" }, { "$ref": "#/components/schemas/dateField" }, { "$ref": "#/components/schemas/countryField" }, { "$ref": "#/components/schemas/subdivisionField" }, { "$ref": "#/components/schemas/selectField" }, { "$ref": "#/components/schemas/groupField" }, { "$ref": "#/components/schemas/bankAccountField" }, { "$ref": "#/components/schemas/documentField" } ] } } }, "required": [ "title", "fields" ] } ] }, "bankAccountField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BANK_ACCOUNT" ] }, "value": { "oneOf": [ { "type": "boolean", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "documentField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DOCUMENT" ] }, "value": { "oneOf": [ { "type": "object", "nullable": true, "properties": { "id": { "type": "string" } }, "required": [ "id" ] } ] } }, "required": [ "label", "value" ] } ] }, "baseField": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "TEXT", "DATE", "COUNTRY", "SELECT", "GROUP", "BANK_ACCOUNT", "DOCUMENT", "SUBDIVISION" ] }, "category": { "type": "string", "nullable": true }, "required": { "type": "boolean" }, "enabled": { "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": true } ] }, "label": { "type": "string" }, "assistiveText": { "type": "string" }, "assistiveTextPlain": { "type": "string" }, "templateDocuments": { "type": "array", "description": "Oyster template documents linked from the field's assistive text.", "items": { "type": "object", "properties": { "url": { "type": "string" }, "lastModifiedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "url", "lastModifiedAt" ] } }, "validationMessage": { "type": "string" } }, "required": [ "id", "type", "required", "category", "enabled", "templateDocuments" ] } } }, "paths": { "/v0.1/hiring/employments/{id}/dynamic/form": { "get": { "summary": "Fetch the dynamic hiring form for an employment", "tags": [ "Employments" ], "description": "Returns the country-specific dynamic hiring form (e.g. CBA level) for an employment. Returns an empty sections array when no dynamic form exists for the employment's country.", "security": [ { "bearer_auth": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "description": "Employment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully returns the dynamic hiring form", "content": { "application/json": { "examples": { "Successfully returns the dynamic hiring form": { "value": { "data": { "sections": [ { "title": "Professional Level", "fields": [ { "id": "recently_categorised_in_cba_level", "type": "SELECT", "label": "Has this Team Member been recently categorised in a CBA Level in Italy?", "category": null, "required": true, "enabled": true, "value": "yes", "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" }, { "value": "not_sure", "label": "Not sure" } ], "mode": "RADIO", "select": "ONE" }, { "id": "current_level_assigned", "type": "TEXT", "label": "What is the current or most recent level assigned to this Team Member in Italy?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "recently_categorised_in_cba_level", "value": "yes" } ] }, "value": "Ingegnere Senior", "templateDocuments": [] }, { "id": "cba_assigned", "type": "TEXT", "label": "In which CBA?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "recently_categorised_in_cba_level", "value": "yes" } ] }, "value": "Contratto Collettivo Nazionale di Lavoro", "templateDocuments": [] }, { "id": "will_be_an_executive", "type": "SELECT", "label": "Will this Team Member be an Executive with a C-level position or will they report directly to a C-level position?", "category": null, "required": true, "enabled": { "anyOf": [ { "fieldId": "recently_categorised_in_cba_level", "value": "no" }, { "fieldId": "recently_categorised_in_cba_level", "value": "not_sure" } ] }, "value": "no", "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_have_decision_making_powers", "type": "SELECT", "label": "Will this Team Member have broad autonomous decision-making powers in order to influence the management and day-to-day operations of your company (or a branch of it)?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_be_an_executive", "value": "yes" } ] }, "value": null, "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_be_able_to_hire_and_fire", "type": "SELECT", "label": "Will this Team Member have the authority to hire and fire other employees?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_have_decision_making_powers", "value": "yes" } ] }, "value": null, "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_be_an_upper_manager", "type": "SELECT", "label": "Will this Team Member be an upper manager such as a VP, the Head of a department, Director or Lead?", "category": null, "required": true, "enabled": { "anyOf": [ { "fieldId": "will_be_an_executive", "value": "no" }, { "fieldId": "will_have_decision_making_powers", "value": "no" }, { "fieldId": "will_be_able_to_hire_and_fire", "value": "no" } ] }, "value": "no", "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_be_involved_in_core_objectives_definition", "type": "SELECT", "label": "Will this Team Member be directly involved in the definition, development and implementation of the core objectives of your company?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_be_an_upper_manager", "value": "yes" } ] }, "value": null, "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_manager_be_an_executive", "type": "SELECT", "label": "Will this Team Member's manager be an Executive with a C-Level position or someone who reports directly to a C-level position?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_be_involved_in_core_objectives_definition", "value": "yes" } ] }, "value": null, "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_perform_managerial_functions", "type": "SELECT", "label": "Will this Team Member perform managerial and supervisory functions of people or projects within their role?", "category": null, "required": true, "enabled": { "anyOf": [ { "fieldId": "will_be_an_upper_manager", "value": "no" }, { "fieldId": "will_be_involved_in_core_objectives_definition", "value": "no" }, { "fieldId": "will_manager_be_an_executive", "value": "no" } ] }, "value": "no", "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_make_autonomous_decisions", "type": "SELECT", "label": "Will this Team Member make autonomous decisions within the scope of the responsibilities delegated to them?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_perform_managerial_functions", "value": "yes" } ] }, "value": "yes", "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_manager_have_an_upper_managerial_responsibility", "type": "SELECT", "label": "Will this Team Member's manager have an upper-managerial level of responsibility such as VP, Head, Director or Lead?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_make_autonomous_decisions", "value": "no" } ] }, "value": "yes", "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_be_an_individual_contributor", "type": "SELECT", "label": "Will this Team Member be an individual contributor (e.g. no direct reports)?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_manager_have_an_upper_managerial_responsibility", "value": "no" } ] }, "value": "no", "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_perform_skilled_creative_work", "type": "SELECT", "label": "Will this Team Member perform skilled creative work in the context of their role?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_manager_have_an_upper_managerial_responsibility", "value": "no" } ] }, "value": null, "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "will_manager_be_someone_below_an_upper_manager_level", "type": "SELECT", "label": "Will this Team Member's manager be someone below an Upper Manager level such as Head, Director or Lead?", "category": null, "required": true, "enabled": { "allOf": [ { "fieldId": "will_manager_have_an_upper_managerial_responsibility", "value": "no" } ] }, "value": null, "templateDocuments": [], "options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ], "mode": "RADIO", "select": "ONE" }, { "id": "comments", "type": "TEXT", "label": "Comments and feedback", "category": null, "required": false, "enabled": { "anyOf": [ { "fieldId": "will_be_able_to_hire_and_fire", "value": "yes" }, { "fieldId": "will_manager_be_an_executive", "value": "yes" }, { "fieldId": "will_perform_managerial_functions", "value": "no" }, { "fieldId": "will_make_autonomous_decisions", "value": "yes" }, { "fieldId": "will_manager_have_an_upper_managerial_responsibility", "value": "yes" }, { "fieldId": "will_be_an_individual_contributor", "value": "yes" }, { "fieldId": "will_be_an_individual_contributor", "value": "no" }, { "fieldId": "will_perform_skilled_creative_work", "value": "yes" }, { "fieldId": "will_perform_skilled_creative_work", "value": "no" }, { "fieldId": "will_manager_be_someone_below_an_upper_manager_level", "value": "yes" }, { "fieldId": "will_manager_be_someone_below_an_upper_manager_level", "value": "no" } ] }, "value": null, "templateDocuments": [] } ] } ], "state": "DRAFT" } } }, "Returns a field with a linked template document": { "value": { "data": { "sections": [ { "title": "Professional Level", "fields": [ { "id": "supporting_document_reference", "type": "TEXT", "label": "Supporting document reference", "category": null, "required": true, "enabled": true, "value": null, "templateDocuments": [ { "url": "https://oysterhr-public-assets.s3.eu-west-1.amazonaws.com/downloads/forms/Example+Template.pdf", "lastModifiedAt": "2025-01-02T03:04:05Z" } ], "assistiveText": "Download the form from here.", "assistiveTextPlain": "Download the form from" } ] } ], "state": "UNSTARTED" } } }, "Returns empty sections when no dynamic form exists for the country": { "value": { "data": { "sections": [] } } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/dynamicForm" } }, "required": [ "data" ] } } } } } } } }, "servers": [ { "url": "https://api.oysterhr.com", "description": "Production server" }, { "url": "https://api-sandbox.oysterhr.com", "description": "Sandbox server" } ] } ```