Skip to main content
POST
Use this endpoint when you orchestrate identity checks yourself and only need duplicate and blacklist screening on a face image. Each response includes a transactionId you can store; there is no Trust Flow, no Trust Validation, and no combined IDmeta outcome beyond the statuses below. For a face liveness check, use Biometrics Verification. Call this endpoint separately if you also need duplicate or blacklist screening.

​
Before you call

When performDuplicateDetection is true, the submitted face is enrolled into your company’s duplicate watchlist as a side effect. That enrolment is what allows later calls to match it. Enable duplicate detection only when you intend to add this face to the watchlist under name.
Blacklists are screen-only on this endpoint. Faces enter a blacklist only through the blacklist upload flow, never through biometrics detection. The image you submit is not stored. IDmeta logs that the call ran, which checks ran, and match counts — not the image, engine payload, or matched identities.

​
Authentication and plan

Same as other /api/v3 Stateless Verification API endpoints: Bearer token (Authorization: Bearer <token>) or HMAC headers (X-HMAC-SIGNATURE, X-TIMESTAMP, X-USER-ID). See Introduction — Authentication. Your company must hold the biometrics_detection plan. Without it, the API returns HTTP 403 before any screening runs.

​
Verification status

This endpoint never returns REJECTED. A duplicate or blacklist hit is a finding for you to act on; IDmeta does not decide whether the subject should be blocked.

​
Interpret data

Request flags control which keys appear in data. Duplicate-only requests omit blacklistDetection entirely — not null, not an empty object. When a requested check completes, read hasMatches as a boolean. When it could not run, hasMatches is null with an error string. null is not a clean screen — treat it as an unknown outcome and do not approve on that basis alone. Duplicate matches always include transactionId (the earlier biometrics detection call that enrolled the matched face). Blacklist matches always include blacklistFaceUploadId. Other fields inside each match object come from the face-identity engine (similarity scores, names, and so on).

​
Billing

A completed screening is billed whether or not it found matches. Validation errors, unresolvable blacklists, unreadable images, and engine failures release the credit reservation and are not charged.

​
Examples

Replace {environment-subdomain}, {your_api_token}, and HMAC headers with your values.

​
1. Duplicate detection only, clean (VERIFIED)

​
2. Duplicate and blacklist, duplicate hit (REVIEW_NEEDED)

​
3. Blacklist hit on one of two lists (REVIEW_NEEDED)

​
4. Unknown blacklist id (404 BLACKLIST_NOT_FOUND)

​
5. Engine unreachable (FAILED, hasMatches: null)

HTTP status for this case is 502. Responses that include a top-level code omit data entirely; this failure has no code and returns per-check errors in data instead.

Authorizations

​
Authorization
string
header
required

Use your API token as a Bearer token in the Authorization header, or HMAC signature headers (X-HMAC-SIGNATURE, X-TIMESTAMP, X-USER-ID) as for other v3 endpoints.

Headers

​
Authorization
string
required
Example:

"Bearer {your_api_token}"

​
Accept
string
default:application/json
​
Content-Type
string
default:application/json

Body

​
image
string
required

Base64 data URI (data:image/jpeg;base64,...) or a multipart file when posting multipart/form-data. Bare base64 without the data: prefix is rejected.

​
name
string
required

Label for enrolment into the duplicate watchlist. Reported on future duplicate matches.

Maximum string length: 255
​
performDuplicateDetection
boolean
required

When true, screens against the duplicate watchlist and enrols this face. Required; not defaulted.

​
performBlacklistDetection
boolean
default:false

When true, screens against the blacklists in blacklistIds. Does not enrol into blacklists.

​
blacklistIds
string<uuid>[]

UUID strings of active biometric blacklists. Required in practice when performBlacklistDetection is true. Unresolvable ids yield HTTP 404 BLACKLIST_NOT_FOUND.

​
metadata
object | null

Free-form data echoed unchanged on the response.

Response

Screening completed. Clean and match outcomes use HTTP 200. Match findings set verificationStatus to REVIEW_NEEDED; a clean screen sets VERIFIED.

​
success
boolean
required
Example:

true

​
message
string
required
​
data
object
required

Only keys for checks requested on the call are present.

​
verificationStatus
enum<string>
required

Never REJECTED. VERIFIED = no matches; REVIEW_NEEDED = at least one match; FAILED only when returned on error paths with screening failure.

Available options:
VERIFIED,
REVIEW_NEEDED,
FAILED
​
verificationStatusCode
enum<integer>
required

3 = Verified, 2 = Review Needed, 6 = Failed.

Available options:
3,
2,
6
​
transactionId
string<uuid>
required

Correlate this call in your systems. Duplicate matches reference earlier enrolment transaction ids.

​
verificationType
string
required
Example:

"biometrics_detection"

​
createdAt
string<date-time>
required
​
metadata
object | null