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

# Sanctions Listing

> Check a company or a person name against the US Treasury's list of Specially Designated Nationals

## Overview

Checks a name against the US Treasury's list of Specially Designated Nationals and returns the entries that match. Each match has a score, the name that matched and the entry as the list publishes it. There are two routes, one for each kind of name:

| Route | Checks |
| - | - |
| `POST /v1/tools/lookup/company-sanctions` | A company name against the entries for companies and other organizations |
| `POST /v1/tools/lookup/person-sanctions` | A person name against the entries for individuals |

A company name never matches an individual's entry, and the reverse. Both routes take the same request and return the same response; only `tool` differs (`company_sanctions` or `person_sanctions`).

Results return in the response, with no polling.

<Warning>
  A screening aid, not a legal determination. No match means no entry on the lists named scored at or above the minimum; it does not mean the party is clear.
</Warning>

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="name" type="string" required>
  The name to check, 2 to 200 characters, free text. Word order, accents and punctuation do not matter. A name of one word needs at least 3 letters.
</ParamField>

<ParamField body="min_score" type="number">
  The lowest score of a match to return, 0.5 to 1 (default 0.85). See [What a score means](#what-a-score-means).
</ParamField>

<ParamField body="limit" type="integer">
  The most matches to return, highest score first (1 to 25, default 10). `total` counts every match at or above `min_score`, which may be more than `limit`.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## What a score means

A score runs from 0.5 to 1 and says how closely the words of your name match the words of an entry's name or of one of its other names (its aliases).

* `1`: the same words, in any order.
* Below 1: a spelling variant, a missing or extra word, a missing middle name, or an initial in place of a name.

A higher score is a closer match, not a finding. Read `matched_name` and the entry's `remarks` (dates of birth, places, identity numbers where the list gives them) before you act on a match.

`min_score` sets the lowest score returned. Lower it to catch more spelling variants, at the cost of more matches that are not the party you mean. Raise it to 1 to see only the same words.

## Response (200)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.receipt_id" type="string">
  The receipt for the payment
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  `company_sanctions` or `person_sanctions`
</ResponseField>

<ResponseField name="data.total" type="integer">
  How many entries scored at or above `min_score`. `matches` holds at most `limit` of them.
</ResponseField>

<ResponseField name="data.matches" type="object[]">
  The matching entries, highest score first. Empty when nothing scored at or above `min_score`.
</ResponseField>

<ResponseField name="data.matches[].score" type="number">
  0.5 to 1, as described above
</ResponseField>

<ResponseField name="data.matches[].matched_name" type="string">
  The name that scored: the entry's own name or one of its other names, as the list writes it
</ResponseField>

<ResponseField name="data.matches[].entry" type="object">
  The entry as the list publishes it: `number`, `name` (a person is written `SURNAME, Given names`), `programs` (the sanctions programs it is listed under), `title`, `remarks`, `other_names` (each with `kind`: `aka`, `fka` or `nka`, and `name`) and `addresses` (each with `street`, `city` and `country`)
</ResponseField>

<ResponseField name="data.lists" type="object[]">
  Every list that was checked
</ResponseField>

<ResponseField name="data.lists[].name" type="string">
  The name of the list, for example `US Treasury list of Specially Designated Nationals`
</ResponseField>

<ResponseField name="data.lists[].as_of" type="string">
  The date and time of the list file the answer was read from (ISO 8601). Read it with every answer: a result is only as current as its `as_of`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/company-sanctions \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "name": "Banco Nacional de Cuba",
      "min_score": 0.85,
      "limit": 10
    }'
  ```

  ```typescript SDK theme={null}
  import { OneShot } from "@oneshot-agent/sdk";

  const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

  const result = await agent.tool("lookup/company-sanctions", {
    name: "Banco Nacional de Cuba",
    min_score: 0.85,
    limit: 10,
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "request_id": "6f1c2a94-0d1e-4b53-9d0e-2f6f0c1f7a11",
      "receipt_id": "rcpt_01HX0000000000000000000000",
      "status": "completed",
      "tool": "company_sanctions",
      "total": 1,
      "matches": [
        {
          "score": 1,
          "matched_name": "BANCO NACIONAL DE CUBA",
          "entry": {
            "number": "306",
            "name": "BANCO NACIONAL DE CUBA",
            "programs": ["CUBA"],
            "title": null,
            "remarks": "a.k.a. 'BNC'.",
            "other_names": [{ "kind": "aka", "name": "NATIONAL BANK OF CUBA" }],
            "addresses": []
          }
        }
      ],
      "lists": [
        {
          "name": "US Treasury list of Specially Designated Nationals",
          "as_of": "2026-10-13T00:00:00.000Z"
        }
      ]
    }
  }
  ```
</ResponseExample>

<Info>See [Pricing](/pricing) for the price of a call.</Info>

## No match

No match is a completed, charged result with `total` 0 and an empty `matches`. It means no entry on the lists named in `lists` scored at or above `min_score`. It does not mean the party is clear.

## When the list is out of date

If a list has never been loaded, or its newest file is older than 72 hours, the call answers `503` with `list_out_of_date` and does not return a result from it. The response names the lists that are out of date. Try again later.

When the check runs before payment, nothing is charged. When it is found after payment, the call is recorded as failed, the response carries its `request_id` and `receipt_id`, and a failed call is not charged.

## Errors

* `400 invalid_request`: `name` is missing, too short, too long or has no letter or digit, or `min_score` or `limit` is out of range. Refused before payment.
* `503 list_out_of_date`: a list is out of date, as above.
* `500 internal_error`: the call failed. It is recorded as failed and is not charged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.