Skip to content
Hermes Health API
GuidesOpenAPI spec

Endpoints

Site research

POST/v0/sites/{site_id}/research

Trigger AI research for a site

Trigger AI research for a site in the background.

Returns the current site data immediately. The research runs asynchronously; poll GET /v0/sites/<site_id> and check researchFinished for completion.

Parameters

  • site_idstringpath, required

    The id of the site to research.

ReturnsSuccess

  • siteobject

    The site's own fields.

  • site.idstring

    Unique identifier of the site.

  • site.npisstring[]

    National Provider Identifiers registered to the site, each a 10-digit number as text. Empty when none is known.

  • site.isFacilityboolean

    Whether the site is a facility, such as a hospital, clinic or pharmacy, rather than an individual practitioner.

  • site.namestring

    Name of the site.

  • site.updatedAtstring

    When the site was last updated, as an RFC 3339 timestamp in UTC.

  • siteEvidenceobject

    Per-field research provenance for the site-level scalars (system name, phone, main fax, website). Departments carry their own evidence inline on each department's `evidence` field.

  • hasEmbeddingboolean

    Whether the site is indexed for name-and-address similarity matching, so new submissions can be matched to it.

  • hasReferenceDataboolean

    Whether there is a reference half to toggle to, i.e. whether the details Reference control should render. When `reference` is included in the response, this is `true` exactly when `reference` is present. Otherwise it reflects whether the site has reference links at all, and may occasionally be `true` for a link that no longer resolves; the first Reference request corrects it.

