> ## 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.
# Internal Blacklists
> Create company-owned face watchlists and screen incoming verifications against them in your Trust Flows.
An **internal blacklist** is a company-owned watchlist of face images that you build yourself. During verification, incoming faces are screened against the blacklists you select in your Trust Flow tool settings.
Blacklists are company-scoped and private. A blacklist is only ever visible and matchable within the company that created it.
## When to use it
Use Internal Blacklists when you need to block or flag people you already know about, for example:
* Known fraudsters
* Repeat chargeback or abuse actors
* Previously rejected applicants
* Internally banned users
* Staff or agent fraud rings
* Regulator- or partner-supplied deny lists
## Internal Blacklists vs Duplicate Detection
These two features often get confused. They live in the same tool settings panel and can run together, but they answer different questions.
| | Internal Blacklist | Duplicate Detection |
| ----------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------- |
| What it screens against | Only the specific blacklists you select in the tool settings | Every face your company has previously enrolled through verification |
| Who populates it | You do — deliberately, via the dashboard or the API | Populated automatically as verifications run |
| Purpose | "Is this a person we've decided to block?" | "Have we already seen this face before?" |
| Result shown as | Blacklist Detected (per blacklist, with the blacklist's name) | Duplicate Detected |
Both surface on the same **Duplicates & Blacklists** tab of a Trust Validation.
## Before you start
* The feature must be enabled for your company. If **Internal Blacklists** is not in the sidebar under Features, contact your IDmeta account manager.
* You need company-level dashboard access to create blacklists, enroll faces, and configure Trust Flows.
## Step 1 — Create a blacklist
In the dashboard, go to **Features → Internal Blacklists** (`/company/internal-biometrics`).
Click **+ Create Blacklist**. Enter a **Name** (required, unique within your company, max 100 characters) and an optional **Description** (max 255 characters). Click **Create**.
Each blacklist has an **Active** or **Inactive** status. Inactive blacklists cannot receive new face uploads and are not screened against.
## Step 2 — Add face images
Click a blacklist name in the list to open its detail page. The **Enrolled Faces in Blacklist** table shows each face's ID, Name, Status, and Enrolled At timestamp.
Click **Add Face Images** and select your files.
Standard limits (may be configurable per deployment):
* Formats: JPG, JPEG, PNG
* Up to 50 images per upload
* Up to 10 MB per file
* Each image should contain one clear, front-facing face
The face **Name** is taken from the uploaded file's filename (without extension). Name your files meaningfully — that name appears in match results.
Enrollment is asynchronous. The upload is accepted immediately and processed in the background. Faces move from **Pending** → **Enrolled** or **Failed**.
Use the refresh button on the Enrolled Faces table to see updated statuses. A large batch takes a short while.
A failed face shows the reason returned by the biometric engine (for example, no face detected). Fix the image and re-upload it — failed rows do not block the rest of the batch.
A batch can finish as **Completed**, **Partially Completed** (some faces failed), or **Failed**.
Each enrolled face gets its own ID. That same ID appears as **Blacklist Face Upload ID** on a Trust Validation match, so you can trace a hit back to the exact enrolled image.
## Step 3 — Turn on blacklist screening in a Trust Flow
Open the [Trust Flow](/trust-flows/creating-a-trust-flow) that includes **Biometrics Verification**, then open the product **Tool Settings**.
Turn on **Perform Blacklist Detection**. Under **Blacklists to screen against**, select one or more blacklists. The picker shows each blacklist's enrolled face count (for example, `Blacklist 2 (8 faces)`).
Only blacklists owned by your company can be selected.
Click **Save Settings**, then save the Trust Flow as described in [Creating a Trust Flow](/trust-flows/creating-a-trust-flow).
Screening runs when the verification is finalised. The incoming selfie is compared against every face in the selected blacklists.
## Step 4 — Read the results
When a match is found, open the Trust Validation detail page and select the **Duplicates & Blacklists** tab. Matches appear in a **Biometrics Verification Blacklist Detected** card.
Each match row shows:
* **Blacklist Name** — which list the face matched
* **Full Name** — the enrolled face's name (from the filename)
* **Similarity Score** — the engine's similarity score for that match (for example, 99%)
* **Blacklist Face Upload ID** — links back to the enrolled face
If the same face matches faces in several blacklists, each blacklist is reported separately.
By default, a match sets the Trust Validation to **Review Needed** so a human can adjudicate. The default action is configurable — you can instead **Reject** the validation automatically. Review Needed is the default. The engine returns a similarity score per match; there is no fixed threshold documented here.
## Managing blacklists
| Action | What it does |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Edit name or description | Updates how the blacklist appears in the list and in match results. Names must stay unique within your company. |
| Deactivate | Sets status to Inactive. The blacklist cannot receive new face uploads and is not screened against. |
| Delete a face | Removes that face from the blacklist so it is no longer matched in future verifications. It does not change Trust Validations that already matched it. |
## Best practices
* Enroll clear, well-lit, front-facing images. Avoid group photos, heavy occlusion, sunglasses, low resolution, or screenshots of screens.
* Enroll two or three images of the same person when you have them. More angles means more reliable matching.
* Use filenames that identify the person or case. They become the face's Name in match results.
* Keep separate blacklists for separate purposes (for example, Confirmed Fraud, Chargeback Abuse, Internal Ban). Match results then say why someone was flagged, and you can screen against different lists in different Trust Flows.
* Keep lists current. Remove faces that are no longer relevant.
* Keep a human in the review loop rather than auto-rejecting, unless your policy explicitly calls for it.
Face images are biometric personal data. Only enroll images you have a lawful basis to store and screen against. Follow your retention policy and applicable privacy law, and keep an internal record of why each person was added.
## Troubleshooting
The feature is permission-gated. Contact your IDmeta account manager to have it enabled for your company.
Enrollment is queued and asynchronous. Use the refresh button on the Enrolled Faces table. Large batches take a short while to process.
Check the failure reason shown on the row. This is usually image quality or no detectable face. Fix the image and re-upload it.
Confirm that:
1. At least one blacklist is selected in the tool settings
2. The blacklist is **Active** and has **Enrolled** faces (not Pending or Failed)
3. Settings were saved and the Trust Flow was re-saved before the validation ran
Common causes: the blacklist is Inactive, the file is not JPG/JPEG/PNG, a file exceeds 10 MB, or the batch has more than 50 files.
The blacklist belongs to another company, or it is inactive.
## Enroll faces via API
Everything above can also be done programmatically for bulk or automated enrollment.
| Method | Path | Purpose |
| ------ | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET` | [`/api/v3/biometric-blacklists`](/api-reference/internal-blacklist/face-enrollment/list-blacklists) | List your blacklists and their IDs (needed for the upload call) |
| `POST` | [`/api/v3/biometric-blacklists/{blacklistId}/faces`](/api-reference/internal-blacklist/face-enrollment/upload-faces) | Upload up to 50 images; returns an `uploadId` and is processed asynchronously (`202 Accepted`) |
| `GET` | [`/api/v3/biometric-blacklists/uploads/{uploadId}`](/api-reference/internal-blacklist/face-enrollment/poll-upload-status) | Poll the batch status, including succeeded and failed counts |
Creating, editing, and deleting blacklists is **dashboard-only**. The API enrolls faces into blacklists that already exist.
Authentication follows the same scheme as all other v3 endpoints. See [Introduction to the API](/api-reference/introduction).
End-to-end flow, status values, and authentication.
`GET /api/v3/biometric-blacklists`
`POST /api/v3/biometric-blacklists/{blacklistId}/faces`
`GET /api/v3/biometric-blacklists/uploads/{uploadId}`