> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/backend1n/technical_documentation/api_reference/faces/faces-1.md).

# /faces

Adds a new specimen (face) to the database. First, the referenced image is looked up in the database and its biometric template is extracted (if the image does not contain a face, it returns 400). The collectionId must correspond to an existing collection, and the mediaId must belong to that same collection. A mediaId can only back one specimen at a time; the image becomes associated with the specimen and is deleted along with it.

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT signed with HS256 (shared secret `auth_jwt_secret`) and with a non-expired `exp` claim; if it includes `nbf`, it must be currently valid. Only applied if `auth_enabled` is true and `auth_accept_authorization_header` is true. The `Bearer` scheme is case-insensitive.\n"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same JWT sent in an API key header. The default name is `x-api-key` and it can be changed with `auth_api_key_header_name`; only applied if `auth_accept_api_key_header` is true. If both headers are sent, `Authorization` takes precedence.\n"}},"schemas":{"FaceBody":{"type":"object","description":"Body for the POST face request","properties":{"mediaId":{"$ref":"#/components/schemas/MediaId"},"collectionId":{"$ref":"#/components/schemas/CollectionId"},"description":{"$ref":"#/components/schemas/FaceDescription"}},"required":["mediaId","collectionId","description"]},"MediaId":{"type":"string","description":"An identifier of an image in the database. Each image is associated with a single specimen (face): the uploaded image becomes associated when the face is created with `POST /faces` and it is deleted together with it (`DELETE /faces/{Id}`) or together with its collection (`DELETE /collections/{collectionId}`).\n"},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"},"FaceDescription":{"type":"string","minLength":1,"description":"Description of the specimen (face) stored in the database."},"FaceResponse":{"type":"object","description":"Data fields of the specimen in the database","properties":{"createAt":{"$ref":"#/components/schemas/CreateAt"},"description":{"$ref":"#/components/schemas/FaceDescription"},"facialTemplateRaw":{"$ref":"#/components/schemas/FacialTemplateRaw"},"id":{"$ref":"#/components/schemas/FaceId"},"mediaId":{"$ref":"#/components/schemas/MediaId"},"collectionId":{"$ref":"#/components/schemas/CollectionId"},"updateAt":{"$ref":"#/components/schemas/UpdateAt"}}},"CreateAt":{"type":"string","description":"Date/time value (UTC, 1-second resolution) in \"%Y-%m-%dT%H:%M:%SZ\" format at which a specimen (face) was created."},"FacialTemplateRaw":{"type":"string","description":"An extended token that contains biometric templates and metadata. Storing it in databases is recommended because it remains valid across engine versions (it can be updated automatically if the extraction technology changes; see `updatedTemplateRaw`). Like the rest of the tokens, its value changes on every extraction (it carries a timestamp): two extractions of the same image do not give the same text, but they identify the same person. It is encoded in RFC4648 base64.\n"},"FaceId":{"type":"string","description":"An identifier of a specimen (face) in the database."},"UpdateAt":{"type":"string","description":"Date/time value (UTC, 1-second resolution) in \"%Y-%m-%dT%H:%M:%SZ\" format at which a specimen (face) was updated."},"BadRequestResult":{"type":"object","description":"Result when incorrect parameters arrive in the request.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Specific description of the reason for the error. It is the only field that indicates the real cause."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."},"UnauthorizedResult":{"type":"object","description":"JWT authentication is enabled and the request does not pass it. It is accompanied by the header `WWW-Authenticate: Bearer`. Values of `message`: `Missing authentication token` (no token or unsupported scheme), `JWT token validation failed` (invalid signature, algorithm or format), `JWT token is expired`, `JWT token does not include exp claim` and `JWT token is not yet valid` (future `nbf`).\n","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"ExceptionResult":{"type":"object","description":"An error occurred while calling the backend services.","properties":{"status":{"type":"number"},"error":{"type":"string"},"exception":{"type":"string","description":"Specific description of the reason for the exception (internal service text; it is not part of the contract)."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}}},"responses":{"Unauthorized":{"description":"JWT authentication is enabled and the token is missing or invalid.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResult"}}}},"PayloadTooLarge":{"description":"The request body exceeds `client_max_body_size`. It is returned with no body and the connection is closed."}}},"paths":{"/faces":{"post":{"description":"Adds a new specimen (face) to the database. First, the referenced image is looked up in the database and its biometric template is extracted (if the image does not contain a face, it returns 400). The collectionId must correspond to an existing collection, and the mediaId must belong to that same collection. A mediaId can only back one specimen at a time; the image becomes associated with the specimen and is deleted along with it.","tags":["Faces"],"requestBody":{"description":"Data needed to add a new specimen (face) to the database.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaceBody"}}}},"responses":{"200":{"description":"All the data fields of the specimen (face) stored in the database.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaceResponse"}}}},"400":{"description":"Incorrect parameters arrive in the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"description":"An error occurred while calling the backend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExceptionResult"}}}}}}}}}
```