NPI Registry Healthcare Provider Lookup API
Pricing
from $1.40 / 1,000 providers
NPI Registry Healthcare Provider Lookup API
Look up public NPI provider records by number or organization name and state, with alias match evidence, registry addresses, taxonomies and clear limits.
Pricing
from $1.40 / 1,000 providers
Rating
0.0
(0)
Developer
Tim Zinin
Maintained by CommunityActor stats
0
Bookmarked
2
Total users
1
Monthly active users
2 days ago
Last modified
Categories
Share
Look up public NPI provider records and preserve name-match evidence, registry addresses and taxonomy fields for directory review and data reconciliation.
Evidence status: private build accepted on 2026-09-05. Every input/output example below is an exact dataset row exported from the accepted private acceptance runs on Apify's network, and the tariff in R4 was read back from the listing's pay-per-event configuration after those runs. This page still makes no claim that a scheduled task, a public review history or any credentialing workflow exists.
R1. What you get
This Actor performs bounded lookups against the official NPPES NPI Registry API v2.1. You can supply an exact ten-digit NPI, or an organization name together with a state. It returns selected public provider fields with source provenance and an explicit description of how the visible name matched the query. One complete unique record delivered in a run is a provider for this product's result pricing.
The output includes the NPI, enumeration type, organization or provider name, other names, practice and mailing addresses, taxonomies, registry last-updated date and matchBasis. The Actor keeps a legal/basic organization name separate from aliases. A query for Mount Sinai can return a provider whose basic name is COSMETIC CLINIC DERMATOLOGY and whose other name is MOUNT SINAI SCHOOL OF MEDICINE. That is recorded as alias evidence, not a false exact basic-name match.
A name search returns candidates for review. It does not confirm that the first candidate is the organization in your own database. The NPI is the exact source identity; matching a name or prefix is a separate relationship. Keep both pieces of information when reconciling records. An analyst can then compare the address and taxonomy against the intended entity without losing the fact that the initial retrieval came through an alias.
Free status rows explain zero results, duplicate providers, non-active source records, source/query errors and limits. A clean negative means a successful API response explicitly reported zero matches for that query. HTTP 200 with an Errors object is an error, not a clean negative. A name query that returns its configured result limit receives a free partial notice because the total number of matching providers remains unknown.
This is a small-query product: at most twenty lookups and twenty provider candidates per lookup, for no more than four hundred candidates before deduplication. It does not paginate, mirror NPPES, enumerate an entire state or enrich records from unrelated websites. Issuance of an NPI does not itself establish licensing, credentials, participation, current availability or suitability for a medical service. Those conclusions are outside this lookup contract.
R2. Who uses it
Directory operators can reconcile an existing organization record with public registry evidence. An exact NPI lookup checks the corresponding registry record. A name-and-state lookup supplies a bounded candidate list when an identifier is missing. The operator can compare names, address purposes and taxonomy fields, then record a reviewed mapping in the directory. The Actor does not automatically merge two organizations merely because their names overlap.
Healthcare data teams can normalize public provider records before importing them into a master-data system. They can keep the NPI as a string identity, preserve aliases separately and attach the source's lastUpdated and retrieval checkedAt. That structure supports repeatable reviews and correction handling. It does not turn the registry's reported details into verified real-time facts about a clinic's operations.
CRM administrators can enrich an existing organization account with a reviewed public identifier and registry fields. The useful step is controlled reconciliation of a known account, not indiscriminate collection of every provider in a region. A name query can match an alias or a larger organization with related wording. The administrator should retain the match basis and human review outcome rather than overwriting the account name with the first source result.
Analysts can investigate a small set of public organizational records using exact identifiers or narrowly scoped name queries. They can inspect taxonomy descriptions and public practice addresses while preserving source evidence. The Actor supplies no patient records, appointment data, private credentials, private contact database or identity resolution outside the public registry. It also does not contact providers or write back to NPPES.
This product is unsuitable for credentialing decisions, license verification, exclusion screening, payer-network eligibility or a full provider census. A field labelled license inside a taxonomy entry is source-reported text, not proof that a licensing authority confirmed current standing. Use the appropriate authoritative verification process for those purposes and keep its evidence separate from this registry lookup.
R3. How to run
Start with the prefilled lookup {"organizationName":"Mount Sinai*","state":"NY"} and maxResultsPerQuery 1. Run the Actor, wait for a terminal status, then inspect the provider row, any partial notice and the OUTPUT summary. The default is deliberately small and shows why aliases matter. A partial notice at limit one is expected when the source returns one candidate; it does not mean the complete provider row is damaged.
For an exact identifier, use a lookup object containing only number. A ten-digit string is the clearest representation, for example {"number":"1689838047"}. Do not combine number with organizationName or state in the same lookup: the two selection modes are exclusive. If your workflow already has the exact NPI, the numeric identity mode avoids ambiguity from a broad name search.
For an organization search, provide organizationName and state together. A trailing asterisk permits a prefix search after at least two letters or digits. The name is limited to 120 characters and a documented punctuation subset. The state is a two-letter code, normalized to uppercase. The Actor does not accept a state-only query, an arbitrary query string or skip/offset controls.
To review more candidates, increase maxResultsPerQuery up to twenty. This is one source request with a larger limit, not a command to page through the entire registry. If the response reaches that limit, the Actor still marks possible truncation. Refine the name and state if a candidate list remains too broad. A larger list can improve review context, but it does not by itself establish which candidate is your intended entity.
Download JSON when inspecting otherNames, addresses and taxonomies. The table view provides at least ten useful columns for identity, evidence and status, but nested fields are easier to understand as JSON. If importing CSV into a spreadsheet, keep NPI and postal codes as text and preserve the queryIndex and sourceUrl. Those fields help a reviewer trace a candidate back to the query that produced it.
R4. Pricing
Pricing: $0.003 per start plus $0.002 per complete provider. This is the listing's configured pay-per-event tariff, read back after the accepted private runs on 2026-09-05: the start event is apify-actor-start and the result event is result-found; no other event is priced. One provider means one complete unique NPI record delivered within the run, including its selected nested registry fields. The number of addresses, aliases or taxonomy entries does not multiply the result event.
At this rate, one provider costs $0.005 including a start, ten providers cost $0.023, twenty cost $0.043 and four hundred cost $0.803. These examples assume the configured 256 MB run and the platform's minimum start-event count of one. The start event is charged once per gigabyte of run memory: the default 256 MB run counts as one start unit ($0.003), while a run launched with 4 GB counts as four ($0.012). This was observed in the acceptance runs, which were deliberately launched at 4 GB and recorded four start events each. Account-specific platform costs or taxes belong to the actual bill rather than these simple event examples.
Zero-result rows, duplicate notices, non-active-record notices, source errors, invalid-input explanations and partial notices are free of result-found. The automatic start event can still apply to a run that finds no provider. If two different queries return the same NPI, the first complete delivery is the paid provider row and a later match becomes a free duplicate notice linking to the first query. Deduplication is across the whole run, not just within each lookup.
A new run can retrieve and bill the same NPI again. There is no persistent replay ledger or free change-detection cache. A repeated lookup can be useful for refreshing source fields, but its value depends on your workflow and the registry's update cadence. Store the last retrieval and source update date in your own system, and choose a refresh policy deliberately rather than assuming unchanged rows will be free.
The buyer's charge cap is checked before each paid delivery, inside the same lock as the linked dataset-and-charge call. If another provider does not fit, paid work stops. A provider that fits exactly remains counted as delivered and paid when the SDK signals the limit has been reached. A budget stop is separate from a source zero-result response and must not be interpreted as evidence that no further providers existed.
Uncertain pricing or money state causes a failed run. Missing result pricing on the platform, unreadable pricing or priced automatic dataset writes are rejected before a paid explanation can occur. A later budget-read error also fails the run. If a linked write/charge throws, the provider may already have reached the dataset, so the Actor stops without retrying that row and records deliveryUncertain for reconciliation against the actual dataset and platform events.
R5. Input contract
The input has two supported top-level fields: lookups and maxResultsPerQuery. It must be a JSON object. The runtime rejects unknown fields and validates the total query-by-result product before source work. There is no hidden pagination option, concurrency override, source URL field or checkbox that disables evidence checks.
| Field | Prefill/default | Runtime bounds | Effect |
|---|---|---|---|
| lookups | [{"organizationName":"Mount Sinai*","state":"NY"}] | 1–20 query objects | Explicit number or organization-name/state selection |
| maxResultsPerQuery | 1 | Integer 1–20 | Shared per-query source limit; total candidates at most 400 |
Each lookup uses exactly one of these shapes:
Both selector shapes are valid; the organization-name shape is the one exercised by the accepted runs, and the exact-NPI shape is covered by unit tests against a saved live response. The runtime also accepts a ten-digit integer for number and normalizes it to a string. A string is preferable for identifiers because downstream systems should not perform arithmetic on NPIs. Whitespace, extra fields, an alphabetic number or a combined number-and-name object is rejected rather than silently reinterpreted.
The organization name must contain at least two letters or digits and can include spaces plus the accepted punctuation characters: ampersand, at sign, apostrophe, quotation mark, colon, comma, slash, parentheses, period, pound sign, semicolon and hyphen. An optional asterisk is allowed only at the end. It is not a regular expression. Leading or trailing whitespace is rejected so the query's meaning is visible in the saved input.
The state field is required for name mode to keep the lookup narrow. It must have two letters and is uppercased. A two-letter shape does not prove the source recognizes the code. If the API rejects a state or another criterion, the Actor records the API error with a nonempty reason. It does not turn the rejected query into a statement that no provider matched.
The upstream API v2.1 supports larger limits and skip values, but this Actor intentionally sends limit 1–20 and skip=0. Its current page was checked during the build and states limit at most 200 and skip at most 1000. Those upstream maxima do not expand this product's input contract. The Actor performs one sequential query per lookup, with bounded transient retries, and never uses a second lookahead request to guess total matches.
When a name response returns exactly maxResultsPerQuery candidates, matchLimitReached is true on a free partial notice and hasMore is null. That means the response reached the chosen boundary; it does not prove a particular number of additional matches. The default Mount Sinai query was separately observed to have at least two results on the build date, but runtime notices remain conservative because another name query may have exactly one total match.
An exact NPI lookup returning one matching provider does not trigger the name-search truncation rule. The identity itself is the selection key. If the source returns a different NPI for an exact query, the row is rejected as an identity error. If it returns zero, the Actor records clean absence only when the result_count/results envelope is valid. Malformed or inconsistent envelopes remain source errors.
R6. Happy, partial and failure output
The examples below are exact dataset rows exported from the accepted private acceptance runs on 2026-09-05, executed on Apify's network with the pay-per-event tariff active. Only checkedAt will differ in your own run; the registry values are the source's public record at that time. No sample patient records or private credentials are included.
Example A — organization alias evidence (accepted run: one result-found event charged, plus the free partial notice shown further below).
The basic organization name and matchedOtherName intentionally differ. matchBasis=other_name_prefix describes the visible prefix correspondence in the alias array. It is not a claim that the source confirmed the user's intended organization, and it does not rename the provider to the query text. The old lastUpdated is the registry's source value; a fresh checkedAt does not make that source update recent.
Example B — zero-result query (accepted run: zero result-found events charged).
queryIndex is zero because the query was the only lookup in that run; with several lookups it counts positions in the zero-based input array. found=false, resultCount=0 and error="" are all present explicitly. Their presence matters: an absent error property is not the same tested contract as a known empty error. The source confirmed result_count=0 for this query in the accepted run; a network failure would require a different status and a nonempty error.
Example C — exact NPI selector (contract shape; the accepted runs used name mode, and this path is covered by unit tests against a saved live response).
A complete matching record uses matchBasis=exact_npi, with the same NPI identity and current public fields from that run. The Actor does not add a partial notice merely because the one exact record fills a limit of one. Repeating this selector later can bill the record again, so an integration should distinguish a new source retrieval from a duplicate webhook or import attempt.
Partial notice (accepted run, second row of Example A; free). The Mount Sinai query in Example A also produced:
This row is free and describes the candidate set. It does not reduce the completeness of the provider row already delivered. hasMore=null means unknown, not false and not a hidden total count. A consumer should refine a query or increase the bounded limit when it needs more review context, while preserving the fact that the previous selection reached its boundary.
Failure contract (not triggered in the accepted runs because the source answered cleanly). A separate direct API probe with number=abc returned HTTP 200 and an Errors array describing an invalid NPI length. The Actor's own input validation refuses abc before making that query, while its source-processing tests independently exercise the Errors response path. An Errors payload becomes status=source_error with a nonempty NPPES Errors reason. It must never pass the clean-negative golden.
R7. Field dictionary
Content and free notices share a common envelope. Provider-specific nested fields are emitted only when supported by the source row. A negative row does not fabricate an organization name or an empty address to make a table look uniform. Branch on found and status first, then read the relevant content fields.
| Field | Type | Meaning and consumer handling |
|---|---|---|
| input | Query object or null | Effective normalized lookup, or null for a run-level notice |
| queryIndex | Integer on query rows | Zero-based input lookup position |
| sourceUrl | String | Exact API request URL or API base for a run notice |
| found | Boolean | True for a complete provider delivered as content |
| status | String | ok, not_found, duplicate, inactive, source_error, input_error or partial |
| resultCount | Integer | One for a complete provider, zero for a free status row |
| partial | Boolean | Incomplete query or run coverage, normally on a notice |
| error | String | Empty for clean absence/duplicates/limits, nonempty for errors |
| warnings | Array of strings | Candidate interpretation and scope explanations |
| checkedAt | ISO UTC string | Retrieval/processing timestamp, not source last update |
| schemaVersion | String | Current row contract version, 1.0 |
| npi | Ten-digit string | Exact public source identity and per-run deduplication key |
| enumerationType | String | NPI-1 for an individual or NPI-2 for an organization |
| organizationName | String or null | Basic organization name; null is normal for an individual |
| providerName | String | Organization name or composed public individual name |
| otherNames | Array of objects | Selected source alias fields with source codes/types |
| practiceAddress | Object or null | Address selected by address_purpose=LOCATION |
| mailingAddress | Object or null | Address selected by address_purpose=MAILING |
| taxonomies | Array of objects | Source code, description, primary flag and other selected fields |
| lastUpdated | Date string | Source basic.last_updated, retained without freshness invention |
| matchBasis | String | Observable identity/name correspondence category |
| matchedOtherName | String or null | Alias that visibly matched the organization query |
| firstQueryIndex | Integer on duplicate notice | Query that first delivered this NPI in the run |
| sourceResultCount | Integer on negative | Explicit upstream zero count |
| matchLimitReached | Boolean on query notice | Returned candidates reached the configured name-query limit |
| hasMore | Null on query notice | Total unseen matches are not known |
matchBasis can be exact_npi, organization_name_exact, organization_name_prefix, other_name_exact, other_name_prefix or upstream_name_search. Exact/prefix name labels describe comparison of the visible strings after case normalization. upstream_name_search means the API returned a candidate but the Actor cannot demonstrate one of its simple visible name correspondences. None of these values is a probabilistic confidence score or a license/identity verification outcome.
otherNames preserves public alias details such as organization_name, code and type. For an individual exact-NPI lookup, available first_name, middle_name and last_name alias fields can be retained instead. Missing alias fields are not filled from the query. Keep alias type and the basic name separate; a doing-business-as name, a former name and the current basic name can have different meanings in your directory workflow.
The address objects retain selected public address fields, including address lines, city, state, postal code, country and purpose, plus office telephone/fax when the source supplies them. The Actor selects by address_purpose rather than trusting array position. During the local source probe, mailing appeared before location, so positional assumptions would have reversed the two addresses. A consumer should also preserve purpose if it flattens these objects.
Taxonomy entries can include code, desc, primary, state, license and taxonomy_group. Keep code as text and primary as a boolean when present. The source-reported license field is not a live verification from a licensing board. A null or empty license value is not proof that a provider lacks a license, and a nonempty value is not proof of current good standing. Those are separate evidentiary questions.
The OUTPUT record reports requested, processed and unprocessed lookups, providersReceived, duplicateProviders and providersWithheld. received counts candidates from valid response envelopes before per-run deduplication. It does not mean every candidate was sold as a complete provider. delivered/paid count confirmed complete rows and result events, free counts status rows, and failed counts free rows carrying errors. partial and fatal describe overall coverage and failure separately.
A deliveryUncertain count means a linked write/charge outcome could not be confirmed. The run fails in that case, even if valid rows already exist. Compare the actual dataset and platform chargedEventCounts during reconciliation. replaySafe=false makes the cross-run limitation explicit: another run may retrieve and bill the same NPI again. Your importer can be idempotent without implying that source retrieval itself is free.
R8. Evidence and boundaries
The source is the official read-only NPPES API v2.1. The API page is delivered as a client application, so the build fetched its current referenced JavaScript module and read the actual API-page content rather than treating an empty web-reader response as the documentation. The page confirmed current API version and pagination bounds, and explained that organization-name searches include other names. The Actor's narrower limits remain independent of those upstream maxima.
The permission basis is the official public query interface and CMS's dissemination of FOIA-disclosable registry data. The Actor requests only bounded public records through that interface. It does not download the full replacement file, query private clinical systems, infer patient information or collect source credentials. Public provider fields still deserve purposeful handling in your downstream system; public availability does not make every possible redistribution or outreach workflow appropriate.
A returned registry record contains information reported to NPPES. lastUpdated describes the source's update field and can be old even when the record remains available. checkedAt records when this Actor retrieved the record. The Actor does not certify that an address is occupied today, that a phone number is reachable or that an organization is taking new patients. Preserve those limits when using registry fields in a customer-facing directory.
A matching name is not the same as a matching entity. Organization searches can find legal names, business names, former names and other names. A query result can therefore look surprising while still following the source's documented matching behavior. The Actor exposes the visible match evidence and leaves uncertain cases as upstream_name_search rather than inventing an exact-name assertion or a fuzzy confidence number.
A complete provider row must have a valid NPI, supported enumeration type, required name, valid source last-updated date and properly shaped public arrays. Exact-NPI queries additionally require the returned NPI to equal the requested one. Optional missing address purposes or measurements are not fabricated. A malformed response body, inconsistent result count or oversized body is an error, and incomplete source content is not sold as a complete provider.
The source's general registry interface includes a notice about hourly query restrictions, but the build did not establish a numeric API requests-per-hour allowance. This Actor uses its own conservative one-request-per-second maximum and twenty-query run cap. Those are product limits, not a claim of an official quota. Your overall schedule and concurrent independent runs must still respect the source's current access rules.
R9. Decision routing
| Outcome | Route | Interpretation |
|---|---|---|
| found=true and exact_npi | Identifier reconciliation | Source record corresponds to the requested NPI |
| found=true and a name/alias match | Candidate review | Visible name correspondence, intended entity still needs review |
| found=true and upstream_name_search | Manual evidence review | Source returned a candidate without a simple demonstrated name match |
| status=not_found and error empty | No-match log | Successful query explicitly returned zero candidates |
| status=duplicate | Query-to-provider link | NPI was already delivered by another query in this run |
| status=inactive | Restricted status handling | Source is non-active; full provider details were not emitted |
| status=partial | Query/run coverage review | Limit reached or work incomplete; unseen total unknown |
| status=source_error | Input/source incident queue | Query failed or source shape was invalid; absence not established |
| OUTPUT.fatal nonempty | Failed-run reconciliation | Money, delivery, input or all-content source failure |
For a directory merge, compare the NPI, basic name, alias evidence and address purpose with your existing record. If they disagree, preserve both records and route the mapping for review. Do not overwrite the directory's verified legal name simply because a search returned an alias. The Actor provides structured source evidence; your organization defines the authority and review rules for a merge.
For a clean zero result, retain the effective query and retrieval time. No match under one spelling, prefix and state is narrower than “this provider does not exist.” A provider may have a different basic name, an alias, another address association or a source update you have not accounted for. A refined query can be useful, but an automated broadening loop should remain bounded and should not turn this tool into a full-state enumeration process.
For duplicate rows, join npi to the provider content from firstQueryIndex. The duplicate notice preserves the fact that another query matched the same source identity without charging for another provider row. This is particularly useful when a directory has both a legal-name and a business-name record. Keep the two input references even if the source identity is shared; deciding whether to merge the local records is a separate step.
For partial queries, treat the candidate set as limited. hasMore=null is intentional. If your application requires exhaustive candidate review, refine the query or choose another approved data process. Do not translate null into false in a frontend boolean conversion. That would turn an unknown total into a misleading claim that no additional provider could match.
R10. Commercial playbooks
Directory identifier repair. A directory team selects a small queue of organization records missing NPIs. It queries the known name and state, reviews candidates and records a human-approved NPI mapping. The team stores basic name, alias evidence, source address and checkedAt beside the mapping. A successful query closes the retrieval task; the separate review outcome determines whether the directory record can be changed.
Begin with a narrow candidate limit and increase it only when review needs more context. If an alias matches, keep that alias as evidence rather than replacing the basic organization name. If the query reaches its limit, document that coverage before concluding that the best-looking candidate is the only candidate. A small queue with explicit review is more reproducible than a broad query whose first row is automatically accepted.
CRM account enrichment. An administrator starts from existing healthcare organization accounts with a known state. The Actor supplies public candidate records; the administrator approves an NPI and selected registry fields for each account. Office contact fields, if present, remain source-reported directory information. The workflow does not automatically send messages, infer consent or treat a public number as a verified sales contact.
Keep the destination account's own identifier and the source NPI in separate columns. Preserve a mapping table with who reviewed the association, when it was reviewed and the evidence used. On a later refresh, compare source changes before overwriting manually curated fields. A changed mailing address need not imply that the practice location moved, and a new alias need not imply that the underlying organization is a new customer account.
Registry snapshot comparison. A data-quality team periodically refreshes exact NPIs already present in its system. It compares selected fields and the source lastUpdated date, retaining an immutable snapshot or a documented latest-value table. This can reveal differences that deserve investigation. It does not prove that the source update is correct or that every real-world change was reported to the registry promptly.
For all three workflows, budget by starts and unique delivered providers rather than by raw dataset row count. A default name query can produce one provider plus a free partial notice, and overlapping queries can produce duplicate notices. Review actual result events after the canary before scaling the workload. The Actor makes no revenue, conversion or coverage guarantee for a directory or CRM process built on top of these records.
R11. Integration recipes
SQL provider table. Use npi as a ten-character string primary key for a latest-source table. Keep enumerationType, organizationName, providerName, lastUpdated and checkedAt as distinct fields. Preserve nested otherNames, addresses and taxonomies as JSON or normalized child tables. Store the external Apify run ID and the effective input in a batch table so each imported snapshot can be traced back to the retrieval that produced it.
A separate query-results table should record run ID, queryIndex, npi, status and matchBasis. This preserves many-to-one relationships when several local search queries find the same provider. A duplicate notice can link to the first content row by npi and firstQueryIndex. Do not require every status row to have an NPI: clean zero-result and source-error rows may identify only the query.
Workflow engine import. Start the Actor with the exact JSON object, wait for terminal status, retrieve OUTPUT and then the dataset. Branch on fatal/partial before filtering content. Import found=true rows through an upsert operation and store the free status rows as operations evidence. Mark the batch imported only after the destination succeeds. A cloud run can be successful while a later spreadsheet or CRM write fails.
Handle completion webhooks idempotently. The webhook's run ID is a lookup key for the dataset, not an instruction to start another paid run. If the same notification arrives twice, use your batch ledger to avoid duplicate imports. Keep platform credentials in your integration's secret store and out of query objects, logs shared with reviewers and exported provider rows.
Python reconciliation. Parse the JSON export and group content by npi. Keep identifiers and postal codes as strings. Parse lastUpdated as a source date and checkedAt as a UTC timestamp, without filling one from the other. Compare basic organization name and aliases separately, and retain the source address purpose before applying any local normalization. A text-normalized match can assist review, but should not overwrite the Actor's original source values.
JavaScript review interface. Render source strings as text and never treat them as executable instructions. Show the basic organization name, matchedOtherName and matchBasis together so a reviewer can see why a candidate appeared. Display null or unknown totals explicitly in partial queries. A generic truthiness check on hasMore would collapse unknown into false and hide the candidate limit.
CSV and spreadsheets. Export an appropriate flat projection for human review, keeping the authoritative JSON alongside it. Use separate practice and mailing columns. Preserve NPI and postal codes as text, especially when leading zeros or fixed-width formatting matter. Proper CSV parsing is required for names containing commas or quotes. Apply your normal formula-injection protections before exposing source strings as spreadsheet cells.
CRM field mapping. Map source npi to a dedicated registry-ID field, not the CRM account's internal ID. Map basic organizationName to a source-name field until a reviewer approves any overwrite. Store aliases in a separate collection or note field with their source type. Keep a last-checked timestamp and a link to source provenance. This avoids silently converting a lookup candidate into a verified account identity.
Derived matching models. If a later pipeline computes similarity scores, store them as derived output with its own method/version and evidence. Do not rename them matchBasis or present them as CMS-provided confidence. Keep source records available for review and avoid sending unnecessary provider details to another service. This Actor itself performs deterministic visible-string checks and has no hidden language-model matching step.
R12. Operating guide
Maintain a small, explicit lookup queue. Use exact NPIs when you already know them and name/state queries when you need candidates. Do not use a wide prefix simply to maximize record counts. The source page directs bulk work toward its dedicated data dissemination process, while this Actor is designed for bounded queries. Increasing concurrent runs is not a substitute for an appropriate bulk-data plan.
Save the effective input and the platform build/version with every run. A repeat run with a changed name, state or candidate limit is not the same experiment as a refresh of an exact NPI. Keep a baseline accepted input for future regression checks. That makes a change in source behavior easier to separate from a local configuration mistake or an intentional code release.
Monitor the difference between requested lookups, providersReceived, delivered providers and free notices. A high duplicateProviders count can indicate that your queue contains multiple names for the same source identity. A high partial count can indicate that the selected limits are too narrow for your review task. A high source-error count requires inspection of the concrete error categories rather than a blanket conclusion that the registry has no data.
If the source returns 429 or temporary server failures, let the Actor's bounded retries complete. If this recurs across runs, reduce overall frequency and concurrency. The one-request-per-second per-run cap does not represent a confirmed hourly quota and does not coordinate other clients on the same network. An immediate external restart loop can repeatedly incur start charges while increasing source load.
If a query returns zero unexpectedly, verify spelling, state and the intended name basis. Organization search can include other names, but this Actor's matchEvidence only labels correspondences it can demonstrate in returned fields. Do not infer that a zero result means a provider lacks an NPI, is unlicensed or has ceased operations. Preserve the exact query so another reviewer can understand the scope of the negative observation.
If the API returns Errors with HTTP 200, inspect the field and description in error. A success HTTP status alone is insufficient for a green data result. The Actor validates the result_count/results envelope and treats malformed structures as source errors. Do not build an integration that checks only the HTTP transport status and then fills an empty provider record to satisfy a downstream schema.
If a source record is non-active, the Actor emits a free identity notice without full provider details. It does not recover historical names or addresses from another source. Do not treat this notice as a complete deactivation registry or as instructions for transaction eligibility. Any such decision requires the appropriate authoritative process and a separately defined scope.
When delivery is uncertain, reconcile before retrying. A linked SDK call writes before charging, so a thrown call can leave a provider in the dataset without confirmed billing acknowledgement. The Actor stops paid work and fails. Your importer should upsert by NPI and record the failed run state, while the operator compares dataset rows with platform charged events before deciding how to continue.
R13. FAQ
Does an NPI prove that a provider is licensed or credentialed? No. The current API page explicitly separates NPI issuance from licensing and credential validation. This product returns public registry evidence and selected fields. It does not query licensing boards, verify qualifications or establish that a provider is suitable for a particular service.
Why did my organization search return a different basic name? The source searches multiple organization-name types, including business and other names. The Actor preserves the basic name and records the visible alias correspondence separately. In the Mount Sinai example, other_name_prefix is the correct explanation; replacing the basic name with the query would lose important evidence.
Is the first result the best or only match? The Actor does not make that claim. It preserves the source's returned candidates within your selected limit. Reaching the limit produces partial with an unknown unseen total. Review names, addresses and taxonomies against your intended record before making an identity association.
Can I query only by state? No. Name mode requires an organization name and state together, or you can use an exact NPI. This keeps the scope bounded and avoids a state-wide extraction interface. The Actor also has no skip or pagination input, even though the upstream API supports broader pagination controls.
Can I use a wildcard anywhere in the name? Only one optional trailing asterisk is accepted, after at least two letters or digits. It is a prefix selector, not a regular expression. Internal or leading wildcards are rejected. Names must also meet the length and punctuation contract described above.
Can I look up an individual provider? An exact NPI can return NPI-1 records with their public provider name and selected registry fields. Organization-name search is for organizations. This Actor does not expose personal first/last-name search, authorized-official search or a private contact-enrichment mode.
Why are addresses selected by purpose? Array order can be unreliable for assigning meaning. The live source probe returned mailing before location, while the page's general description suggested another order. Matching address_purpose directly avoids reversing practice and mailing fields. A missing purpose remains null rather than borrowing the other address.
Does a phone number mean it was verified? No. A public office phone or fax field is passed through from the registry when supplied. The Actor does not call it, check ownership or confirm current reachability. Keep it labelled as source-reported directory information and apply your own rules to any downstream use.
Why is lastUpdated old in a fresh run? lastUpdated belongs to the source record, while checkedAt belongs to this retrieval. The Actor preserves both. A current API response can carry an old update date; it would be misleading to replace that date with today's time. Use the source date and your own review policy when deciding whether to investigate stale information.
Why did I get a partial row with maxResultsPerQuery=1? The name query returned its configured limit. Without another request or a total-count field, the Actor cannot prove whether unseen matches exist. It reports hasMore=null and matchLimitReached=true. The complete provider row remains complete and billable; the partial row is free set-level evidence.
Can a partial notice prove there are more providers? No. It proves the selected result boundary was reached. A specific query can be separately tested with a larger limit, as the build did for Mount Sinai, but the runtime contract remains conservative for all queries. Do not turn null into false or a guessed positive count.
Why did two queries produce one provider row? They returned the same NPI. The Actor deduplicates provider identity across the run and emits a free duplicate notice for the later query. Join that notice to the first provider row. This preserves query coverage without billing the same provider twice in one run.
Will a repeat run be free? No. Deduplication does not persist across runs. A new run can retrieve and bill the same NPI again, whether or not its source fields changed. Idempotent importing and cross-run change detection belong to your own integration and do not remove the cost of a new source retrieval.
What is the difference between not_found and source_error? not_found requires a valid successful response with result_count zero and an empty results array. source_error means the query or response failed, including an Errors object inside HTTP 200. The latter does not establish absence and must not satisfy a clean-negative acceptance check.
Can a run with no provider still cost money? Yes. The automatic start event can be charged even when no result-found event occurs. The tariff separates starts from complete providers: the accepted zero-result run charged start events and no result event. Check your account bill for the exact start charge, which scales with the memory you select for the run.
Is this a complete mirror of NPPES? No. It performs at most twenty bounded queries, each returning at most twenty candidates, with skip fixed at zero. It does not download dissemination files or traverse an entire registry. Use a separately planned bulk-data process when complete coverage is the requirement.
How should I report a defect? Provide the run ID, effective input, terminal status, relevant OUTPUT fields and a redacted example through the platform issue channel when available. Exclude tokens and unnecessary personal details. A concrete NPI, queryIndex and error category make a problem reproducible without sharing an entire unrelated directory export.
R14. Sources and rights
The NPPES API page documents the read-only v2.1 interface and name-query behavior. The CMS data dissemination page describes public access to FOIA-disclosable registry data. This Actor uses that public query scope and retains source provenance. It does not claim access to private clinical records or authority to change source data.
CMS, NPPES and NPI identify the source system and identifier standard. This is an independent lookup tool with no implied endorsement, certification or official credentialing status. A downstream directory, CRM mapping or analysis remains the consumer's own product and decision process. Review current source notices and your organization's handling requirements for the intended use, especially when redistributing public provider information.
The evidence has three layers: local source and logic checks (a genuine alias result, a zero-result query and a separate API Errors control), the accepted private runs of 2026-09-05 on Apify's network whose rows appear in R6, and the tariff read back from the listing. This page claims no public scheduled task and no review history.
Related tools
Related tools for adjacent workflows in healthcare and regulatory monitoring, official open-data APIs.
| Actor | What it does |
|---|---|
| Clinical Trials Monitor | Pair it in the healthcare and regulatory monitoring workflow: Retrieve up to 100 ClinicalTrials.gov studies for up to 25 condition, drug, or sponsor queries |
| FDA Approval Feed | Pair it in the healthcare and regulatory monitoring workflow: Collect bounded openFDA approval and recall observations by drug or company |
| Patent Evidence Normalizer | Pair it in the healthcare and regulatory monitoring workflow: Normalize buyer-owned, rights-holder-authorized, PatentsView CC BY 4.0, or licensed patent exports into... |
| Gov Tender Radar | Pair it in the official open-data APIs workflow: Search official TED procurement notices by keyword, CPV query, or buyer country |
| Sanctions Screening API | Pair it in the official open-data APIs workflow: Screen up to 100 names against fresh official OFAC SDN primary and alias files plus the EU consolidated... |