Conditional attributes

  • site.taxIdstring

    Federal tax identification number of the organization operating the site. Empty string when not known, and always empty for customer accounts.

  • site.addressLine1string

    First line of the street address. Empty string when not known.

  • site.addressLine2string

    Second line of the street address, such as a suite or building. Empty string when there is none.

  • site.citystring

    City of the site's address. Empty string when not known.

  • site.zipstring

    ZIP code of the site's address, as text so leading zeros are kept. Empty string when not known.

  • site.phonestring

    Main telephone number of the site. Empty string when not known.

  • site.mainFaxstring

    Main fax number of the site in E.164 format. Separate from the departments' fax numbers. Null when not known.

  • site.emailstring

    General email address of the site. Separate from the departments' email addresses. Empty string when not known.

  • site.statestring

    State of the site's address, normally a two-letter code. Empty string when not known.

  • site.systemNamestring

    Name of the health system the site belongs to. Empty string when not known.

  • site.primarySpecialtystring

    Primary medical specialty of the site. Empty string when not known.

  • site.latitudenumber

    Latitude of the site in decimal degrees. Null when the address has not been located on a map, such as a PO box.

  • site.longitudenumber

    Longitude of the site in decimal degrees. Null when the address has not been located on a map, such as a PO box.

  • site.formattedAddressstring

    Complete address of the site on one line. Empty string when not known.

  • site.researchFinishedstring

    When the most recent full research run on the site's contact details finished, as an RFC 3339 timestamp in UTC. Null when the site has not been researched.

  • site.researchDurationMsinteger

    Wall-clock duration of the most recently completed AI research run.

  • site.operationalStatusstring

    Operational status determined by AI research; null until a site has been researched.

  • site.operationalStatusNotestring

    Generated explanation shown under the operational status (why the facility is closed/acquired and where records were transferred).

  • site.placeIdstring

    Identifier of the map place the site's address and name were verified against. Empty string when the site has not been verified.

  • site.addressHashinteger

    Numeric fingerprint of the site's normalized address, used to find sites at the same address. Null when the address has not been normalized.

  • site.fingerprintedAtstring

    When the site's address was last normalized and fingerprinted, as an RFC 3339 timestamp in UTC. Null when it never has been.

  • site.dedupConsideredAtstring

    When the site was last reviewed for duplicate records, as an RFC 3339 timestamp in UTC. Null when it never has been.

  • site.websitestring

    Website of the site. Empty string when not known.

  • site.acceptsEsignatureboolean

    Whether the site accepts electronically signed authorizations with a record request. Null when not known.

  • site.googlePlacesNamestring

    Name of the site as listed by the map place in `placeId`. Empty string when the site has not been verified.

  • site.dataSourcesstring[]

    Internal provenance labels for the site's information. Omitted when empty, and always empty for customer accounts.

  • site.npiEnumerationDatestring

    Date (YYYY-MM-DD) the site's NPI was first issued in the national provider registry. Null when not known.

  • site.npiDeactivationReasonstring

    Reason the national provider registry gives for deactivating the site's NPI. Empty string when the NPI has not been deactivated.

  • site.npiDeactivationDatestring

    Date (YYYY-MM-DD) the site's NPI was deactivated. Null when it has not been.

  • site.npiReactivationDatestring

    Date (YYYY-MM-DD) a deactivated NPI was reactivated. Null when it has not been.

  • site.medicalDepartmentIdstring

    Identifier of the department that receives medical records requests for this site. Null when none is routed.

  • site.facilityBillingDepartmentIdstring

    Identifier of the department that receives facility billing records requests. Null when none is routed.

  • site.physicianBillingDepartmentIdstring

    Identifier of the department that receives physician billing records requests. Null when none is routed.

  • site.imagingBillingDepartmentIdstring

    Identifier of the department that receives imaging billing records requests. Null when none is routed.

  • site.emergencyRoomBillingDepartmentIdstring

    Identifier of the department that receives emergency room billing records requests. Null when none is routed.

  • site.anesthesiologyBillingDepartmentIdstring

    Identifier of the department that receives anesthesiology billing records requests. Null when none is routed.

  • site.imagingDepartmentIdstring

    Identifier of the department that receives imaging records requests. Null when none is routed.

  • managingOrganizationIdstring

    The Organization that manages this site's Location — the legacy `Org-{site_id}` for untouched rows, a minted `Org-mint-{ksuid}` once the site has been through org dedup. Resolved from the projection because it is no longer derivable from the site id.

  • siteEvidence.systemNameobject

    Provenance and sign-off for the site's `systemName`.

  • siteEvidence.systemName.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.systemName.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.systemName.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.systemName.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.systemName.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.phoneobject

    Provenance and sign-off for the site's `phone`.

  • siteEvidence.phone.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.phone.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.phone.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.phone.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.phone.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.mainFaxobject

    Provenance and sign-off for the site's `mainFax`.

  • siteEvidence.mainFax.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.mainFax.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.mainFax.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.mainFax.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.mainFax.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.websiteobject

    Provenance and sign-off for the site's `website`.

  • siteEvidence.website.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.website.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.website.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.website.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.website.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.operationalStatusobject

    Provenance and sign-off for the site's operational status (whether it is open, closed, merged or relocated).

  • siteEvidence.operationalStatus.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.operationalStatus.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.operationalStatus.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.operationalStatus.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.operationalStatus.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.nameobject

    Sign-off for the site's `name`.

  • siteEvidence.name.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.name.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.name.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.name.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.name.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.taxIdobject

    Sign-off for the site's `taxId`.

  • siteEvidence.taxId.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.taxId.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.taxId.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.taxId.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.taxId.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.isFacilityobject

    Sign-off for the site's `isFacility`.

  • siteEvidence.isFacility.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.isFacility.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.isFacility.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.isFacility.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.isFacility.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.emailobject

    Provenance and sign-off for the site's `email`.

  • siteEvidence.email.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.email.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.email.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.email.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.email.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.primarySpecialtyobject

    Sign-off for the site's `primarySpecialty`.

  • siteEvidence.primarySpecialty.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.primarySpecialty.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.primarySpecialty.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.primarySpecialty.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.primarySpecialty.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.acceptsEsignatureobject

    Sign-off for the site's `acceptsEsignature`.

  • siteEvidence.acceptsEsignature.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.acceptsEsignature.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.acceptsEsignature.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.acceptsEsignature.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.acceptsEsignature.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.addressLine1object

    Sign-off for the site's `addressLine1`.

  • siteEvidence.addressLine1.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.addressLine1.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.addressLine1.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.addressLine1.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.addressLine1.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.addressLine2object

    Sign-off for the site's `addressLine2`.

  • siteEvidence.addressLine2.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.addressLine2.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.addressLine2.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.addressLine2.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.addressLine2.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.cityobject

    Sign-off for the site's `city`.

  • siteEvidence.city.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.city.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.city.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.city.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.city.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.stateobject

    Sign-off for the site's `state`.

  • siteEvidence.state.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.state.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.state.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.state.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.state.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • siteEvidence.zipobject

    Sign-off for the site's `zip`.

  • siteEvidence.zip.authoredboolean

    Whether the backing value was explicitly authored by a user or the AI researcher. Catalog ingestion and historical evidence serialized before this marker was introduced default to `false`.

  • siteEvidence.zip.sourcesobject[]

    Citations backing the value. Empty for manually-entered, ingested, or pre-evidence-replayed values; `authored` distinguishes the first case.

  • siteEvidence.zip.confirmedBystring

    User id that confirmed this researched value, or null while it is still system-authored (unconfirmed).

  • siteEvidence.zip.confirmedAtstring

    When the value was confirmed.

  • siteEvidence.zip.unverifiedboolean

    AI-authored value whose citation could not be kept: the researcher read it from a source we could not verify or store (a dead/blocked link, or a short-lived search-grounding redirect). The value is retained rather than discarded, but flagged so the UI shows the AI badge with an "unverified" source instead of a link. Distinct from `sources.is_empty()` alone, which means "manually entered".

  • googleMapsUrlstring

    Map link for the site's verified place. Null when the site has no `placeId`.

  • medicalDepartmentobject & object

    Department that receives medical records requests for this site, including values inherited from the managing organization. Null when none is routed.

  • facilityBillingDepartmentobject & object

    Department that receives facility billing records requests. Null when none is routed.

  • physicianBillingDepartmentobject & object

    Department that receives physician billing records requests. Null when none is routed.

  • imagingBillingDepartmentobject & object

    Department that receives imaging billing records requests. Null when none is routed.

  • emergencyRoomBillingDepartmentobject & object

    Department that receives emergency room billing records requests. Null when none is routed.

  • anesthesiologyBillingDepartmentobject & object

    Department that receives anesthesiology billing records requests. Null when none is routed.

  • imagingDepartmentobject & object

    Department that receives imaging records requests. Null when none is routed.

  • referenceobject

    Catalog-union half for the site-details Reference toggle. Absent when the site has no reference links, or when the viewer never asked for Reference mode and the union was not built. Details-only; not a browse column.

Errors

401404500