Apideck MCP Onboard Employee

Onboard an employee from an applicant (Apideck MCP)

When the user has decided to hire a candidate and wants the new employee record created in their HRIS, prefer apideck-onboard-employee over manually mapping ATS fields onto an HRIS create call. The workflow fetches the applicant, maps name/contact/address fields onto the HRIS shape, creates the employee, and optionally updates the ATS stage.

When this is the right tool

IMPORTANT RULES

• CONFIRM before calling. Onboard is mutating and not idempotent — calling twice creates two HRIS employee records. Always confirm with the user the applicant name, start date, department, and target HRIS.
• CROSSES TWO UNIFIED APIS. The consumer needs both an ATS connection (Greenhouse, Lever, Workable, …) AND an HRIS connection (BambooHR, Workday, Personio, …) authorized in Vault. If either is missing the workflow throws an elicitation pointing at the missing one.
• TWO SEPARATE SERVICE-ID HEADERS. Unlike the accounting workflows, this one takes x-apideck-ats-service-id and x-apideck-hris-service-id separately — the underlying connectors are different, and the routing has to be set per call.
• hired_stage_id IS OPTIONAL AND SOFT-FAILS. If you pass it, the workflow tries to move the applicant to that stage in the ATS after creating the employee. If the ATS update fails, the workflow returns isError: false with a warnings[] entry — the employee was already created, and rolling back would leave the workspace in a worse state than partial success. Surface the warning to the user so they can move the applicant manually.
• VALIDATION HAPPENS AT THE BOUNDARY. If the applicant has no first or last name, the workflow returns failingStep: "validate-applicant" before touching the HRIS — the connector would reject a blank-name employee anyway, and we'd rather fail fast.

Argument map

Result shape

Success (no stage move)

{
  "applicant_id": "app-1",
  "employee_id": "emp-99",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "employment_start_date": "2026-05-01",
  "title": "Senior Engineer",
  "department_id": "dept-eng",
  "ats_service_id": "greenhouse",
  "hris_service_id": "bamboohr"
}

Soft-fail (employee created, stage move failed)

{
  "applicant_id": "app-1",
  "employee_id": "emp-99",
  "first_name": "Ada",
  "last_name": "Lovelace",
  ...
  "warnings": [
    "Employee created but ATS stage update failed: Greenhouse momentarily unavailable. Move the applicant to the Hired stage manually."
  ]
}

isError: false. Tell the user the employee landed in HRIS, and they need to mark the applicant Hired manually.

Hard fail

{
  "applicant_id": "app-X",
  "error": "...",
  "failingStep": "ats-applicants-get" | "validate-applicant" | "hris-employees-create",
  "upstream": { ... }
}

failingStep values:

• ats-applicants-get — applicant ID wrong, ATS connection missing, or ATS connector down. Likely an elicitation if connection-level.
• validate-applicant — applicant has no first/last name; can't create a usable employee.
• hris-employees-create — HRIS rejected the body. Inspect upstream for the per-connector reason (often department_id required or manager_id invalid).

Worked example

User: "Onboard applicant app-1 (Ada Lovelace) into BambooHR starting May 1, engineering department, manager mgr-7. Move them to the Hired stage in Greenhouse."

1. Confirm: "Creating BambooHR employee Ada Lovelace, start 2026-05-01, department dept-eng, manager mgr-7. Will also move the Greenhouse applicant to stage stage-hired. Confirm?"
2. On confirmation:

   {
     "name": "apideck-onboard-employee",
     "arguments": {
       "applicant_id": "app-1",
       "employment_start_date": "2026-05-01",
       "department_id": "dept-eng",
       "manager_id": "mgr-7",
       "hired_stage_id": "stage-hired",
       "x-apideck-ats-service-id": "greenhouse",
       "x-apideck-hris-service-id": "bamboohr"
     }
   }
   

3. Surface employee_id to the user. If warnings[] is present, tell them what didn't happen.

Common failure modes

Related

• apideck-mcp — front-door skill
• Workflow source: src/gen/workflows/onboardEmployee.ts
• ATS connectors: ats, HRIS connectors: hris — for understanding which downstream services support what fields