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

# Health Provider Registration (organisation)

> Look up a US health care organisation by provider number, or by name and state.

Look up US health care organisations (clinics, hospitals, pharmacies and suppliers) in the national provider register. Give a 10-digit NPI, or organization\_name and state with an optional city, never both. Names match a prefix: a trailing \* is appended when absent, with at least two characters before it. Returns registered names, active status, organisational subpart status, registration and update dates, specialties with primary flags and licence details, practice and mailing addresses, and the authorised official name and title. The official telephone is omitted. The registry refreshes daily; judge each record by last\_updated\_on. Registration is not a licence check or proof of current practice at the address. Use person\_health\_provider for individual practitioners. total is the number returned, at most limit; no match completes with providers: \[].

## Authentication

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

## Request Body

**npi** `string`

The organisation provider number. Give this, or organization\_name and state, never both. A health provider number is exactly 10 digits.

**organization\_name** `string`

Organisation name prefix. Needs state; a trailing \* is appended when absent. 2 to 100 characters. Give at least two characters before an optional trailing \*.

**state** `string`

US state code. Needs organization\_name. A state is two capital letters, such as MN.

**city** `string`

A city, to narrow a name search. An optional trailing \* needs at least two preceding characters. 1 to 100 characters.

**limit** `integer`

Most providers to return. From 1 to 20. Defaults to `5`.

<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 `company_health_provider`

**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 `US Centers for Medicare & Medicaid Services`.

**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`

When the source says the fact was last updated, or `null` when the source gives no date

## Result

Nested under `data.result`.

**data.result.total** `number`

Number of providers returned.

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

Providers.

**data.result.providers\[].npi** `string`

The 10-digit provider number.

**data.result.providers\[].organization\_name** `string`

Organization name. `null` when the source gives no value.

**data.result.providers\[].other\_names** `string[]`

Other names.

**data.result.providers\[].subpart** `boolean`

True when registered as an organisational subpart.

**data.result.providers\[].active** `boolean`

True when the registration is active.

**data.result.providers\[].registered\_on** `string`

Date the 10-digit number was issued, YYYY-MM-DD. `null` when the source gives no value.

**data.result.providers\[].last\_updated\_on** `string`

Date the registry last updated the record, YYYY-MM-DD. `null` when the source gives no value.

**data.result.providers\[].specialties** `object[]`

Specialties.

**data.result.providers\[].specialties\[].code** `string`

Taxonomy code. `null` when the source gives no value.

**data.result.providers\[].specialties\[].description** `string`

Description. `null` when the source gives no value.

**data.result.providers\[].specialties\[].primary** `boolean`

Primary.

**data.result.providers\[].specialties\[].license\_state** `string`

License state. `null` when the source gives no value.

**data.result.providers\[].specialties\[].license\_number** `string`

License number. `null` when the source gives no value.

**data.result.providers\[].practice\_address** `object`

Where they practise, as registered. `null` when the source gives no value.

**data.result.providers\[].practice\_address.street** `string`

Street. `null` when the source gives no value.

**data.result.providers\[].practice\_address.city** `string`

City. `null` when the source gives no value.

**data.result.providers\[].practice\_address.state** `string`

State. `null` when the source gives no value.

**data.result.providers\[].practice\_address.postal\_code** `string`

Postal code. `null` when the source gives no value.

**data.result.providers\[].practice\_address.phone** `string`

Phone. `null` when the source gives no value.

**data.result.providers\[].mailing\_address** `object`

Where they receive mail, as registered. `null` when the source gives no value.

**data.result.providers\[].mailing\_address.street** `string`

Street. `null` when the source gives no value.

**data.result.providers\[].mailing\_address.city** `string`

City. `null` when the source gives no value.

**data.result.providers\[].mailing\_address.state** `string`

State. `null` when the source gives no value.

**data.result.providers\[].mailing\_address.postal\_code** `string`

Postal code. `null` when the source gives no value.

**data.result.providers\[].mailing\_address.phone** `string`

Phone. `null` when the source gives no value.

**data.result.providers\[].authorized\_official** `object`

Authorized official.

**data.result.providers\[].authorized\_official.name** `string`

Name. `null` when the source gives no value.

**data.result.providers\[].authorized\_official.title** `string`

Title. `null` when the source gives no value.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/company-health-provider \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "npi": "1881018208"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/company-health-provider", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "npi": "1881018208"
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/company-health-provider', {
  npi: '1881018208'
});
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": "company_health_provider",
    "result": {
      "total": 1,
      "providers": [
        {
          "npi": "1881018208",
          "organization_name": "MAYO CLINIC",
          "other_names": [],
          "active": true,
          "subpart": false,
          "registered_on": "2014-02-05",
          "last_updated_on": "2021-04-12",
          "specialties": [
            {
              "code": "261QM1300X",
              "description": "Clinic/Center, Multi-Specialty",
              "primary": true,
              "license_state": null,
              "license_number": null
            }
          ],
          "practice_address": {
            "street": "200 1ST ST SW",
            "city": "ROCHESTER",
            "state": "MN",
            "postal_code": "55905-0001",
            "phone": "507-284-2511"
          },
          "mailing_address": {
            "street": "200 1ST ST SW",
            "city": "ROCHESTER",
            "state": "MN",
            "postal_code": "55905-0001",
            "phone": "507-284-2511"
          },
          "authorized_official": {
            "name": "Mr. DENNIS DAHLEN",
            "title": "Chief Financial Officer"
          }
        }
      ]
    },
    "evidence": {
      "source": "US Centers for Medicare & Medicaid Services",
      "source_kind": "public",
      "retrieved_at": "2026-01-15T12:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-01-15T12:00:00.000Z"
        }
      ],
      "as_of": "2021-04-12"
    }
  }
}
```

> [!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.