List matches
Lists sanctions matches across every org, oldest first — the platform's review queue.
GET /v1/principal/matches
| Address | https://api.hanzo.ai/v1/principal/matches |
| Method | GET |
| Operation | get_principal_matches |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Lists sanctions matches across every org, oldest first — the platform's review queue. SuperAdmin only: a match names an org the platform screened, and the org it names is not the one to decide it.
A match is one org against one designation or embargoed jurisdiction, with every name, address or country of the org that brought them close. Open matches are the ones no payment to or from their org clears past until a reviewer decides them; a match is recorded when a payment to or from its org is cleared.
Request
1 field.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string | — | Status is open, cleared or confirmed; open when omitted. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | principal.matchList | ok |
default | problem-details | refused |
200 body — 17 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
matches | body | principal.Match[] | — | |
matches[].decidedAt | body | integer (int64) | — | DecidedAt is when, unix seconds. |
matches[].decidedBy | body | string | — | DecidedBy is the reviewer, or "exact designated address". |
matches[].entry | body | string | — | Entry is the designated subject's primary name, or the jurisdiction's. |
matches[].foundAt | body | integer (int64) | — | FoundAt is when a screening first found it, unix seconds. |
matches[].hits | body | principal.Hit[] | — | Hits are the org's names, addresses and countries that matched, in the order they were first seen. |
matches[].hits[].kind | body | string | — | Kind is name (matched fuzzily), address (matched exactly) or jurisdiction. |
matches[].hits[].role | body | string | — | Role is where it came from: entity, founder, form, wallet, or — for a country — citizenship, organization or residence. |
matches[].hits[].subject | body | string | — | Subject is the name, address or country as the org stated it. |
matches[].id | body | string | — | ID addresses the match for a reviewer's decision. |
matches[].list | body | string | — | List is the publisher — ofac, un, eu or ofsi — or jurisdiction for an embargoed place. |
matches[].note | body | string | — | Note is the reviewer's reason. |
matches[].org | body | string | — | Org is the org the match names. |
matches[].reason | body | string | — | Reason is what first matched, and which identifiers agreed or conflicted. |
matches[].ref | body | string | — | Ref is the entry's reference on that list, or the country code. |
matches[].score | body | number (double) | — | Score is the highest similarity seen, 0 to 1; an address or a jurisdiction is 1. |
matches[].status | body | string | — | Status is open (a reviewer decides), cleared (a namesake, decided) or confirmed (the designated person, decided — or a designated address). |
Failure carries the platform error shape — see Errors.
Examples
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, PrincipalApi } from 'hanzoai';
const api = new PrincipalApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getPrincipalMatches();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import PrincipalApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = PrincipalApi(client).get_principal_matches()cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.PrincipalAPI.GetPrincipalMatches(context.Background()).Execute()
if err != nil {
return err
}use hanzo_client::apis::{configuration::Configuration, principal_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = principal_api::get_principal_matches(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.PrincipalApi;
ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));
var result = new PrincipalApi(client).getPrincipalMatches();The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl https://api.hanzo.ai/v1/principal/matches \
-H "Authorization: Bearer $HANZO_API_KEY"MCP declares no tool for principal — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.
How is this guide?