conecto. Get started
HR

Request time off

hr_request_leave · Changes data · Markdown

Asks for time off for someone, counting working days less holidays; it waits for a decision unless approved at once.

$0.01 a call

From your agent’s balance. A call that fails costs nothing.

An example

Tom wants December 21 to 31 off for Christmas, with the 31st as a half day.

Your agent callshr_request_leave$0.01 a call

The example business is Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. The reply is the one the tool really gives.

With these arguments
{
  "person": "tom.okafor@hansenvoss.example",
  "leave_type": "Vacation",
  "start": "2026-12-21",
  "end": "2026-12-31",
  "half_end": true,
  "note": "Christmas with family"
}
What comes back
{
  "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"
    }
  ]
}

Use it when

Someone asks for a holiday, a sick day or a day off.

What it does

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.

What comes back

request: its request_id, person, type, dates, half days, days counted and status; balances: the person's balance of that type after it. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
personRequiredinteger or stringThe person_id, or their work email. 1 to 254 characters, at least 1.
leave_typeRequiredstringA leave type by name, e.g. "Vacation". 1 to 60 characters.
startRequiredstringYYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
endstringThe last day off, YYYY-MM-DD. Default: start. Matches ^\d{4}-\d{2}-\d{2}$.
half_startbooleanThe first day is a half day. Default: false.
half_endbooleanThe last day is a half day. Default: false.
notestringUp to 1,000 characters.
approvebooleanDefault: false.
allow_negativebooleanDefault: false.

The call

Over MCP, call hr_request_leave on https://api.conecto.chat/mcp/hr. Over REST:

Terminal
curl -X POST 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"}'

When it refuses

A refused call costs nothing and says what to do next.

CodeWhenWhat to do
not_found404No person of the business has that person_id or work email.Find them with hr_list_people.
not_found404No leave type has that name.Call hr_get_settings, or add it with hr_save_leave_type.
invalid_input400A date is not a date like 2026-10-01, or from is after to.Fix the date.
not_enough_days409The balance (after pending requests) cannot take the days.Ask for fewer days, or pass allow_negative: true if the owner agrees.
overlaps409The person already has leave in those days.Change or cancel the other request first.
no_working_days400The dates hold no working days.Check the dates.
outside_employment409The dates fall before the person starts or after they leave.Pick dates within their employment.
has_left409The person has left.Nothing to request.
archived409The leave type is archived.Use a type that is in use.

More HR tools

All 23 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md