---
title: "Divide candidate faces into groups based on face similarity."
method: POST
path: "/group"
---

# Divide candidate faces into groups based on face similarity.

`POST /group`

>
*
  * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result.
  * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts.
  * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try "Verify Face To Face" when you only have 2 candidate faces.
  * The 'recognitionModel' associated with the query faces' faceIds should be the same.

## Request body

- object
  - `faceIds` AzureCoreUuid[], required — Array of candidate faceIds created by "Detect". The maximum is 1000 faces.

## Response `200`

A successful call returns one or more groups of similar faces (rank by group size) and a messyGroup.

- GroupingResult — Response body for group face operation.
  - `groups` array[], required — A partition of the original faces based on face similarity. Groups are ranked by number of faces.
    - AzureCoreUuid[]
  - `messyGroup` AzureCoreUuid[], required — Face ids array of faces that cannot find any similar faces from original faces.

## Other responses

- `default` — An unexpected error response.

---

[API](https://skmtc.net/azure/apis/ai-face.md) · [All operations](https://skmtc.net/azure/apis/ai-face/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/azure/ai-face/versions/e9a68c525be6/schema)