---
title: "POST /group"
method: POST
path: "/group"
---

# POST /group

`POST /group`

Divide candidate faces into groups based on face similarity.<br />
* 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 [Face - Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface) when you only have 2 candidate faces.
* The 'recognitionModel' associated with the query faces' faceIds should be the same.

## Request body

- GroupRequest — Request body for group request.
  - `faceIds` string[], required — Array of candidate faceId created by Face - 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.

- GroupResult — An array of face groups based on face similarity.
  - `groups` array[], required — A partition of the original faces based on face similarity. Groups are ranked by number of faces
    - string[]
  - `messyGroup` string[] — Face ids array of faces that cannot find any similar faces from original faces.

## Other responses

- `default` — Error response.

---

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