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

# Blacklist

> Block transactions by field value, with TTLs and event-driven auto-population.

The blacklist lets operators block transactions based on values extracted from the decision context — a card
fingerprint, a device IP, a customer ID, and so on. Entries can be created manually through the Admin API or
populated automatically from [lifecycle events](/products/specter/concepts/lifecycle-events).

## Entries

A blacklist entry blocks a specific value at a given JSONPath, optionally with an expiry.

```json theme={null}
{
  "field_path": "$.credential_fingerprint",
  "value": "crd_4ba218...",
  "ttl_seconds": 604800
}
```

<ParamField body="field_path" type="string" required>
  JSONPath matched against the decision context (e.g. `$.device.ip`, `$.customer.id`).
</ParamField>

<ParamField body="value" type="string" required>
  The exact value to block.
</ParamField>

<ParamField body="ttl_seconds" type="integer">
  Time-to-live. Omit for a permanent entry.
</ParamField>

Manage entries with the Admin API (scopes `admin:blacklist:read` / `admin:blacklist:write`):

| Method   | Path                        |
| -------- | --------------------------- |
| `GET`    | `/api/admin/blacklist`      |
| `GET`    | `/api/admin/blacklist/{id}` |
| `POST`   | `/api/admin/blacklist`      |
| `DELETE` | `/api/admin/blacklist/{id}` |

For card-fingerprint entries, Specter stores a masked-PAN `display_hint` (e.g. `****1234`) alongside the opaque
fingerprint so operators can identify the card without exposing it.

## Blacklist rules

A `blacklist` rule in a ruleset blocks any decision whose context contains a matching value, and can
**auto-populate** the blacklist when a configured event arrives:

```json theme={null}
{
  "id": "block-known-cards",
  "type": "blacklist",
  "name": "Block known fraudulent credentials",
  "action": "BLOCK",
  "enabled": true,
  "fields": ["$.credential_fingerprint", "$.device.ip"],
  "ttl_seconds": 604800,
  "populate_on": ["fraud_report", "chargeback"]
}
```

<ResponseField name="fields" type="array">
  JSONPath fields checked against the blacklist on each decision.
</ResponseField>

<ResponseField name="ttl_seconds" type="integer">
  TTL applied to auto-populated entries. Omit for permanent.
</ResponseField>

<ResponseField name="populate_on" type="array">
  Event types that trigger auto-population: `fraud_report`, `chargeback`, `failed`. Defaults to `["fraud_report"]`.
</ResponseField>

When a matching [lifecycle event](/products/specter/concepts/lifecycle-events) is ingested, Specter upserts
blacklist entries for every configured field using the originating decision's values. A card that charges back
is then blocked on its next attempt.

## Related

<Card title="Lifecycle events" icon="arrows-spin" href="/products/specter/concepts/lifecycle-events">
  The events that drive blacklist auto-population.
</Card>