--- name: "hr_request_leave" area: "hr" title: "Request time off" price: "$0.01" method: "POST" url: "https://api.conecto.chat/v1/tools/hr_request_leave" mcp_server: "https://api.conecto.chat/mcp/hr" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/hr/hr_request_leave" --- # Request time off (`hr_request_leave`) Asks for time off for someone, counting working days less holidays; it waits for a decision unless approved at once. Ask for time off for someone, from start to end (default: one day), with a half day on the first and/or last day if wanted. Only working days count, minus the holidays of everyone and of their location; leave that crosses into a new leave year counts in each. Refused when it overlaps their pending or approved leave, has no working days, falls outside their employment or they have left, or when a tracked balance (after pending requests) can't take it, unless allow_negative: true (the reply then says how far below 0 it goes). It waits for hr_decide_leave unless approve: true decides at once. Returns the request_id and the balance after it. Price: $0.01 a call. A call that fails costs nothing. ## Use it when Someone asks for a holiday, a sick day or a day off. ## Say this to your agent > Tom wants December 21 to 31 off for Christmas, with the 31st as a half day. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `person` | integer or string | yes | The person_id, or their work email. 1 to 254 characters, at least 1. | | | | `leave_type` | string | yes | A leave type by name, e.g. "Vacation". 1 to 60 characters. | | | | `start` | string | yes | YYYY-MM-DD (matches ^\\d{4}-\\d{2}-\\d{2}$) | | | | `end` | string | no | The last day off, YYYY-MM-DD. Default: start. Matches ^\\d{4}-\\d{2}-\\d{2}$. | | | | `half_start` | boolean | no | The first day is a half day. | | `false` | | `half_end` | boolean | no | The last day is a half day. | | `false` | | `note` | string | no | Up to 1,000 characters. | | | | `approve` | boolean | no | | | `false` | | `allow_negative` | boolean | no | | | `false` | ## Example Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. MCP: call `hr_request_leave` on the MCP server `https://api.conecto.chat/mcp/hr` with these arguments: ```json { "person": "tom.okafor@hansenvoss.example", "leave_type": "Vacation", "start": "2026-12-21", "end": "2026-12-31", "half_end": true, "note": "Christmas with family" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/hr_request_leave \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"person": "tom.okafor@hansenvoss.example", "leave_type": "Vacation", "start": "2026-12-21", "end": "2026-12-31", "half_end": true, "note": "Christmas with family"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "hr_request_leave", "status": "succeeded", "replayed": false, "cost_usd": "$0.01", "balance_usd": "$19.75", "result": { "request": { "request_id": 4101, "person": { "person_id": 4102, "name": "Tom Okafor" }, "leave_type": "Vacation", "paid": true, "start": "2026-12-21", "end": "2026-12-31", "half_start": false, "half_end": true, "days": "7.5", "hours": "60", "by_leave_year": { "2026": "7.5" }, "status": "pending", "note": "Christmas with family", "decision_note": null, "decided_by": null, "decided_at": null, "allow_negative": false, "created_at": "2026-10-14T08:00:00+00:00" }, "balances": [ { "leave_type": "Vacation", "tracked": true, "paid": true, "year": 2026, "from": "2026-01-01", "to": "2026-12-31", "annual_days": "28", "own_allowance": false, "accrual": "yearly", "months_counted": 12, "entitlement": "28", "carried_over": "0", "adjustments": "0", "approved": "0", "balance": "28", "pending": "7.5", "available_after_pending": "20.5" } ] } } ``` `result`: request: its request_id, person, type, dates, half days, days counted and status; balances: the person's balance of that type after it. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | No person of the business has that person_id or work email. | Find them with hr_list_people. | | `not_found` | 404 | No leave type has that name. | Call hr_get_settings, or add it with hr_save_leave_type. | | `invalid_input` | 400 | A date is not a date like 2026-10-01, or from is after to. | Fix the date. | | `not_enough_days` | 409 | The balance (after pending requests) cannot take the days. | Ask for fewer days, or pass allow_negative: true if the owner agrees. | | `overlaps` | 409 | The person already has leave in those days. | Change or cancel the other request first. | | `no_working_days` | 400 | The dates hold no working days. | Check the dates. | | `outside_employment` | 409 | The dates fall before the person starts or after they leave. | Pick dates within their employment. | | `has_left` | 409 | The person has left. | Nothing to request. | | `archived` | 409 | The leave type is archived. | Use a type that is in use. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [hr_save_people](https://conecto.chat/tools/hr/hr_save_people.md): Adds people or changes them, up to 100 at a time, all or none: names, emails, job, department, location, manager, dates and allowances. $1.00 per person added. - [hr_list_people](https://conecto.chat/tools/hr/hr_list_people.md): People by last name, everyone who hasn't left by default, filtered by status, department, location, manager, type or words. Free up to 1,000,000 reads a month. - [hr_get_person](https://conecto.chat/tools/hr/hr_get_person.md): Everything about one person: details, leave balances for a year, pending and upcoming leave, documents, open tasks and direct reports. Free up to 1,000,000 reads a month. - [hr_delete_person](https://conecto.chat/tools/hr/hr_delete_person.md): Erases a person for good with their leave, tasks and document records; their files stay in the store. Free. - [hr_get_settings](https://conecto.chat/tools/hr/hr_get_settings.md): The working days, hours, leave year, time zone, leave types, public holidays and checklists. Free up to 1,000,000 reads a month. - [hr_save_settings](https://conecto.chat/tools/hr/hr_save_settings.md): Sets the work calendar: working days, hours per day, leave year, time zone, and one location's public holidays for a year. $0.001 a call. - [hr_save_leave_type](https://conecto.chat/tools/hr/hr_save_leave_type.md): Adds or changes a kind of time off: annual days, monthly or yearly accrual, carry-over, paid and tracked. $0.001 a call. - [hr_adjust_leave](https://conecto.chat/tools/hr/hr_adjust_leave.md): Adds days to, or takes days off, one person's balance of a tracked leave type, with the reason. $0.01 a call. - [hr_decide_leave](https://conecto.chat/tools/hr/hr_decide_leave.md): Approves or declines a pending leave request, or cancels one that is pending or approved. $0.01 a call. - [hr_list_leave](https://conecto.chat/tools/hr/hr_list_leave.md): Leave requests, latest start first, by person, status, type or dates. Free up to 1,000,000 reads a month. - [hr_who_is_out](https://conecto.chat/tools/hr/hr_who_is_out.md): Who is off in a period (today by default), with each leave and its days, plus public holidays and people on long leave. Free up to 1,000,000 reads a month. - [hr_save_checklist](https://conecto.chat/tools/hr/hr_save_checklist.md): Adds or changes an onboarding or offboarding checklist: items with an owner and a due day relative to the start or last day. $0.001 a call. - [hr_start_checklist](https://conecto.chat/tools/hr/hr_start_checklist.md): Turns a checklist into tasks for one person, each due relative to their start date or last day. $0.01 a call. - [hr_tasks](https://conecto.chat/tools/hr/hr_tasks.md): Checklist tasks, soonest due first: open, overdue, done or all, for one person, one owner or a date. Free up to 1,000,000 reads a month. - [hr_complete_task](https://conecto.chat/tools/hr/hr_complete_task.md): Marks a checklist task done, or opens it again. $0.01 a call. - [hr_save_document](https://conecto.chat/tools/hr/hr_save_document.md): Keeps a file from the store on a person's record (a contract, an ID, a certificate), or changes or removes it. $0.01 a call. - [hr_report](https://conecto.chat/tools/hr/hr_report.md): Headcount, joiners and leavers, time off taken, or everyone's leave balances. Free up to 1,000,000 reads a month. - [hr_dashboard_link](https://conecto.chat/tools/hr/hr_dashboard_link.md): A one-time link to HR at a glance: who is out, leave to decide, open tasks, and who starts or leaves soon. Free up to 1,000,000 reads a month. - [hr_save_policy](https://conecto.chat/tools/hr/hr_save_policy.md): Keeps a policy people must read and confirm, like an AI use policy; a changed text is a new version. $0.001 a call. - [hr_send_policy](https://conecto.chat/tools/hr/hr_send_policy.md): Emails each person in a policy's scope a one-time link to read and confirm its current version. $0.02 per email sent. - [hr_record_training](https://conecto.chat/tools/hr/hr_record_training.md): Records a training someone completed, like AI literacy, with its date, hours, certificate and expiry. $0.01 a call. - [hr_policy_status](https://conecto.chat/tools/hr/hr_policy_status.md): Who confirmed each policy's current version, and who holds a valid training of each kind. Free up to 1,000,000 reads a month.