> ## 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. # Biometrics Verification > Run a face liveness check, and optionally screen the same selfie for duplicates and against your blacklists ## OpenAPI ````yaml stateless-verification-api/compliance/biometrics-verification.openapi.json POST /api/v3/verifications/biometrics-verification-passthrough openapi: 3.0.3 info: title: Biometrics Verification Passthrough API 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: [] paths: /api/v3/verifications/biometrics-verification-passthrough: post: tags: - Compliance Verification summary: Biometrics Verification description: >- Run a face liveness check, and optionally screen the same selfie for duplicates and against your blacklists. `livenessThreshold` and the returned `livenessScore` are both **percentages from 0 to 100** on the same scale, so they compare directly. `livenessThreshold` defaults to `70`. It can only make the check stricter — a face the engine already rejected cannot pass by lowering `livenessThreshold`. Both `performDuplicateDetection` and `performBlacklistDetection` default to `false`. `data.duplicateDetection` and `data.blacklistDetection` are returned only when their corresponding flag was set to `true` on the request, and independently of each other. A request that sets neither returns a `data` object containing just `livenessPass` and `livenessScore`. Read these keys with a presence check — they are not always there. `blacklistIds` holds **UUID strings**, not integers. Required when `performBlacklistDetection` is `true`. Screening runs on any image the engine could read — including one that failed liveness — because a face below the threshold is still worth checking against watchlists. Screening **never** changes `verificationStatus`; that field reports the liveness verdict only. Whether a duplicate or blacklist hit should block the subject is your policy call. `performDuplicateDetection` enrols the selfie into your duplicate watchlist; `enrolled` reports whether that succeeded. No image is stored by the passthrough API itself. Duplicate matches carry the `transactionId` of the earlier passthrough call the matched face was enrolled under. Blacklist matches carry `blacklistFaceUploadId` instead. If screening was requested but could not complete, that object reports `"hasMatches": null` with an `error` string. The liveness result is unaffected and still returned. `verificationStatusCode`: `3` = Verified, `2` = Review Needed, `1` = Rejected, `6` = Failed. HTTP `400`, `404`, `500`, and `502` release the reserved credit. Only a completed liveness check — passed or rejected — is billed. operationId: biometricsVerificationPassthrough parameters: - name: Authorization in: header required: true schema: type: string example: Bearer {your_api_token} - name: Accept in: header required: false schema: type: string default: application/json - name: Content-Type in: header required: false schema: type: string default: application/json requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BiometricsVerificationRequest' examples: livenessOnly: summary: Verify liveness only description: >- Uses the default liveness threshold of `70`. Duplicate and blacklist screening are left off. value: image: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD... livenessThreshold: 70 performDuplicateDetection: false metadata: customerReference: CUST-10294 strictLiveness: summary: Verify liveness at a stricter threshold value: image: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD... livenessThreshold: 90 metadata: customerReference: CUST-10294 withDetection: summary: Verify liveness with duplicate and blacklist screening value: image: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD... livenessThreshold: 70 performDuplicateDetection: true performBlacklistDetection: true blacklistIds: - 6f1c2a90-8d3b-4f2e-9c11-7ab5d0e34f89 metadata: customerReference: CUST-10294 multipart/form-data: schema: type: object required: - image properties: image: type: string format: binary description: Selfie image file. Alternative to a Base64 data URI in JSON. livenessThreshold: type: number minimum: 0 maximum: 100 default: 70 performDuplicateDetection: type: boolean default: false performBlacklistDetection: type: boolean default: false description: >- Only available if your account is subscribed to biometric blacklist screening. Create blacklists in the IDmeta Platform first to obtain `blacklistIds`. blacklistIds: type: array description: >- UUID strings of active biometric blacklists from the IDmeta Platform. Required when `performBlacklistDetection` is `true`. items: type: string format: uuid metadata: type: object additionalProperties: true responses: '200': description: >- Liveness completed. Passed, rejected, and review-needed outcomes all use HTTP 200 when the engine returns a liveness verdict. Duplicate and blacklist hits are reported in `data` but do not change `verificationStatus`. content: application/json: schema: $ref: '#/components/schemas/BiometricsVerificationSuccessResponse' examples: noDetection: summary: Liveness passed, screening not requested value: success: true message: Biometrics verification processed successfully data: livenessPass: true livenessScore: 98.12 verificationStatus: VERIFIED verificationStatusCode: 3 transactionId: 9d4f2b18-6c31-4e75-8a90-2f1b7c3e5d60 verificationType: biometrics_verification metadata: customerReference: CUST-10294 createdAt: 2026-09-14 04:12:37+0000 duplicateOnly: summary: Liveness passed, duplicate screening only description: >- Request set only `performDuplicateDetection: true`. `duplicateDetection` is present; `blacklistDetection` is absent entirely — not empty, not null. value: success: true message: Biometrics verification processed successfully data: livenessPass: true livenessScore: 98.12 duplicateDetection: performed: true hasMatches: false enrolled: true matches: [] verificationStatus: VERIFIED verificationStatusCode: 3 transactionId: 9d4f2b18-6c31-4e75-8a90-2f1b7c3e5d60 verificationType: biometrics_verification metadata: customerReference: CUST-10294 createdAt: 2026-09-14 04:12:37+0000 duplicateFound: summary: Liveness passed, duplicate detected description: >- `verificationStatus` remains `VERIFIED` because liveness passed. The duplicate hit is for you to act on; it is not folded into the verdict. value: success: true message: Biometrics verification processed successfully data: livenessPass: true livenessScore: 98.12 duplicateDetection: performed: true hasMatches: true enrolled: true matches: - record_id: 3f8c1d22-5b47-4a90-b6e2-1c7d9a04e5b3 name: Jane Citizen similarity_score: 96.4 transactionId: c0a8012e-5f44-4d2a-9b71-0e8f3a6c1d54 blacklistDetection: performed: true hasMatches: false blacklists: - blacklistId: 6f1c2a90-8d3b-4f2e-9c11-7ab5d0e34f89 blacklistName: Internal Fraud Watchlist hasMatches: false matches: [] verificationStatus: VERIFIED verificationStatusCode: 3 transactionId: 9d4f2b18-6c31-4e75-8a90-2f1b7c3e5d60 verificationType: biometrics_verification metadata: customerReference: CUST-10294 createdAt: 2026-09-14 04:12:37+0000 rejected: summary: Liveness rejected description: >- A `livenessScore` of `21.40` is below the default `livenessThreshold` of `70`. Screening results, if requested, are still present in `data`. value: success: true message: Biometrics verification processed successfully data: livenessPass: false livenessScore: 21.4 duplicateDetection: performed: true hasMatches: false enrolled: true matches: [] blacklistDetection: performed: true hasMatches: false blacklists: - blacklistId: 6f1c2a90-8d3b-4f2e-9c11-7ab5d0e34f89 blacklistName: Internal Fraud Watchlist hasMatches: false matches: [] verificationStatus: REJECTED verificationStatusCode: 1 transactionId: 9d4f2b18-6c31-4e75-8a90-2f1b7c3e5d60 verificationType: biometrics_verification metadata: customerReference: CUST-10294 createdAt: 2026-09-14 04:12:37+0000 '400': description: >- Validation failed or the image could not be read. No completed liveness check is recorded and reserved credit is released. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/BiometricsVerificationValidationErrorResponse - $ref: '#/components/schemas/BiometricsVerificationErrorResponse' examples: invalidRequest: summary: Request failed validation value: success: false code: VALIDATION_FAILED message: >- The request could not be validated. Please check the submitted fields. errors: image: - The image field is required. livenessThreshold: - The liveness threshold must be between 0 and 100. transactionId: null verificationType: biometrics_verification createdAt: 2026-09-14 04:12:37+0000 unreadableImage: summary: The image could not be read description: >- Other `message` values for this case: "Multiple faces detected in the image. Please ensure only one face is visible.", "Face is partially hidden or obscured. Please ensure full face is clearly visible.", "Face is cropped. Please ensure full face is in frame.", "Face is too small. Please move face closer to the camera.", "Face angle is too large. Please ensure face is clearly visible.", "Face is too close to the border. Please ensure face is clearly visible." value: success: false message: >- No face detected in the image. Please ensure face is clearly visible. data: {} verificationStatus: FAILED verificationStatusCode: 6 transactionId: 9d4f2b18-6c31-4e75-8a90-2f1b7c3e5d60 verificationType: biometrics_verification metadata: null createdAt: 2026-09-14 04:12:37+0000 '404': description: >- Returned when `performBlacklistDetection` is `true` and `blacklistIds` is absent, empty, or contains only ids that are unknown, inactive, or owned by another company. Nothing is screened, no transaction is recorded, and no credit is consumed. Failure responses carrying a `code` omit `data` entirely. content: application/json: schema: $ref: >- #/components/schemas/BiometricsVerificationBlacklistNotFoundResponse examples: blacklistNotFound: summary: Blacklist screening requested with no resolvable blacklist value: success: false code: BLACKLIST_NOT_FOUND message: >- No active blacklist was found for the supplied blacklistIds. verificationStatus: FAILED verificationStatusCode: 6 transactionId: 9d4f2b18-6c31-4e75-8a90-2f1b7c3e5d60 verificationType: biometrics_verification metadata: customerReference: CUST-10294 createdAt: 2026-09-14 04:12:37+0000 '500': description: Unhandled failure. Reserved credit is released. content: application/json: schema: $ref: '#/components/schemas/BiometricsVerificationErrorResponse' examples: internalError: summary: Unhandled failure value: success: false message: Internal Server Error data: {} verificationStatus: FAILED verificationStatusCode: 6 transactionId: 9d4f2b18-6c31-4e75-8a90-2f1b7c3e5d60 verificationType: biometrics_verification metadata: null createdAt: 2026-09-14 04:12:37+0000 '502': description: >- The biometrics engine could not be reached. Reserved credit is released. content: application/json: schema: $ref: '#/components/schemas/BiometricsVerificationErrorResponse' examples: sourceUnavailable: summary: The biometrics engine could not be reached value: success: false message: Failed to process biometrics verification data: {} verificationStatus: FAILED verificationStatusCode: 6 transactionId: 9d4f2b18-6c31-4e75-8a90-2f1b7c3e5d60 verificationType: biometrics_verification metadata: null createdAt: 2026-09-14 04:12:37+0000 components: schemas: BiometricsVerificationRequest: type: object required: - image properties: image: type: string description: >- Base64 data URI (for example `data:image/jpeg;base64,...`), or a multipart file upload when posting `multipart/form-data`. livenessThreshold: type: number minimum: 0 maximum: 100 default: 70 description: >- Minimum liveness confidence as a percentage (0–100), on the same scale as `livenessScore`. `livenessPass` is true and `verificationStatus` is `VERIFIED` when the score is greater than or equal to this value. May only tighten the result, never loosen it. performDuplicateDetection: type: boolean default: false description: >- When `true`, screens the selfie against your company's duplicate watchlist and enrols it for future matches. performBlacklistDetection: type: boolean default: false description: >- When `true`, screens the selfie against the blacklists named in `blacklistIds`. This feature is only available if your account is subscribed to biometric blacklist screening. You must create and add blacklists in the IDmeta Platform first to obtain the `blacklistIds` to pass here. blacklistIds: type: array description: >- UUID strings of your company's active biometric blacklists, created in the IDmeta Platform. Required when `performBlacklistDetection` is `true`. items: type: string format: uuid metadata: type: object additionalProperties: true description: Free-form correlation data, echoed back on the response. BiometricsVerificationSuccessResponse: type: object required: - success - message - data - verificationStatus - verificationStatusCode - transactionId - verificationType - createdAt properties: success: type: boolean example: true message: type: string description: >- `Biometrics verification successful` when liveness passed; `Biometrics verification rejected` when liveness failed. data: $ref: '#/components/schemas/BiometricsVerificationData' verificationStatus: type: string enum: - VERIFIED - REVIEW_NEEDED - REJECTED description: >- Liveness verdict only. Duplicate and blacklist hits do not change this field. verificationStatusCode: type: integer enum: - 3 - 2 - 1 description: '`3` = Verified, `2` = Review Needed, `1` = Rejected.' transactionId: type: string format: uuid verificationType: type: string example: biometrics_verification metadata: type: object additionalProperties: true nullable: true createdAt: type: string example: 2026-09-14 04:12:37+0000 BiometricsVerificationValidationErrorResponse: type: object required: - success - code - message - errors - transactionId - verificationType - createdAt properties: success: type: boolean example: false code: type: string enum: - VALIDATION_FAILED message: type: string errors: type: object additionalProperties: type: array items: type: string transactionId: type: string format: uuid nullable: true verificationType: type: string example: biometrics_verification createdAt: type: string BiometricsVerificationErrorResponse: type: object required: - success - message - verificationStatus - verificationStatusCode - transactionId - verificationType - createdAt properties: success: type: boolean example: false message: type: string data: type: object additionalProperties: true description: Empty object when present. verificationStatus: type: string example: FAILED verificationStatusCode: type: integer example: 6 transactionId: type: string format: uuid nullable: true verificationType: type: string example: biometrics_verification metadata: type: object additionalProperties: true nullable: true createdAt: type: string BiometricsVerificationBlacklistNotFoundResponse: type: object required: - success - code - message - verificationStatus - verificationStatusCode - transactionId - verificationType - createdAt properties: success: type: boolean example: false code: type: string enum: - BLACKLIST_NOT_FOUND message: type: string verificationStatus: type: string example: FAILED verificationStatusCode: type: integer example: 6 transactionId: type: string format: uuid verificationType: type: string example: biometrics_verification metadata: type: object additionalProperties: true nullable: true createdAt: type: string BiometricsVerificationData: type: object required: - livenessPass - livenessScore properties: livenessPass: type: boolean description: Whether the face met the effective liveness threshold. livenessScore: type: number minimum: 0 maximum: 100 description: >- Engine liveness confidence as a percentage (0–100), on the same scale as `livenessThreshold`. duplicateDetection: $ref: '#/components/schemas/DuplicateDetectionResult' blacklistDetection: $ref: '#/components/schemas/BlacklistDetectionResult' DuplicateDetectionResult: type: object required: - performed properties: performed: type: boolean description: >- `true` when duplicate screening ran or was attempted. This object is only returned when the request flag was set. hasMatches: type: boolean nullable: true description: >- Whether duplicate faces were found. `null` when screening was requested but could not complete; see `error`. enrolled: type: boolean description: Whether enrolment into the duplicate watchlist succeeded. matches: type: array items: $ref: '#/components/schemas/DuplicateDetectionMatch' description: Present when screening completed (`hasMatches` is not `null`). error: type: string description: Present when `hasMatches` is `null` — screening could not complete. description: >- Returned only when `performDuplicateDetection` was `true`. Omitted entirely when the flag was not set. BlacklistDetectionResult: type: object required: - performed properties: performed: type: boolean description: >- `true` when blacklist screening ran or was attempted. This object is only returned when the request flag was set. hasMatches: type: boolean nullable: true description: >- Whether any blacklist returned a match. `null` when screening was requested but could not complete; see `error`. blacklists: type: array items: $ref: '#/components/schemas/BlacklistScreeningResult' description: Per-blacklist outcomes when screening completed. error: type: string description: Present when `hasMatches` is `null` — screening could not complete. description: >- Returned only when `performBlacklistDetection` was `true`. Omitted entirely when the flag was not set. DuplicateDetectionMatch: type: object properties: record_id: type: string format: uuid name: type: string similarity_score: type: number description: Match similarity percentage. transactionId: type: string format: uuid description: >- Transaction id of the earlier passthrough call under which the matched face was enrolled. additionalProperties: true BlacklistScreeningResult: type: object properties: blacklistId: type: string format: uuid blacklistName: type: string hasMatches: type: boolean matches: type: array items: $ref: '#/components/schemas/BlacklistDetectionMatch' BlacklistDetectionMatch: type: object properties: record_id: type: string format: uuid name: type: string similarity_score: type: number blacklistFaceUploadId: type: string format: uuid description: Identifier of the enrolled blacklist face that matched. additionalProperties: true securitySchemes: bearerAuth: type: http scheme: bearer description: Use your API token as a Bearer token in the `Authorization` header. ````