Skip to content
Hermes Health API
GuidesOpenAPI spec

Endpoints

Site finder

POST/v0/site-finder

Start a site-finder job

Start a site-finder job to resolve a site by name, address, and optional identifiers.

Runs the site resolution pipeline (geocoding, embedding search, AI matching) in the background and returns a jobId. Poll GET /v0/site-finder/jobs/<job_id> until status is completed or failed to retrieve the result.

Request bodyapplication/json

  • namestring

    Name of the facility or provider to find, as the caller knows it. A provider's name is resolved to the facility they practice at when possible.

  • addressLine1string

    First street address line of the site.

Optional parameters

  • addressLine2string

    Optional secondary address line — suite/unit/apt, or for Puerto Rico addresses the `URB <name>` urbanization line per USPS Publication 28.

  • citystring

    City of the site. May be omitted or null.

  • statestring

    Two-letter US state code of the site. May be omitted or null.

  • zipstring

    ZIP code of the site. May be omitted or null.

  • latitudenumber

    Latitude of the site in decimal degrees. Optional: the submitted address is geocoded, and these coordinates are used only when that lookup finds nothing. Supply it together with `longitude`.

  • longitudenumber

    Longitude of the site in decimal degrees. Optional: the submitted address is geocoded, and these coordinates are used only when that lookup finds nothing. Supply it together with `latitude`.

  • npistring

    10-digit National Provider Identifier. When exactly one existing site carries this NPI, that site is returned without an address search.

  • ncpdpstring

    NCPDP Provider ID for pharmacy sites. Matched ahead of NPI in the shortcut pipeline because NCPDP uniquely identifies a dispensing location.

  • taxIdstring

    Federal tax identification number of the organization. Carried into the new-site proposal when no existing site matches.

  • isFacilityboolean

    Whether the name is a facility (true) or an individual provider (false). When omitted or null, it is inferred from the name.

  • recordsPhonestring

    Medical-records phone number. Informational: the site finder does not use it to match or to build a new-site proposal.

  • recordsFaxstring

    Medical-records fax number in E.164 format. Informational: the site finder does not use it to match or to build a new-site proposal.

  • recordsEmailstring

    Medical-records email address. Informational: the site finder does not use it to match or to build a new-site proposal.

  • billingPhonestring

    Billing-records phone number. Informational: the site finder does not use it to match or to build a new-site proposal.

  • billingFaxstring

    Billing-records fax number in E.164 format. Informational: the site finder does not use it to match or to build a new-site proposal.

  • billingEmailstring

    Billing-records email address. Informational: the site finder does not use it to match or to build a new-site proposal.

  • billingWebsitestring

    Website for billing-records requests. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingPhonestring

    Imaging-records phone number. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingFaxstring

    Imaging-records fax number in E.164 format. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingEmailstring

    Imaging-records email address. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingWebsitestring

    Website for imaging-records requests. Informational: the site finder does not use it to match or to build a new-site proposal.

  • phonestring

    Main phone number of the site. Carried into the new-site proposal when no existing site matches.

  • mainFaxstring

    Main fax number of the site in E.164 format. Informational: the site finder does not use it to match or to build a new-site proposal.

  • recordWebsitestring

    Website for records requests. Informational: the site finder does not use it to match or to build a new-site proposal.

  • ehrstring

    Name of the electronic health record system the site uses. Informational: the site finder does not use it to match or to build a new-site proposal.

  • systemNamestring

    Name of the health system the site belongs to. Carried into the new-site proposal when no existing site matches.

  • primarySpecialtystring

    Primary specialty of the site or provider, as free text. Carried into the new-site proposal when no existing site matches.

  • acceptsEsignatureboolean

    Whether the site accepts electronically signed authorizations. Carried into the new-site proposal when no existing site matches.

  • operationalStatusstring

    Operational status to stamp on a site created from this search's new-site proposal. Omit it for an operating site.

  • medicalRoistring

    Release-of-information vendor handling medical-records requests. With `authoritativeRoi` and `medicalRoiId`, it identifies an existing site directly.

  • billingRoistring

    Release-of-information vendor handling billing-records requests. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingRoistring

    Release-of-information vendor handling imaging-records requests. Informational: the site finder does not use it to match or to build a new-site proposal.

  • medicalRoiIdstring

    The medical-records vendor's own identifier for this site. With `authoritativeRoi` true and `medicalRoi` set, an existing site whose department carries this identifier is returned without an address search.

  • billingRoiIdstring

    The billing-records vendor's own identifier for this site. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingRoiIdstring

    The imaging-records vendor's own identifier for this site. Informational: the site finder does not use it to match or to build a new-site proposal.

  • medicalRecordsRequestMethodstring

    How medical-records requests are delivered to the site. Informational: the site finder does not use it to match or to build a new-site proposal.

  • billingRequestMethodstring

    How billing-records requests are delivered to the site. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingRequestMethodstring

    How imaging-records requests are delivered to the site. Informational: the site finder does not use it to match or to build a new-site proposal.

  • medicalRecordsAddressobject

    Mailing address for medical-records requests. Informational: the site finder does not use it to match or to build a new-site proposal.

  • billingAddressobject

    Mailing address for billing-records requests. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingAddressobject

    Mailing address for imaging-records requests. Informational: the site finder does not use it to match or to build a new-site proposal.

  • medicalRecordsMailFeestring

    Fee the site charges to mail medical records, as a decimal amount. Informational: the site finder does not use it to match or to build a new-site proposal.

  • billingMailFeestring

    Fee the site charges to mail billing records, as a decimal amount. Informational: the site finder does not use it to match or to build a new-site proposal.

  • imagingMailFeestring

    Fee the site charges to mail imaging records, as a decimal amount. Informational: the site finder does not use it to match or to build a new-site proposal.

  • authoritativeRoiboolean

    When true, `medicalRoiId` is treated as a stable unique identifier: an existing site carrying it is returned without an address search. Defaults to false.

  • dataSourcestring

    Free-text label for where the submitted site details came from. Informational: the site finder does not use it to match or to build a new-site proposal.

  • authoritativeboolean

    Whether the submitted identity fields should be trusted over the values already stored on a matching site. Informational for the site finder, which never updates sites. Defaults to false.

  • autoResearchboolean

    Accepted but ignored: the site finder never starts background research on the site it finds.

  • npiEnumerationDatestring

    Date the NPI was first issued (YYYY-MM-DD). Informational: the site finder does not use it to match or to build a new-site proposal.

  • npiDeactivationReasonstring

    Reason code the NPI registry gives for deactivating the NPI, when it has been deactivated. Informational: the site finder does not use it to match or to build a new-site proposal.

  • npiDeactivationDatestring

    Date the NPI was deactivated (YYYY-MM-DD), when it has been. Informational: the site finder does not use it to match or to build a new-site proposal.

  • npiReactivationDatestring

    Date a deactivated NPI was reactivated (YYYY-MM-DD), when it has been. Informational: the site finder does not use it to match or to build a new-site proposal.

