> ## 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.

# Liquor Licence

> Look up active New York liquor licences by licence id or business name, with classes, premises and expiration dates.

Look up a business location in the New York State Liquor Authority register, which lists active licences only and refreshes daily. `state` is required; currently only NY is covered. Give at least one of `license_id` and `name`; the id takes precedence when both are given. Names are matched as stored, ignoring case, as a substring of the trade or legal name. Try a short distinctive fragment: SORLEY matches MC SORLEYS, but McSorley's does not. `zipcode` narrows either search. Return at most `limit` licences, newest last issue date first, with their class, premises, issue dates and expiration date. Missing values are null; dates are YYYY-MM-DD. An empty licenses list is a completed result: no active licence was found under that name or id, not evidence that the location never held one. Pending and inactive licences are not searched.

## Authentication

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

## Request Body

**state** `string` *required*

State issuing the licence. One of `NY`.

**license\_id** `string`

The source licence identifier; takes precedence over name.

**name** `string`

A distinctive fragment of the trade or legal name, matched ignoring case. 2 to 100 characters.

**zipcode** `string`

ZIP code to narrow the search.

**limit** `integer`

Most licences to return. From 1 to 25. Defaults to `10`.

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

## Response (200 OK)

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

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `business_liquor_license`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `New York State Liquor Authority`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string`

The rows have no update timestamp; null. retrieved\_at dates the answer.

## Result

Nested under `data.result`.

**data.result.state** `string`

The state asked for.

**data.result.licenses** `object[]`

Matching active licences, newest last issue date first; empty when none matched.

**data.result.licenses\[].license\_id** `string`

The source licence identifier.

**data.result.licenses\[].legal\_name** `string`

The legal name on the licence. `null` when the source gives no value.

**data.result.licenses\[].trade\_name** `string`

The trade name (DBA), or null when absent.

**data.result.licenses\[].description** `string`

The licence type in the authority's words. `null` when the source gives no value.

**data.result.licenses\[].class** `string`

The licence class code, retaining leading zeros. `null` when the source gives no value.

**data.result.licenses\[].address** `string`

The actual address of the premises, or null when absent.

**data.result.licenses\[].city** `string`

The city of the premises, or null when absent.

**data.result.licenses\[].county** `string`

The county of the premises. `null` when the source gives no value.

**data.result.licenses\[].zipcode** `string`

The ZIP code of the premises. `null` when the source gives no value.

**data.result.licenses\[].original\_issue\_date** `string`

Original issue date, YYYY-MM-DD or null.

**data.result.licenses\[].last\_issue\_date** `string`

Most recent issue date, YYYY-MM-DD or null.

**data.result.licenses\[].effective\_date** `string`

Effective date, YYYY-MM-DD or null.

**data.result.licenses\[].expiration\_date** `string`

Expiration date, YYYY-MM-DD or null.

**data.result.licenses\[].latitude** `number`

Latitude of the premises, or null when absent.

**data.result.licenses\[].longitude** `number`

Longitude of the premises, or null when absent.

**data.result.total** `integer`

Rows returned, not a count of all matches; the source does not send a count.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/business-liquor-license \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "state": "NY",
    "license_id": "0138-21-123999"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/business-liquor-license", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "state": "NY",
    "license_id": "0138-21-123999"
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/business-liquor-license', {
  state: 'NY',
  license_id: '0138-21-123999'
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "business_liquor_license",
    "result": {
      "state": "NY",
      "total": 1,
      "licenses": [
        {
          "license_id": "0138-21-123999",
          "legal_name": "MC SORLEYS OLD ALE HOUSE INC",
          "trade_name": "MC SORLEYS OLD ALE HOUSE",
          "description": "Food & Beverage Business",
          "class": "0138",
          "address": "15 E 7TH STREET",
          "city": "NEW YORK",
          "county": "New York",
          "zipcode": "10003",
          "original_issue_date": "2025-04-03",
          "last_issue_date": "2025-04-03",
          "effective_date": "2024-07-01",
          "expiration_date": "2027-06-30",
          "latitude": 40.72868,
          "longitude": -73.98976
        }
      ]
    },
    "evidence": {
      "source": "New York State Liquor Authority",
      "source_kind": "public",
      "retrieved_at": "2026-10-20T00:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-20T00:00:00.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


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