> ## 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.

# Poll duplicate detection upload status

> Check the status of an asynchronous duplicate-detection face enrollment upload until it reaches a terminal state.

Poll this endpoint with the `uploadId` returned from [Upload faces](/api-reference/duplicate-detection/upload-faces) until `status` is a terminal value (`2`, `3`, or `4`).

Returns `404` if the upload does not exist or is not owned by your company.

## Status values

| Value | Meaning                                          | Terminal? |
| ----- | ------------------------------------------------ | --------- |
| `0`   | Pending — queued, not yet started                | No        |
| `1`   | Processing — enrollment in progress              | No        |
| `2`   | Completed — all images enrolled                  | Yes       |
| `3`   | Failed — no images enrolled                      | Yes       |
| `4`   | Partially completed — some enrolled, some failed | Yes       |

## Example response

### 200 OK — partially completed

```json theme={null}
{
  "success": true,
  "data": {
    "uploadId": "3aa8f48e-8a62-4439-82b9-bc3ae4b176a2",
    "trustFlowId": 409,
    "status": 4,
    "statusLabel": "Partially completed",
    "numberOfImages": 12,
    "numberOfSucceededImages": 10,
    "numberOfFailedImages": 2,
    "failedImages": [
      {
        "index": 3,
        "filename": "face4.jpg",
        "reason": "No face detected in the image."
      },
      {
        "index": 7,
        "filename": "face8.jpg",
        "reason": "Face is too small. Please move face closer to the camera."
      }
    ],
    "createdAt": "2026-07-29 07:08:15+0000",
    "updatedAt": "2026-07-29 07:09:02+0000"
  }
}
```

| Field                     | Description                                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `numberOfSucceededImages` | Images successfully enrolled into the duplicate-detection watchlist. Each gets a Verified Trust Validation. |
| `numberOfFailedImages`    | Images that failed enrollment. No Trust Validation or stored image is kept for these.                       |
| `failedImages`            | Per-image failure details with a human-readable `reason` from the biometric engine.                         |

## Example cURL

```bash theme={null}
curl -X GET "https://api.idmetagroup.com/api/v3/duplicate-detection/uploads/3aa8f48e-8a62-4439-82b9-bc3ae4b176a2" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
```

## Error responses

| Code  | When                                          |
| ----- | --------------------------------------------- |
| `200` | Upload status retrieved                       |
| `404` | Upload not found or not owned by your company |


## OpenAPI

````yaml api-reference/duplicate-detection/duplicate-detection.openapi.json GET /api/v3/duplicate-detection/uploads/{uploadId}
openapi: 3.0.3
info:
  title: Duplicate Detection — Face Enrollment API
  description: >-
    Mass-enroll face images into the reserved biometric duplicate-detection
    watchlist. 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: Duplicate Detection
    description: Mass-enroll faces into the duplicate-detection watchlist
paths:
  /api/v3/duplicate-detection/uploads/{uploadId}:
    get:
      tags:
        - Duplicate Detection
      summary: Poll upload status
      description: >-
        Poll with the uploadId returned from the upload endpoint until status is
        a terminal value (2, 3, or 4). Returns per-image failure reasons when
        enrollment fails.
      operationId: getDuplicateDetectionUploadStatus
      parameters:
        - name: uploadId
          in: path
          required: true
          description: >-
            The upload UUID returned from POST
            /api/v3/duplicate-detection/faces.
          schema:
            type: string
            format: uuid
            example: 3aa8f48e-8a62-4439-82b9-bc3ae4b176a2
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            example: Bearer {your_api_token}
      responses:
        '200':
          description: Upload status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadStatusResponse'
              example:
                success: true
                data:
                  uploadId: 3aa8f48e-8a62-4439-82b9-bc3ae4b176a2
                  trustFlowId: 409
                  status: 4
                  statusLabel: Partially completed
                  numberOfImages: 12
                  numberOfSucceededImages: 10
                  numberOfFailedImages: 2
                  failedImages:
                    - index: 3
                      filename: face4.jpg
                      reason: No face detected in the image.
                    - index: 7
                      filename: face8.jpg
                      reason: >-
                        Face is too small. Please move face closer to the
                        camera.
                  createdAt: 2026-07-29 07:08:15+0000
                  updatedAt: 2026-07-29 07:09:02+0000
        '404':
          description: Upload not found or not owned by your company
components:
  schemas:
    UploadStatusResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/UploadStatusData'
    UploadStatusData:
      type: object
      properties:
        uploadId:
          type: string
          format: uuid
        trustFlowId:
          type: integer
          description: >-
            The internal system Trust Flow all resulting Trust Validations
            belong to.
        status:
          type: integer
          description: 'Upload status. Terminal values: `2`, `3`, `4`.'
        statusLabel:
          type: string
          description: Human-readable status label.
          example: Completed
        numberOfImages:
          type: integer
        numberOfSucceededImages:
          type: integer
        numberOfFailedImages:
          type: integer
        failedImages:
          type: array
          items:
            $ref: '#/components/schemas/FailedImage'
          description: >-
            Per-image failure details. Present when one or more images failed
            enrollment.
        createdAt:
          type: string
        updatedAt:
          type: string
    FailedImage:
      type: object
      properties:
        index:
          type: integer
          description: Zero-based index of the image in the upload batch.
        filename:
          type: string
          description: Original filename of the failed image.
        reason:
          type: string
          description: Human-readable failure reason from the biometric engine.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use `Bearer {your_api_token}` in the Authorization header, or HMAC
        signature headers (`X-HMAC-SIGNATURE`, `X-TIMESTAMP`, `X-USER-ID`). Same
        authentication as other v3 endpoints.

````