> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idmetagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload faces for enrollment

> Queue up to 50 face images per request for asynchronous biometric blacklist enrollment.

Queues up to 50 images per request for background enrollment. Only images that successfully enroll are stored; failed images are discarded.

The face name is derived from each image's filename (without extension).

## Error responses

| Code  | When                                                                                               |
| ----- | -------------------------------------------------------------------------------------------------- |
| `404` | Blacklist not found or not owned by your company                                                   |
| `422` | Blacklist inactive, validation failure (too many/invalid files), or company storage not configured |


## OpenAPI

````yaml api-reference/internal-blacklist/biometric-blacklist.openapi.json POST /v3/biometric-blacklists/{id}/faces
openapi: 3.0.3
info:
  title: Internal Blacklist — Biometric Blacklist API
  description: >-
    Enroll face images into biometric blacklists (watchlists). Enrollment is
    asynchronous.
  version: 1.0.0
servers:
  - url: https://{environment-subdomain}.idmetagroup.com
    description: Your environment (replace `{environment-subdomain}`)
    variables:
      environment-subdomain:
        default: integrate
        description: IDmeta environment subdomain
security:
  - bearerAuth: []
tags:
  - name: Internal Blacklist
    description: Biometric blacklist enrollment endpoints
paths:
  /v3/biometric-blacklists/{id}/faces:
    post:
      tags:
        - Internal Blacklist
      summary: Upload faces for enrollment
      description: >-
        Queue up to 50 images per request for background enrollment. Only images
        that successfully enroll are stored; failed images are discarded. The
        face name is derived from each image filename (without extension).
      operationId: uploadBiometricBlacklistFaces
      parameters:
        - name: id
          in: path
          required: true
          description: The blacklist UUID (from the list endpoint).
          schema:
            type: string
            format: uuid
            example: b1f2c3d4-0000-0000-0000-000000000000
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            example: Bearer {your_api_token}
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - images[]
              properties:
                images[]:
                  type: array
                  description: >-
                    1–50 image files. Accepted formats: jpg, jpeg, png. Max 10
                    MB each.
                  items:
                    type: string
                    format: binary
                  minItems: 1
                  maxItems: 50
      responses:
        '202':
          description: Face upload accepted and queued for enrollment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFacesResponse'
              example:
                success: true
                message: Face upload accepted and queued for enrollment
                data:
                  upload_id: 1024
                  blacklist_id: b1f2c3d4-0000-0000-0000-000000000000
                  number_of_images: 50
                  status: 1
                  status_label: Processing
                  createdAt: '2026-07-27T09:15:00.000000Z'
        '404':
          description: Blacklist not found or not owned by your company
        '422':
          description: >-
            Blacklist inactive, validation failure (too many/invalid files), or
            company storage not configured
components:
  schemas:
    UploadFacesResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          $ref: '#/components/schemas/UploadFacesData'
    UploadFacesData:
      type: object
      properties:
        upload_id:
          type: integer
          description: Use this ID to poll upload status.
        blacklist_id:
          type: string
          format: uuid
        number_of_images:
          type: integer
        status:
          type: integer
          description: Initial upload status. `1` = Processing.
        status_label:
          type: string
          description: Human-readable status label.
          example: Processing
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the upload was created.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use `Bearer {your_api_token}` in the Authorization header, plus HMAC
        signature headers. Same authentication as other v3 endpoints.

````