---
title: "Update multiple people"
method: POST
path: "/api/people/bulk-update"
tags: ["people"]
---

# Update multiple people

`POST /api/people/bulk-update`

## Request

- Base URL: `https://api.gumnut.ai`
- URL: `https://api.gumnut.ai/api/people/bulk-update`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Updates name, birth date, visibility, favorite status, or thumbnail on multiple people in one transactional call. Each item carries the target person id and the per-person change — different fields can be changed on different people in the same request. Atomic: a duplicate id, an unknown or inaccessible id, or any per-item failure rejects the whole batch and writes nothing.

Items apply in request order, and each rename is checked against the names left by earlier items: swapping two people's names, or giving two people the same name, returns 409. Renaming to another record's name in the same library, including hidden people, also returns 409. Names ignore case and surrounding whitespace; retrying the same collision does not resolve it.

`update_person` edits a single person.

## Request body

- BulkUpdatePeopleRequest: Bulk-update request body — heterogeneous per-person changes in one call.
  - `updates` BulkUpdatePersonItem[], required: List of per-person updates. Each item carries the target person id and the change to apply to it; different fields can be changed on different people in the same request. Up to 200 items per request.
    - `id` string, required: Person ID (with the `person_` prefix) to apply this change to.
    - `change` PersonUpdate, required
      - `name` string, nullable: New display name; must not be blank. Surrounding whitespace is trimmed. Omit to leave unchanged; pass `null` to clear the name.
      - `birth_date` string, date, nullable: New birth date (ISO 8601 date). Omit to leave unchanged.
      - `is_hidden` boolean: Hide or unhide this person. Omit to leave unchanged.
      - `is_favorite` boolean: Mark or unmark this person as a favorite. Omit to leave unchanged.
      - `thumbnail_face_id` string, nullable: New thumbnail face ID for this person. Omit to leave unchanged. Enumerate a person's faces with `list_faces` and `person_id`.

## Response `200`

Successful Response

- BulkUpdatePeopleResponse: Empty acknowledgment returned by `bulk_update_people`.

## Other responses

- `401`: Missing, invalid, or expired credentials.
- `403`: The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404`: Not found
- `409`: Name is already in use Clerk sign-in could not be associated with the existing account. Resolve the identity conflict before retrying sign-in; repeated requests with unchanged verification and identity state will not resolve it.
- `422`: Validation Error
- `429`: Rate limit exceeded, or too many of your requests are already in progress. Retry after the interval in the `Retry-After` header.
- `503`: Authentication provider temporarily unavailable. Retry sign-in later.

## Changes

- **2026-10-16** `7c2860d9eb88`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gumnut-ai/apis/gumnut-api/changes/api/people/bulk-update/post.md)

---

[API](https://skmtc.dev/gumnut-ai/apis/gumnut-api.md) - [All operations](https://skmtc.dev/gumnut-ai/apis/gumnut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gumnut-ai/apis/gumnut-api/revisions/f3baab78e588?raw)