Create matches

POST /v1/principal/matches/{id}

Principal → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/principal/matches/{id}`
Method	`POST`
Operation	`post_principal_matches_by_id`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Decides one sanctions match, as a Hanzo platform reviewer. SuperAdmin only — an admin of the org the match names is refused, because that would be the org deciding its own case — and the decision is written and put on the audit trail in one transaction: a decision the trail does not take is not made.

cleared records a namesake: the org's names resemble a designated person's and the other identifiers show a different one. It covers the hits the reviewer read, and a later name close to the same person reopens it. confirmed records the designated person itself, and blocks every payment to or from the org whatever it is later called. A decision may be changed only by another decision, with its own note.

Request

4 fields, body application/json (required).

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the match, from the path.
`decision`	body	string	—	Decision is cleared (a namesake: the identifiers show a different person) or confirmed (the designated person).
`id`	body	string	—	ID is the match, from the path.
`note`	body	string	—	Note is the reviewer's reason — which identifiers decided it.

Response

Status	Body	Meaning
`200`	principal.Match	ok
`default`	problem-details	refused

200 body — 16 fields.

Field	In	Type	Always	Description
`decidedAt`	body	integer (int64)	—	DecidedAt is when, unix seconds.
`decidedBy`	body	string	—	DecidedBy is the reviewer, or "exact designated address".
`entry`	body	string	—	Entry is the designated subject's primary name, or the jurisdiction's.
`foundAt`	body	integer (int64)	—	FoundAt is when a screening first found it, unix seconds.
`hits`	body	principal.Hit[]	—	Hits are the org's names, addresses and countries that matched, in the order they were first seen.
`hits[].kind`	body	string	—	Kind is name (matched fuzzily), address (matched exactly) or jurisdiction.
`hits[].role`	body	string	—	Role is where it came from: entity, founder, form, wallet, or — for a country — citizenship, organization or residence.
`hits[].subject`	body	string	—	Subject is the name, address or country as the org stated it.
`id`	body	string	—	ID addresses the match for a reviewer's decision.
`list`	body	string	—	List is the publisher — ofac, un, eu or ofsi — or jurisdiction for an embargoed place.
`note`	body	string	—	Note is the reviewer's reason.
`org`	body	string	—	Org is the org the match names.
`reason`	body	string	—	Reason is what first matched, and which identifiers agreed or conflicted.
`ref`	body	string	—	Ref is the entry's reference on that list, or the country code.
`score`	body	number (double)	—	Score is the highest similarity seen, 0 to 1; an address or a jurisdiction is 1.
`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.postPrincipalMatchesById({ id: 'id', decision: "<decision>", id: "<id>" });

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).post_principal_matches_by_id(id='id', decision="<decision>", id="<id>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.PrincipalAPI.PostPrincipalMatchesById(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::post_principal_matches_by_id(&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).postPrincipalMatchesById();

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 -X POST https://api.hanzo.ai/v1/principal/matches/<id> \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "decision": "<decision>",
       "id": "<id>"
     }'

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.

Principal API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page