A directory reconciliation job can return a plausible organization name and still match the wrong entity. Names, alternate names and practice locations are evidence about a candidate; the NPI is the registry identifier. A useful workflow preserves that distinction instead of replacing a local record with the first search result.
The NPI Registry lookup Actor performs bounded queries against the official NPPES registry API. Its purpose here is public directory data reconciliation. A returned record is not a credentialing decision or a clinical recommendation.
Search for candidates with a bounded query
The installed prefill searches an organization-name prefix within a state. The trailing wildcard is allowed only after a sufficiently long prefix. Keep the requested name and state with the response so a reviewer can see what relationship was actually tested.
{
"lookups": [
{
"organizationName": "Mount Sinai*",
"state": "NY"
}
],
"maxResultsPerQuery": 1
}
Each lookup must use either an exact ten-digit number alone, or an organization name together with a state. Do not combine both routes in one lookup object. The contract permits one through twenty lookup objects and a result limit of one through twenty per query.
Keep basic names and aliases separate
The output includes provider identity, enumeration type, addresses, taxonomies, registry update information and matchBasis. Preserve the basic organization name separately from other names. An alias match should remain an alias match even when it is a strong lead for a person reviewing the directory.
The historical README describes a Mount Sinai query that matched through another name rather than the basic organization name. That is a useful example of why a single display-name field is insufficient. It is historical acceptance evidence, not a claim about the registry's current contents.
Do not infer the total search population
The runtime makes one bounded request per lookup and does not paginate the registry. A name search that reaches maxResultsPerQuery produces a partial notice because the full match count remains unknown. A limit of one therefore means at most one returned candidate, not that only one candidate exists.
Route that notice into the review queue alongside the complete candidates. An exact record can be useful even when the surrounding candidate search is incomplete. Your workflow should retain both the candidate and the query coverage status instead of requiring a misleading all-or-nothing label.
Propose changes before applying them
Build a reconciliation table with the local record ID, requested query, NPI, match basis, relevant names, selected address evidence and registry update date. Let a reviewer accept or reject a proposed relationship. An accepted relationship can then become a separately recorded mapping in the directory.
Avoid automatically merging records merely because their names normalize to the same string. Organizational relationships and locations can change, and a public address is not necessarily the location your own application intended to represent. Keep the original local record available for comparison.
Make the operational outcome inspectable
Separate no match, source failure, capped search and accepted candidate mapping. Each state answers a different question. A no-match response says what this query returned at this time; it does not prove that an organization lacks an identifier under another name.
The practical benefit is a review queue that contains enough evidence to make a decision. It keeps registry identity precise while allowing name and address evidence to remain uncertain until someone resolves the relationship.
Cost and verification scope
The current FREE-tier result price is $0.002 for the documented unit: One NPPES provider record with NPI, addresses and taxonomies. The listing also has a $0.003 start event, charged per GB of Actor memory with a minimum of one event. A free diagnostic row does not refund that start event. Discounted platform tiers have their own rates; inspect your applicable tier before estimating a batch. These are listing prices read on 21 October 2026, not a receipt or a claim about customer spending.
The contract for this draft was checked against installed build 0.1.3 (50FARaFyDZNhiRQjf). The input above is an illustrative schema example, not a newly executed run. Current source responses and useful output still need inspection when you choose to run it. No new cloud build or run was made to prepare this article.
Open the Actor and inspect its input and pricing.
AI-assisted draft; publication requires independent technical review.
Top comments (0)