ReturnsSuccess

  • jobIdstring

    Identifier of the started job. Poll `GET /v0/site-finder/jobs/<job_id>` with it for the result.

Errors

400401429500

POST/v0/site-finder/embed-token

Mint a site-finder embed token

Mint an embed token for iframing the site-finder UI.

The token authorizes the interactive embed at GET /ui/site-finder/embed?token=...: anyone holding it can run finder searches, create sites from finder proposals, and trigger AI research, all attributed and billed to the minting user’s company. Tokens are stateless, sealed with authenticated encryption (encrypt-then-MAC, keyed apart from both the generic URL-query oracle and the auth-check embed tokens), and expire one hour after minting — mint a fresh token each time you render the page that hosts the iframe.

See Embedding the site finder for the full iframe integration guide.

Request bodyapplication/json

object

ReturnsSuccess

  • tokenstring

    The embed token: an opaque encrypted string to pass to the embed as its `token` query parameter. It grants access to what it was minted for until it expires, so mint a fresh one rather than storing it.

Errors

400401429500

GET/v0/site-finder/jobs/{job_id}

Retrieve a site-finder job

Fetch the status and result of a site-finder job started via POST /v0/site-finder.

Poll this endpoint until status is completed or failed. On completion, siteFinder contains the resolution result and siteFinderProposal contains a signed proposal to create a new site if no match was found.

Parameters

  • job_idstringpath, required

    The `jobId` returned when the job was started with `POST /v0/site-finder`.

ReturnsSuccess

  • idstring

    Identifier of the job, as returned by `POST /v0/site-finder`.

  • statusstring

    Where the job is in its lifecycle.

  • inputSummaryobject

    The name and address the job was started with.

  • inputSummary.namestring

    Facility or provider name the job was started with.

  • inputSummary.addressstring

    First street address line the job was started with.

  • createdAtstring

    When the job was started (RFC 3339, UTC).

Conditional attributes

  • externalIdstring

    The caller's own reference for the row, taken from the `id` column of a batch upload; absent for single lookups.

  • inputSummary.citystring

    City the job was started with; absent when none was given.

  • inputSummary.statestring

    State the job was started with; absent when none was given.

  • inputSummary.zipstring

    ZIP code the job was started with; absent when none was given.

  • siteFinderobject

    The search result: the matched site, other candidate matches, and nearby sites. Present only once `status` is `completed`.

  • outcomestring | string | string | object | string | string

    How the result was reached. Present only once `status` is `completed`.

  • nameResolutionobject | object | object

    Whether the submitted name was treated as a facility or a provider. Absent until the job completes, and when an identifier in the request matched a site directly.

  • siteFinderProposalobject

    Signed proposal for creating the site when no existing site matched. Absent when a site matched, when the name is a provider whose facility could not be determined, when the entity is not a healthcare organization, or when the proposal could not be prepared.

  • spellingCorrectionobject

    The corrected name and/or city the search used, when the submitted spelling could not be located.

  • siteEligibilityobject

    Web-search check of an unmatched name and address. Present only when no existing site matched and the check ran; a `category` of `other` means the entity is not a medical facility, pharmacy or lab, and no `siteFinderProposal` is returned.

  • errorstring

    Message describing why the job failed. Present only when `status` is `failed`.

  • startedAtstring

    When the job began running (RFC 3339, UTC); absent while it is still `pending`.

  • finishedAtstring

    When the job reached `completed` or `failed` (RFC 3339, UTC); absent until then.

Errors

401404500