---
title: "POST /largefacelists/{largeFaceListId}/persistedfaces"
method: POST
path: "/largefacelists/{largeFaceListId}/persistedfaces"
---

# POST /largefacelists/{largeFaceListId}/persistedfaces

`POST /largefacelists/{largeFaceListId}/persistedfaces`

Add a face to a specified large face list, up to 1,000,000 faces.
<br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](https://docs.microsoft.com/rest/api/faceapi/largefacelist/deleteface) or [LargeFaceList - Delete](https://docs.microsoft.com/rest/api/faceapi/largefacelist/delete) is called.
<br /> Note persistedFaceId is different from faceId generated by [Face - Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).
* Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
* JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
* "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl), there’s no guarantee to detect and add the face successfully.
* Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.
* Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel.
* The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size.
* Different 'detectionModel' values can be provided. To use and compare different detection models, please refer to [How to specify a detection model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)

Quota:
* Free-tier subscription quota: 1,000 faces per large face list.
* S0-tier subscription quota: 1,000,000 faces per large face list.

## Path parameters

- `largeFaceListId` string, required

## Query parameters

- `userData` string
- `targetFace` integer[]
- `detectionModel` 'detection_01' | 'detection_02' | 'detection_03'

## Parameters

- `../../../Common/Parameters.json#/components/parameters/ImageUrl` — unresolved $ref

## Response `200`

A successful call returns a new persistedFaceId.

- PersistedFace — PersonFace object.
  - `persistedFaceId` string, uuid, required — The persistedFaceId of the target face, which is persisted and will not expire. Different from faceId created by Face - Detect and will expire in at the time specified by faceIdTimeToLive after the detection call.
  - `userData` string — User-provided data attached to the face. The size limit is 1KB.

## 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/revisions/8a19b734b92a/schema)