--- name: "hiring_hire_applicant" area: "hiring" title: "Hire an applicant" price: "$0.25" method: "POST" url: "https://api.conecto.chat/v1/tools/hiring_hire_applicant" mcp_server: "https://api.conecto.chat/mcp/hiring" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/hiring/hiring_hire_applicant" --- # Hire an applicant (`hiring_hire_applicant`) Hires an applicant in one call: Hired in hiring, a person in HR with their résumé on file, and their onboarding checklist started. The hire in one call instead of five: the applicant moves to Hired, joins HR as a person (their name, the job's title, department and location unless given, start_date, work_email if they have one yet, their own email kept as personal_email), their résumé goes on their HR record, and the onboarding checklist named in checklist starts. Refused if they are already in HR. $0.25. Price: $0.25 a call. A call that fails costs nothing. ## Use it when A candidate accepted the offer. - For adding someone to HR who never applied, use [hr_save_people](https://conecto.chat/tools/hr/hr_save_people.md). ## Say this to your agent > Maria Santos accepted. She starts on November 2 as a mechanic, with the email maria@ from day one. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `applicant_id` | integer | yes | At least 1. | | | | `start_date` | string | yes | YYYY-MM-DD (matches ^\\d{4}-\\d{2}-\\d{2}$) | | | | `work_email` | string | no | Up to 254 characters. | | | | `title` | string | no | Up to 120 characters. | | | | `department` | string | no | Up to 120 characters. | | | | `location` | string | no | Up to 120 characters. | | | | `manager` | integer or string | no | Their manager's person_id or work email. | | | | `employment_type` | string | no | | `"full_time"`, `"part_time"`, `"contractor"`, `"intern"` | | | `checklist` | string | no | An onboarding checklist to start. Up to 80 characters. | | | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `hiring_hire_applicant` on the MCP server `https://api.conecto.chat/mcp/hiring` with these arguments: ```json { "applicant_id": 4101, "start_date": "2026-11-02", "work_email": "maria@halversoncycle.example" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/hiring_hire_applicant \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"applicant_id": 4101, "start_date": "2026-11-02", "work_email": "maria@halversoncycle.example"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "hiring_hire_applicant", "status": "succeeded", "replayed": false, "cost_usd": "$0.25", "balance_usd": "$19.75", "result": { "person": { "person_id": 4101, "name": "Maria Santos", "first_name": "Maria", "last_name": "Santos", "preferred_name": null, "work_email": "maria@halversoncycle.example", "job_title": "Bike mechanic", "department": "Workshop", "location": "Portland, OR", "manager": null, "employment_type": "full_time", "start_date": "2026-11-02", "probation_end": null, "end_date": null, "status": "active", "personal_email": "maria.santos@example.com", "phone": "+1 503 555 0130", "birthday": null, "emergency_contact": null, "notes": null, "custom": {}, "allowances": {}, "created_at": "2026-10-14T08:00:00+00:00", "updated_at": "2026-10-14T08:00:00+00:00" }, "applicant": { "applicant_id": 4101, "job": "bike-mechanic", "name": "Maria Santos", "email": "maria.santos@example.com", "phone": "+1 503 555 0130", "stage": "Hired", "rating": null, "source": "careers", "applied_at": "2026-10-14T08:00:00+00:00", "updated_at": "2026-10-14T08:00:00+00:00", "has_resume": true, "flags": [], "screened": null, "stage_since": "2026-10-14T08:00:00+00:00", "stages_reached": [ "Applied", "Hired" ], "assessments": [], "interview": null, "next_step": null, "match_score": null, "screening_summary": null, "passed_filter_at": null, "risk": "high", "signals": { "risk": "high", "high": [ { "code": "shared_phone", "applicant_ids": [ 2 ], "text": "The same phone number is on 1 other application under another email address." } ], "minor": [], "authentic": [ { "code": "name_in_email", "text": "Their name is in their email address." } ], "checked_at": "2026-10-14T08:00:00+00:00" }, "spam": false }, "onboarding_tasks": 0 } } ``` `result`: person: the new HR record (the job's title, department and location unless given); applicant: the application, now Hired; onboarding_tasks: how many checklist tasks started. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | No applicant of the business has that applicant_id. | Find them with hiring_list_applicants. | | `payment_required` | 402 | The application came in while the balance could not pay its fee, so it is held. | Top up; the application opens once its fee is paid. | | `already_hired` | 409 | The applicant is in HR already. | Find their record with hr_list_people. | | `not_found` | 404 | The checklist or the manager is not in HR. | Use a checklist from hr_get_settings and a person from hr_list_people. | | `invalid_input` | 400 | start_date, work_email or another field is not valid. | Fix the field the message names. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [hiring_setup_careers](https://conecto.chat/tools/hiring/hiring_setup_careers.md): Sets up the careers page at cncto.co/j/: its name, intro, website, reply-to address and who hears about applications. $0.001 a call. - [hiring_design_careers](https://conecto.chat/tools/hiring/hiring_design_careers.md): Gives the careers and job pages the business's own look: colours, a font, corners, a cover, a headline and its own CSS. $0.001 a call. - [hiring_create_job](https://conecto.chat/tools/hiring/hiring_create_job.md): Posts a job with its own page and application form on the careers page. $0.01 a call. - [hiring_update_job](https://conecto.chat/tools/hiring/hiring_update_job.md): Changes a job's details, its criteria and filter, or opens or closes it. $0.01 a call. - [hiring_list_jobs](https://conecto.chat/tools/hiring/hiring_list_jobs.md): The business's jobs with their status, page and applicants per stage. Free up to 1,000,000 reads a month. - [hiring_list_applicants](https://conecto.chat/tools/hiring/hiring_list_applicants.md): Applicants, newest or best match first: for one job or all, by stage, screening, risk, name or email, or the ones kept as spam. Free up to 1,000,000 reads a month. - [hiring_get_applicant](https://conecto.chat/tools/hiring/hiring_get_applicant.md): One application in full: answers, résumé link, screening and match score, the checks on who sent it, notes and history. Free up to 1,000,000 reads a month. - [hiring_screen_queue](https://conecto.chat/tools/hiring/hiring_screen_queue.md): The next applications nobody has screened, with the job's criteria and the résumé as text, blind by default. Free up to 1,000,000 reads a month. - [hiring_record_screening](https://conecto.chat/tools/hiring/hiring_record_screening.md): Saves a review of one application: strong, partial or weak, a summary, and each criterion with its evidence. $0.01 a call. - [hiring_mark_spam](https://conecto.chat/tools/hiring/hiring_mark_spam.md): Moves one application to spam or back, and can block the network and email domain it came from. $0.001 a call. - [hiring_get_blocklist](https://conecto.chat/tools/hiring/hiring_get_blocklist.md): The networks and email domains whose applications are kept as spam. Free up to 1,000,000 reads a month. - [hiring_update_blocklist](https://conecto.chat/tools/hiring/hiring_update_blocklist.md): Blocks or unblocks networks and email domains; what comes from them is kept as spam, with no fee and no emails. $0.001 a call. - [hiring_move_applicant](https://conecto.chat/tools/hiring/hiring_move_applicant.md): Moves an applicant to another stage of their job, with a note; the candidate is not told. $0.01 a call. - [hiring_note](https://conecto.chat/tools/hiring/hiring_note.md): Adds a note to an applicant, rates them 1 to 5, or both. $0.01 a call. - [hiring_email_applicant](https://conecto.chat/tools/hiring/hiring_email_applicant.md): Emails an applicant in the business's name; replies go to the careers page's reply-to address. $0.02 a call. - [hiring_invite_to_interview](https://conecto.chat/tools/hiring/hiring_invite_to_interview.md): Emails an applicant a link to book an interview on one of the calendar's meeting types, and can move them to a stage. $0.05 a call. - [hiring_save_assessment](https://conecto.chat/tools/hiring/hiring_save_assessment.md): Writes a skills test or changes one: questions scored on their own, written answers to mark, a time limit and shuffling. $0.01 a call. - [hiring_list_assessments](https://conecto.chat/tools/hiring/hiring_list_assessments.md): The business's skills tests: title, questions, time limit, and how many were sent and completed. Free up to 1,000,000 reads a month. - [hiring_send_assessment](https://conecto.chat/tools/hiring/hiring_send_assessment.md): Emails an applicant their own link to a skills test. $0.02 a call. - [hiring_assessment_results](https://conecto.chat/tools/hiring/hiring_assessment_results.md): An applicant's tests: status, score, each answer against the expected one, answers to mark, time taken and how often they left the page. Free up to 1,000,000 reads a month. - [hiring_mark_assessment](https://conecto.chat/tools/hiring/hiring_mark_assessment.md): Gives points to the written answers of a completed test. $0.01 a call. - [hiring_delete_assessment](https://conecto.chat/tools/hiring/hiring_delete_assessment.md): Deletes a skills test with every candidate's answers to it. Free. - [hiring_delete_applicant](https://conecto.chat/tools/hiring/hiring_delete_applicant.md): Deletes an applicant and their résumé for good. Free. - [hiring_dashboard_link](https://conecto.chat/tools/hiring/hiring_dashboard_link.md): A one-time link to hiring at a glance: each applicant's stage and next step, the tests and interviews waiting, and the open jobs. Free up to 1,000,000 reads a month.