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

# Address Registry Screening

> Screen incoming and outgoing transactions by counterparty identity with Address Registry Screening: create counterparty groups, build the policy, and activate ARS through the Fireblocks API or Console.

Address Registry Screening (ARS) checks a transaction's counterparty against Fireblocks' shared registry of known, verified addresses, as part of your compliance policy. It answers one question: does this transaction involve an address that belongs to a verified entity, or to a counterparty you have grouped for special handling?

ARS covers both incoming and outgoing transactions, matching on the source or the destination address. It is the first check in the screening flow, before AML/KYT and Travel Rule, and it is free.

ARS is not a risk screening, and it does not decide whether the Travel Rule applies. A `not found` result does not mean an address is unhosted, illicit, or non-compliant: it may belong to a counterparty that is not a Fireblocks customer, or that has opted out. To register your legal entity or look up addresses directly, see [Address Registry](/reference/address-registry).

## Common use cases

* **Transact only with verified counterparties**: reject transactions to or from addresses not found in the registry.
* **Restrict jurisdictions**: block transactions with counterparties in jurisdictions you have grouped as restricted.

## What you can do through the API

| Task | Console | API |
| - | - | - |
| Manage counterparty groups | Yes | Yes |
| Build the Trigger (Screening Policy) and Outcome (Post-Screening Policy) | Yes | No |
| Configure timeout behavior | Yes | No |
| Activate or deactivate ARS | Yes | Yes |

## Before you start

ARS depends on Address Registry. All workspaces are opted in to Address Registry by default. If your workspace has opted out, activating ARS fails, and opting out later disables ARS until you opt back in. See [Address Registry](/reference/address-registry).

## How ARS decides

You build the ARS policy in the Console, under **Policies** > **Compliance**. It works like any other compliance policy (see [Compliance Policies](/docs/compliance-policies)):

* **Trigger (Screening Policy)** decides which transactions get a counterparty check, by source, destination, asset, and amount.
* **Timeout behavior** decides whether a transaction is accepted or rejected if the registry check does not return in time.
* **Outcome (Post-Screening Policy)** decides the action based on the result:

| Condition | Action |
| - | - |
| Counterparty is in a specific group | Accept or reject |
| Counterparty found, but not in any group | Falls through to your catch-all default rule |
| Counterparty not found in the registry | Accept or reject |

## Step 1: Create counterparty groups

A counterparty group is a named set of counterparties matched by jurisdiction. Today, jurisdiction is the only grouping attribute. You define groups first, then reference them in your Outcome (Post-Screening Policy). Create as many groups as your policy needs.

| Operation | Endpoint |
| - | - |
| Create a group | [`POST /counterparty_groups`](/api-reference/compliance/create-a-counterparty-group) |
| List groups | [`GET /counterparty_groups`](/api-reference/compliance/list-counterparty-groups) |
| Get a group | [`GET /counterparty_groups/{groupId}`](/api-reference/compliance/get-a-counterparty-group) |
| Update a group | [`PATCH /counterparty_groups/{groupId}`](/api-reference/compliance/update-a-counterparty-group) |
| Delete a group | [`DELETE /counterparty_groups/{groupId}`](/api-reference/compliance/delete-a-counterparty-group) |

Creating, updating, and deleting groups requires the Admin or Non-Signing Admin role. Create and update requests accept an optional `Idempotency-Key` header, valid for 24 hours; the delete endpoint does not accept this header.

| Field | Type | Description |
| - | - | - |
| `groupId` | string (UUID) | Returned by Fireblocks. |
| `name` | string | Required. The group's display name. |
| `description` | string | Optional. |
| `jurisdictionCodes` | string\[] | Required. ISO 3166-1 alpha-2 country codes the group matches, for example `["US", "SG"]`. |
| `isActive` | boolean | Whether the group is active. |
| `createdAt`, `updatedAt` | string (ISO 8601) | Returned by Fireblocks. |

```ts theme={"system"}
const { data: group } = await fireblocks.compliance.createCounterpartyGroup({
  createCounterpartyGroupRequest: {
    name: "APAC Financial Partners",
    description: "APAC-based financial institution counterparties", // Optional
    jurisdictionCodes: ["SG", "HK"],
  },
});

console.log(group.groupId);
```

## Step 2: Build the policy

In the Console, add Trigger (Screening Policy) rules that decide which transactions ARS checks, then Outcome (Post-Screening Policy) rules that reference your counterparty groups. See [About Address Registry Screening](https://support.fireblocks.io/hc/en-us/articles/30614325399836-About-Address-Registry-Screening) on the Help Center.

## Step 3: Activate ARS

| Operation | Endpoint |
| - | - |
| Activate | [`POST /screening/ars/config/activate`](/api-reference/compliance/activate-ars-address-registry-screening) |
| Deactivate | [`POST /screening/ars/config/deactivate`](/api-reference/compliance/deactivate-ars-address-registry-screening) |

Both return the current configuration:

```json theme={"system"}
{
  "active": true,
  "lastUpdate": "2026-01-29T12:00:00.000Z"
}
```

Once active, ARS applies to every transaction that matches your Trigger (Screening Policy). Deactivating it stops the check until you activate it again.

## Results

* **While it runs:** the transaction is in `PENDING_AML_SCREENING`, the same status as every other check.
* **On rejection:** `subStatus` is `REJECTED_AML_SCREENING`, the same value as other checks, delivered on the `transaction.status.updated` webhook event. See [Compliance Events & Webhooks](/docs/compliance-events-webhooks).
* **Full result:** ARS results are not included in [`GET /screening/transaction/{txId}`](/api-reference/compliance/provides-all-the-compliance-details-for-the-given-screened-transaction), which covers AML/KYT and Travel Rule only.
* **Next steps:** to bypass a rejected transaction, see [Transaction Screening Operations](/docs/transaction-screening-operations).

## Limitations

* **European and Swiss-hosted workspaces**: Address Registry, and so ARS, is not supported. Lookups against addresses from these workspaces return `not_found`.
* **Developer Sandbox workspaces**: Address Registry, and so ARS, is not supported.
* **Coverage**: the registry only resolves addresses within the Fireblocks network.

Wherever the registry returns no match, your rule for "Counterparty not found in the registry" applies.

## On the Help Center

To build the ARS policy or manage counterparty groups in the Console, see [About Address Registry Screening](https://support.fireblocks.io/hc/en-us/articles/30614325399836-About-Address-Registry-Screening).