Skip to main content
POST
Merge people

Authorizations

Authorization
string
header
required

Gumnut API key (apikey_...) sent as a Bearer token in the Authorization header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it.

Path Parameters

person_id
string
required

Person ID (with person_ prefix) of the primary person that absorbs the source people. Person IDs are carried by the id field of person responses (e.g. list_people, get_person) and by person references on faces and assets.

Body

application/json
source_person_ids
string[]
required

IDs of the people to merge into the primary person. These people will be deleted after their faces are moved.

Required array length: 1 - 50 elements

Response

Successful Response

Represents a person identified through face clustering and recognition.

id
string
required

Unique person identifier with 'person_' prefix

is_hidden
boolean
required

Whether this person should be hidden from the UI

is_favorite
boolean
required

Whether this person is marked as a favorite

created_at
string<date-time>
required

When this person record was created

updated_at
string<date-time>
required

When this person record was last updated

name
string | null

Optional name assigned to this person

birth_date
string<date> | null

Optional birth date of this person

asset_count
integer | null

Number of unique photos this person appears in, or null if not computed

thumbnail_face_id
string | null

ID of the face resource used as this person's thumbnail

asset_urls
Asset Urls · object | null

Asset variants from this person's thumbnail face. May be null when embedded in an AssetResponse; use /api/people endpoints for full person data.

cluster_metrics
ClusterMetricsResponse · object | null

Cohesion metrics for this person's face cluster. Populated only when include=cluster_metrics is requested on the people endpoint, and only for persons with a populated centroid (newly-created empty Persons will have null). See ClusterMetricsResponse for the shape.