---
name: "hr_save_people"
area: "hr"
title: "Add or change people"
price: "$1.00 per person added"
method: "POST"
url: "https://api.conecto.chat/v1/tools/hr_save_people"
mcp_server: "https://api.conecto.chat/mcp/hr"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/hr/hr_save_people"
---

# Add or change people (`hr_save_people`)

Adds people or changes them, up to 100 at a time, all or none: names, emails, job, department, location, manager, dates and allowances.

Add people or change them, up to 100 at a time, all or none: matched by person_id, else by work email (any case); anyone not found is added (first_name needed). Give only what changes: "" clears text, null clears a date. A manager can be anyone on the account, also someone added later in the same call; loops are refused. Status left follows from a past end_date (their last day). Each saved person comes back with their person_id. When you add people partway through a leave year, record what they have already used or carried over with hr_adjust_leave.

Price: $1.00 per person added. A call that fails costs nothing.

## Use it when

Someone joins, changes role, gets a new manager or leaves.

- For a customer or supplier contact, use [crm_save_contact](https://conecto.chat/tools/crm/crm_save_contact.md).

## Say this to your agent

> Add Felix Wagner, our new warehouse operative: he starts November 2 in the warehouse, reports to Lena, probation until the end of April.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `people` | array of objects | yes | 1 to 100 items. |  |  |
| `people[].person_id` | integer | no | Who to change. Left out, work_email finds them; if nobody has it, a new person is added. At least 1. |  |  |
| `people[].first_name` | string | no | Up to 100 characters. |  |  |
| `people[].last_name` | string | no | Up to 100 characters. |  |  |
| `people[].preferred_name` | string | no | What they like to be called. Up to 100 characters. |  |  |
| `people[].work_email` | string | no | One person per address on the account, any case; "" clears it. Up to 254 characters. |  |  |
| `people[].personal_email` | string | no | Up to 254 characters. |  |  |
| `people[].phone` | string | no | Up to 40 characters. |  |  |
| `people[].job_title` | string | no | Up to 120 characters. |  |  |
| `people[].department` | string | no | Up to 120 characters. |  |  |
| `people[].location` | string | no | Where they work, e.g. "Berlin". Holidays set for this location apply to them. Up to 120 characters. |  |  |
| `people[].manager` | integer or string or null | no | Their manager: a person_id or work email on this account (someone added later in the same call is fine); null for none. 1 to 254 characters, at least 1. |  |  |
| `people[].employment_type` | string | no |  | `"full_time"`, `"part_time"`, `"contractor"`, `"intern"` |  |
| `people[].start_date` | string or null | no | YYYY-MM-DD, or null to clear it. Matches ^\\d{4}-\\d{2}-\\d{2}$. |  |  |
| `people[].probation_end` | string or null | no | YYYY-MM-DD, or null to clear it. Matches ^\\d{4}-\\d{2}-\\d{2}$. |  |  |
| `people[].end_date` | string or null | no | Their last day, YYYY-MM-DD (null to clear). Once it has passed their status is left. Matches ^\\d{4}-\\d{2}-\\d{2}$. |  |  |
| `people[].status` | string | no | on_leave for a long absence (parental leave, a sabbatical). "left" follows from end_date. | `"active"`, `"on_leave"` |  |
| `people[].birthday` | string or null | no | YYYY-MM-DD, or null to clear it. Matches ^\\d{4}-\\d{2}-\\d{2}$. |  |  |
| `people[].emergency_contact` | string | no | Who to call, how they are related and their number, as text. Up to 500 characters. |  |  |
| `people[].notes` | string | no | Up to 5,000 characters. |  |  |
| `people[].custom` | object | no | Your own fields as text, e.g. {"T-shirt": "M"}: merged into what is there, null removes one. Up to 20. |  |  |
| `people[].allowances` | object | no | Their own annual days per tracked leave type where they differ from the type's, e.g. {"Vacation": 28}; null goes back to the type's. |  |  |

## Example

Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff.

MCP: call `hr_save_people` on the MCP server `https://api.conecto.chat/mcp/hr` with these arguments:

```json
{
  "people": [
    {
      "first_name": "Felix",
      "last_name": "Wagner",
      "work_email": "felix.wagner@hansenvoss.example",
      "job_title": "Warehouse operative",
      "department": "Warehouse",
      "location": "Hamburg",
      "employment_type": "full_time",
      "manager": "lena.brandt@hansenvoss.example",
      "start_date": "2026-11-02",
      "probation_end": "2027-04-30"
    }
  ]
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/hr_save_people \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"people": [{"first_name": "Felix", "last_name": "Wagner", "work_email": "felix.wagner@hansenvoss.example", "job_title": "Warehouse operative", "department": "Warehouse", "location": "Hamburg", "employment_type": "full_time", "manager": "lena.brandt@hansenvoss.example", "start_date": "2026-11-02", "probation_end": "2027-04-30"}]}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "hr_save_people",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$1.00",
  "balance_usd": "$19.75",
  "result": {
    "people": [
      {
        "person_id": 4105,
        "name": "Felix Wagner",
        "first_name": "Felix",
        "last_name": "Wagner",
        "preferred_name": null,
        "work_email": "felix.wagner@hansenvoss.example",
        "job_title": "Warehouse operative",
        "department": "Warehouse",
        "location": "Hamburg",
        "manager": {
          "person_id": 4101,
          "name": "Lena Brandt"
        },
        "employment_type": "full_time",
        "start_date": "2026-11-02",
        "probation_end": "2027-04-30",
        "end_date": null,
        "status": "active",
        "created": true
      }
    ]
  }
}
```

`result`: people: each saved person with their person_id and details.

## 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. |
| `invalid_input` | 400 | An email or date is not valid, or a new person has no first_name. | Fix what the message names for the person it labels. |
| `email_taken` | 409 | Another person has that work email. | Change that person by person_id instead. |
| `manager_cycle` | 409 | The manager would end up reporting to the person, or to themselves. | Pick another manager. |
| `not_tracked` | 409 | An allowance names a leave type that is not tracked. | Set allowances only for tracked types. |

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_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_request_leave](https://conecto.chat/tools/hr/hr_request_leave.md): Asks for time off for someone, counting working days less holidays; it waits for a decision unless approved at once. $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.