Skip to content
Hermes Health API
GuidesOpenAPI spec

Endpoints

Patients

The patient object

Attributes

  • patientobject

    The patient record.

  • patient.companyIdinteger

    ID of the company that owns the patient.

    The numeric id of the company (tenant) a resource belongs to.

  • patient.idstring

    The patient's ID, unique within the project.

  • patient.projectIdstring

    ID of the project the patient belongs to.

    An identifier of 1 to 32 ASCII letters, digits, hyphens or underscores.

  • patient.firstNamestring

    The patient's first name, including any additional first names.

  • patient.lastNamestring

    The primary last name.

  • patient.lastNamesstring[]

    Every last name for the patient — primary first, then any alternate last names (maiden/prior names). Always contains at least one entry.

  • patient.dateOfBirthstring

    The patient's date of birth, as `YYYY-MM-DD`.

  • patient.sexstring

    The patient's sex.

  • patient.zipCodesstring[]

    The ZIP codes where the patient lived at the time of each visit, not necessarily their current ZIP code. Empty when none are on file.

  • patient.hasSocialSecurityNumberboolean

    Whether an SSN is on file, without exposing its value. Lets the frontend render the censored value + reveal control when present, or "Not provided" (and no reveal button) when absent — instead of always assuming one might exist and forcing a wasted reveal click.

  • patient.createdAtstring

    When the patient was created.

  • patient.authorizationStatusstring

    Where the review of the patient's authorization stands. Searches are not submitted until it is `Approved`.

  • patient.searchLevelstring

    Legacy coupled search level, derived from the `siteSonar` / `patientHistories` flags below — read those in new code.

  • patient.siteSonarboolean

    Whether site sonar (facility discovery) is requested.

  • patient.patientHistoriesboolean

    Whether patient histories (diagnosis/treatment data) are requested.

  • patient.ehrSearchboolean

    Whether EHR Search is requested for this patient.

  • patient.searchStatusstring

    Where the patient's clinical-data searches stand. Watch this field, or subscribe a webhook to it, to learn when a search finishes.

  • patient.siteSonarStatusstringDeprecated

    Deprecated alias of `searchStatus`, always the same value. Read `searchStatus` in new code; this field will be removed.

  • projectJoinobject

    The project the patient belongs to, with its company, its record request, patient and visit counts, and its letters.

  • projectJoin.projectobject

    The project.

  • projectJoin.project.idstring

    The project's ID.

  • projectJoin.project.companyIdinteger

    ID of the company that owns the project.

    The numeric id of the company (tenant) a resource belongs to.

  • projectJoin.project.namestring

    The project's name.

  • projectJoin.project.descriptionstring

    A free-text description of the project. Empty when none was given.

  • projectJoin.project.createdAtstring

    When the project was created.

  • projectJoin.project.updatedAtstring

    When the project was last changed.

  • projectJoin.project.medicalInformationRequestedstring[]

    The kinds of medical information the project requests, one free-text entry each, such as `Medication history`.

  • projectJoin.project.statusstring

    Where the project is in its lifecycle: `Sandbox`, `Live`, or `Closed`.

  • projectJoin.project.authorizationMethodstring

    How the project's patients authorize the release of their records.

  • projectJoin.project.selfServeboolean

    Whether the project is configured for self-service operation. Only Hermes can turn this on; false otherwise.

  • projectJoin.companyobject

    The company that owns the project.

  • projectJoin.company.idinteger

    Numeric identifier of the company.

    The numeric id of the company (tenant) a resource belongs to.

  • projectJoin.company.namestring

    Name of the company.

  • projectJoin.requestobject

    Number of record requests in the project.

  • projectJoin.request.countinteger

    Number of related records; zero when there are none.

  • projectJoin.patientobject

    Number of patients in the project.

  • projectJoin.patient.countinteger

    Number of related records; zero when there are none.

  • projectJoin.visitobject

    Number of visits on file across the project's patients.

  • projectJoin.visit.countinteger

    Number of related records; zero when there are none.

  • projectJoin.requestLetterobject

    The project's request letter: the project's own when one is uploaded, otherwise the company's default. The download URL is null when neither exists.

  • projectJoin.requestLetter.uploadHeadersobject

    Extra headers to send with the upload. Normally empty.

  • projectJoin.requestLetter.expiresIninteger

    How long the URLs in this object stay valid, in seconds from when they were issued. Fetch a fresh object rather than caching one.

  • projectJoin.requestLetter.looseFilesobject[]

    Other files stored under this file's location that are not part of its own document set, such as separately uploaded scans, each with its own short-lived download URL. Empty when there are none or when this response only offers an upload.

  • projectJoin.representationLetterobject

    The project's letter of representation: the project's own when one is uploaded, otherwise the company's default. The download URL is null when neither exists.

  • projectJoin.representationLetter.uploadHeadersobject

    Extra headers to send with the upload. Normally empty.

  • projectJoin.representationLetter.expiresIninteger

    How long the URLs in this object stay valid, in seconds from when they were issued. Fetch a fresh object rather than caching one.

  • projectJoin.representationLetter.looseFilesobject[]

    Other files stored under this file's location that are not part of its own document set, such as separately uploaded scans, each with its own short-lived download URL. Empty when there are none or when this response only offers an upload.

  • authorizationobject

    The patient's authorization document: a short-lived download URL when one is on file, and a short-lived upload URL for sending a new one.

  • authorization.uploadHeadersobject

    Extra headers to send with the upload. Normally empty.

  • authorization.expiresIninteger

    How long the URLs in this object stay valid, in seconds from when they were issued. Fetch a fresh object rather than caching one.

  • authorization.looseFilesobject[]

    Other files stored under this file's location that are not part of its own document set, such as separately uploaded scans, each with its own short-lived download URL. Empty when there are none or when this response only offers an upload.

  • authorization.looseFiles[].urlstring

    Short-lived presigned URL to download the file.

  • authorization.looseFiles[].fileNamestring

    The name a reader sees. For a record request's deliverables this is the unique name the shared presentation assigned (see `DeliverableView`), so it can differ from the object's own basename when two returns brought the same file name; everywhere else it IS the basename.

  • authorization.looseFiles[].keystring

    The file's full storage path, `/`-separated.

  • authorization.looseFiles[].sizeinteger

    The file's size in bytes.

  • authorization.looseFiles[].lastModifiedstring

    When the file was last written.

  • hipaaAuthorizationobjectDeprecated

    Deprecated copy of `authorization`, always the same value. Read `authorization` in new code; this field will be removed.

  • visitCountinteger

    Number of visits on file for the patient.

  • completedRecordRequestCountinteger

    Number of the patient's record requests in a finished status: `Completed`, `Partial`, `PatientNotFound`, `ServiceDatesNotFound`, `SiteClosed`, `Canceled`, `DuplicateRequest`, or `Resubmitted`.

  • recordRequestCountinteger

    Number of the patient's record requests, in any status.

  • checkobject

    Whether the patient has the authorization the project requires.

  • check.readyboolean

    Whether the patient has the authorization the project requires: always true on a project with a covered purpose (`CoveredOperations`, `CoveredPayment`, `CoveredTreatment`), otherwise true once an authorization document is uploaded. It does not mean the authorization is approved; see `authorizationStatus`.

  • check.authorizationUploadedboolean

    Whether an authorization document has been uploaded for the patient.

  • siteSonarAvailableboolean

    Whether Site Sonar is available for this patient — i.e. the company has been approved for the feature (`site_sonar_enabled`). Always `true` on a Sandbox project, whose searches are simulated and need no approval.

  • patientHistoriesAvailableboolean

    Whether patient histories are available for this patient — i.e. the company has been approved for the feature (`patient_histories_enabled`). Always `true` on a Sandbox project, whose searches are simulated and need no approval.

  • ehrSearchAvailableboolean

    Whether EHR Search is available for this patient — i.e. the company has been approved for the feature (`ehr_search_enabled`). Always `true` on a Sandbox project, whose searches are simulated and need no approval.

  • notesobject[]

    Notes left on the patient, newest first.

  • notes[].idstring

    The note's ID.

  • notes[].createdAtstring

    When the note was written.

  • notes[].userEmailstring

    Email address of the user who wrote the note. Empty when that user can no longer be found.

  • notes[].contentstring

    The note's text.

  • notes[].authoredByAiboolean

    True when the note was authored by the Hermes AI voice agent rather than a human user. Renderers show an automated "AI" badge and skip the human user lookup.

Conditional attributes

  • patient.zipCodestringDeprecated

    Deprecated: the first entry of `zipCodes`, or null when there is none. Read `zipCodes` in new code.

  • patient.mobilestring

    The patient's mobile phone number in E.164 form, such as `+12025550142`. Null when none is on file.

  • patient.emailstring

    The patient's email address. Null when none is on file.

  • patient.userIdstring

    ID of the user who created the patient. Null when not recorded.

  • patient.ownerUserIdstring

    Assignee for queue-based work distribution. Distinct from `user_id`, which is the creator. Cleared/set via the patient queue endpoint.

  • projectJoin.project.purposestring

    Why the project requests records. Null when no purpose is set.

  • projectJoin.requestLetter.downloadUrlstring

    Short-lived presigned URL to download the file. Null when no file is stored yet, or when this response only offers an upload.

  • projectJoin.requestLetter.uploadUrlstring

    Short-lived presigned URL to upload the file: `PUT` the raw bytes to it exactly as issued, with no `Authorization` header. Uploading again replaces the file. Null when this response only offers a download.

  • projectJoin.requestLetter.extractionobject

    The document's extraction (form data under `data`, plus text and page count). Null for non-auth-check files.

  • projectJoin.requestLetter.verdictsobject

    The auth-check verdicts derived from `extraction`. Null for non-auth-check files or when the document hasn't been analyzed.

  • projectJoin.requestLetter.verdictCountsobject

    Tally of `verdicts` by status, a readability convenience for API consumers. Null exactly when `verdicts` is null.

  • projectJoin.requestLetter.embedTokenstring

    Standalone auth-check embed token, pre-minted on the upload path when the caller supplies patient context alongside the request for an upload URL. Equivalent to the token from `POST /v0/auth-check/<filename>/embed-token`, saving that round-trip. Null when no patient context was supplied.

  • projectJoin.requestLetter.uploadedByobject | object | object | object | object | object | object | object | object | object | object

    Who or what placed this file. Absent when no attribution was recorded or when this endpoint does not report it.

  • projectJoin.representationLetter.downloadUrlstring

    Short-lived presigned URL to download the file. Null when no file is stored yet, or when this response only offers an upload.

  • projectJoin.representationLetter.uploadUrlstring

    Short-lived presigned URL to upload the file: `PUT` the raw bytes to it exactly as issued, with no `Authorization` header. Uploading again replaces the file. Null when this response only offers a download.

  • projectJoin.representationLetter.extractionobject

    The document's extraction (form data under `data`, plus text and page count). Null for non-auth-check files.

  • projectJoin.representationLetter.verdictsobject

    The auth-check verdicts derived from `extraction`. Null for non-auth-check files or when the document hasn't been analyzed.

  • projectJoin.representationLetter.verdictCountsobject

    Tally of `verdicts` by status, a readability convenience for API consumers. Null exactly when `verdicts` is null.

  • projectJoin.representationLetter.embedTokenstring

    Standalone auth-check embed token, pre-minted on the upload path when the caller supplies patient context alongside the request for an upload URL. Equivalent to the token from `POST /v0/auth-check/<filename>/embed-token`, saving that round-trip. Null when no patient context was supplied.

  • projectJoin.representationLetter.uploadedByobject | object | object | object | object | object | object | object | object | object | object

    Who or what placed this file. Absent when no attribution was recorded or when this endpoint does not report it.

  • authorization.downloadUrlstring

    Short-lived presigned URL to download the file. Null when no file is stored yet, or when this response only offers an upload.

  • authorization.uploadUrlstring

    Short-lived presigned URL to upload the file: `PUT` the raw bytes to it exactly as issued, with no `Authorization` header. Uploading again replaces the file. Null when this response only offers a download.

  • authorization.extractionobject

    The document's extraction (form data under `data`, plus text and page count). Null for non-auth-check files.

  • authorization.verdictsobject

    The auth-check verdicts derived from `extraction`. Null for non-auth-check files or when the document hasn't been analyzed.

  • authorization.verdictCountsobject

    Tally of `verdicts` by status, a readability convenience for API consumers. Null exactly when `verdicts` is null.

  • authorization.embedTokenstring

    Standalone auth-check embed token, pre-minted on the upload path when the caller supplies patient context alongside the request for an upload URL. Equivalent to the token from `POST /v0/auth-check/<filename>/embed-token`, saving that round-trip. Null when no patient context was supplied.

  • authorization.looseFiles[].folderstring

    The display folder this file sits in, `/`-joined, relative to the listing root. Populated only where a listing presents a tree — a record request's deliverables — and omitted from the payload otherwise.

  • authorization.looseFiles[].uploadedByobject | object | object | object | object | object | object | object | object | object | object

    Who or what placed this file. Absent for older files recorded without attribution.

  • authorization.uploadedByobject | object | object | object | object | object | object | object | object | object | object

    Who or what placed this file. Absent when no attribution was recorded or when this endpoint does not report it.

  • ehrSearchBlockedReasonstring

    Why the EHR Search this patient has requested will not actually run, or null when nothing is holding it back. Availability and runnability are different questions: `ehrSearchAvailable` says the company is approved for the feature, this says whether the request as submitted can reach the vendor at all. Only ever set when `ehrSearch` is requested — the requestor is being told about the run they asked for. `MissingZipCode` means the submission is armed and waiting: add a ZIP code and it goes out on its own, with no further call.

  • patientHistoriesBlockedReasonstring

    Why the Patient Histories run this patient has requested will not actually run, or null when nothing is holding it back. Scoped to what will actually run: an `InsuranceLife` project does not require a ZIP code for its histories run, so a zip-less patient there is never reported as blocked. See `ehrSearchBlockedReason` for the availability-vs-runnability distinction.

  • siteSonarBlockedReasonstring

    Why the Site Sonar run this patient has requested will not actually run, or null when nothing is holding it back. A ZIP code is never the reason here — Site Sonar searches a zip-less patient fine — so the only value this takes is `DeceasedBeforeClinicalData`, for a patient whose authorization documents date their death before any clearinghouse still holds records. Unlike `MissingZipCode` that is not a wait: nothing an operator supplies will make the search find something, and the capability is finished rather than armed.

  • latestSiteSonarFeeAtstring

    Created-at of this patient's latest non-canceled Site Sonar fee (`SiteSonarHit` / `SiteSonarNoHit`) — the same fees shown in Clinical Data Activity. Null when Site Sonar has never billed a run.

  • latestPatientHistoriesFeeAtstring

    Created-at of this patient's latest non-canceled Patient Histories fee (`PatientHistoryHit` / `PatientHistoryNoHit` / `PatientHistoriesPlus`) — the same fees shown in Clinical Data Activity. Null when Patient Histories has never billed a run.

  • latestEhrSearchSentAtstring

    When this patient's latest EHR Search request was sent — the Clinical Data Activity outbound timestamp. Null when no EHR Search request has been recorded.

  • createdByEmailstring

    Email of the user who created this patient.

  • ownerEmailstring

    Email of the user currently assigned as the owner. Null when the patient is unowned or when the owner record can no longer be resolved.

  • notes[].updatedAtstring

    When the note was last edited. Null when it has never been edited.

  • embedTokenstring

    Pre-minted embed token for iframing a read-only auth-check view. Pass the token to `GET /ui/auth-check/embed?token=...` to render the analysis UI inside your own page without proxying the raw analysis schema. Null when the authorization PDF has not yet been uploaded. Expiry is one hour from fetch time — re-fetch the patient for a fresh token. See [Embedding the auth-check UI](#embedding-the-auth-check-ui).

POST/v0/companies/{company_id}/projects/{project_id}/patients

Create a patient (Hermes-generated ID)

Hermes assigns the patient ID and returns it. Use PUT instead to choose the ID yourself, or to re-send a patient you already have an ID for.

Set siteSonar and/or patientHistories on the body to begin retrieval immediately; omit both to register the patient without searching. Both routes take the same body — the ID strategy is the only difference.

Request bodyapplication/json

  • firstNamestring

    The patient's first name. Put additional first names here, separated by spaces (`Mary Anne`). Omit middle names.

    A person's name: letters in any script, spaces, hyphens, apostrophes and periods, with no digits. A hyphen or apostrophe must sit between two letters (Smith-Jones, O'Brien), a period only right after a letter (Smith Jr.), and never two spaces in a row. Surrounding whitespace is trimmed, the text is Unicode-normalized (NFC), and curly apostrophes, Unicode hyphens and no-break spaces become their plain forms. A blank or invalid name is rejected, with a message saying what to fix.

  • dateOfBirthstring

    The patient's date of birth, as `YYYY-MM-DD`.

    A date of birth. Must not lie in the future; today (in UTC) is allowed. A future or invalid date is rejected.

  • sexstring

    The patient's sex: `male`, `female`, or `unknown`. Set it whenever it is known: when it is `unknown` and records are found under both sexes, `searchStatus` becomes `AmbiguousIdentity` and the records are withheld until it is set.

Optional parameters

  • lastNamestringDeprecated

    Legacy single last name, kept for backward compatibility. Send `lastNames` instead; this is ignored when `lastNames` is also sent.

    A person's name: letters in any script, spaces, hyphens, apostrophes and periods, with no digits. A hyphen or apostrophe must sit between two letters (Smith-Jones, O'Brien), a period only right after a letter (Smith Jr.), and never two spaces in a row. Surrounding whitespace is trimmed, the text is Unicode-normalized (NFC), and curly apostrophes, Unicode hyphens and no-break spaces become their plain forms. A blank or invalid name is rejected, with a message saying what to fix.

  • lastNamesstring[]

    Every last name for the patient. Each last name is searched separately against the clinical data sources, and the Site Sonar / Patient Histories fee is charged as a multiple of the name count. Put a suffix after the last name, separated by a space (`Smith Jr.`), and omit middle names entirely.

    A patient's last names: the primary last name first, then any alternates such as maiden or prior married names. At least one entry, and every entry follows the person-name rules. A hyphenated name is one entry (Smith-Jones), not two. An empty list or an invalid entry is rejected.

  • zipCodestringDeprecated

    Legacy single ZIP code, kept for backward compatibility. Send `zipCodes` instead; this is ignored when `zipCodes` is also sent.

    A US ZIP code: five digits, or ZIP+4 as NNNNN-NNNN. A ZIP+4 without its hyphen is accepted, and a base shorter than five digits is left-padded with zeroes. Surrounding whitespace is trimmed, and the value is always returned as NNNNN or NNNNN-NNNN. Anything else is rejected.

  • zipCodesstring[]

    The ZIP codes where the patient lived at the time of each visit, not their current ZIP code. Pass every one you know; they widen the clinical-data search. On a live project a patient without one has a requested EHR Search held until a ZIP code is added, and Patient Histories too unless the project's purpose is `InsuranceLife`.

    A US ZIP code: five digits, or ZIP+4 as NNNNN-NNNN. A ZIP+4 without its hyphen is accepted, and a base shorter than five digits is left-padded with zeroes. Surrounding whitespace is trimmed, and the value is always returned as NNNNN or NNNNN-NNNN. Anything else is rejected.

  • cityStatesobject[]

    City and state pairs for locations where the patient received care — one entry per address, each carrying both halves. City and state are always sent together: the clinical data sources match on the pair, and a city without its state matches nothing. A two-letter USPS code or the full state name is accepted and stored as the code; an unrecognized state is rejected with a 422 during deserialization. Values are taken as supplied and are not required to be verified against any external record.

  • cityStates[].citystring

    The city name.

    A city name. Surrounding whitespace is trimmed, and it must contain at least one letter or digit, or it is rejected. Stored as written, with its case unchanged.

  • cityStates[].statestring

    The state the city is in.

    A US state, district or territory: its two-letter USPS code, or its full name in any letter case. Washington DC, Washington D.C., US Virgin Islands, U.S. Virgin Islands, United States Virgin Islands and Virgin Islands are also accepted. Surrounding whitespace is trimmed, and any other value is rejected. Returned as the uppercase code.

  • mobilestring

    The patient's mobile number. Omit the field or send `null` to clear it.

    A phone number, returned in E.164 form (+12025550142). Any common spelling is accepted on input, such as (202) 555-0142 or 202-555-0142; a number without a country code is read as a US number, and other countries need the + and their country code. A number that is not valid for its country is rejected.

  • socialSecurityNumberstring

    The patient's Social Security number. Omit the field or send null for none. Patient responses report only whether one is on file.

    Free text. Surrounding whitespace is trimmed, and an empty or whitespace-only value is rejected.

  • payerInsuranceIdstring

    The patient's insurance or member id. Omit the field or send null for none.

    An insurance or member id, as the patient's provider records it. Surrounding whitespace is trimmed; it must not be blank and may be at most 80 characters, or it is rejected.

  • emailstring

    The patient's email address. Omit the field or send null for none.

    Free text. Surrounding whitespace is trimmed, and an empty or whitespace-only value is rejected.

  • siteSonarboolean

    Request Site Sonar, which finds the facilities where the patient was treated. Omitted means off.

  • patientHistoriesboolean

    Request Patient Histories, which retrieves the patient's diagnoses, procedures, prescription fills and lab results. Omitted means off. Independent of `siteSonar`.

  • ehrSearchboolean

    Request EHR Search, which searches connected EHR networks for the patient's records. Omitted means off. Independent of the other flags.

ReturnsSuccess

Returns The patient object.

Errors

400401403422500

GET/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}

Retrieve a patient

Returns the patient’s identity fields, authorizationStatus, and searchStatus. Poll this to watch a search progress, or subscribe a webhook to the request-flag columns instead.

ReturnsSuccess

Returns The patient object.

Errors

401404500

PUT/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}

Upsert a patient by ID

You supply the patient ID in the URL. If no patient has that ID one is created; if one does, it is replaced — so retries are idempotent. The ID may be one of your own or one Hermes generated earlier. Use POST instead when you have no ID yet and want Hermes to assign one.

Set siteSonar and/or patientHistories on the body to begin retrieval immediately; omit both to register the patient without searching. Both routes take the same body — the ID strategy is the only difference.

Request bodyapplication/json

  • firstNamestring

    The patient's first name. Put additional first names here, separated by spaces (`Mary Anne`). Omit middle names.

    A person's name: letters in any script, spaces, hyphens, apostrophes and periods, with no digits. A hyphen or apostrophe must sit between two letters (Smith-Jones, O'Brien), a period only right after a letter (Smith Jr.), and never two spaces in a row. Surrounding whitespace is trimmed, the text is Unicode-normalized (NFC), and curly apostrophes, Unicode hyphens and no-break spaces become their plain forms. A blank or invalid name is rejected, with a message saying what to fix.

  • dateOfBirthstring

    The patient's date of birth, as `YYYY-MM-DD`.

    A date of birth. Must not lie in the future; today (in UTC) is allowed. A future or invalid date is rejected.

  • sexstring

    The patient's sex: `male`, `female`, or `unknown`. Set it whenever it is known: when it is `unknown` and records are found under both sexes, `searchStatus` becomes `AmbiguousIdentity` and the records are withheld until it is set.

Optional parameters

  • lastNamestringDeprecated

    Legacy single last name, kept for backward compatibility. Send `lastNames` instead; this is ignored when `lastNames` is also sent.

    A person's name: letters in any script, spaces, hyphens, apostrophes and periods, with no digits. A hyphen or apostrophe must sit between two letters (Smith-Jones, O'Brien), a period only right after a letter (Smith Jr.), and never two spaces in a row. Surrounding whitespace is trimmed, the text is Unicode-normalized (NFC), and curly apostrophes, Unicode hyphens and no-break spaces become their plain forms. A blank or invalid name is rejected, with a message saying what to fix.

  • lastNamesstring[]

    Every last name for the patient. Each last name is searched separately against the clinical data sources, and the Site Sonar / Patient Histories fee is charged as a multiple of the name count. Put a suffix after the last name, separated by a space (`Smith Jr.`), and omit middle names entirely.

    A patient's last names: the primary last name first, then any alternates such as maiden or prior married names. At least one entry, and every entry follows the person-name rules. A hyphenated name is one entry (Smith-Jones), not two. An empty list or an invalid entry is rejected.

  • zipCodestringDeprecated

    Legacy single ZIP code, kept for backward compatibility. Send `zipCodes` instead; this is ignored when `zipCodes` is also sent.

    A US ZIP code: five digits, or ZIP+4 as NNNNN-NNNN. A ZIP+4 without its hyphen is accepted, and a base shorter than five digits is left-padded with zeroes. Surrounding whitespace is trimmed, and the value is always returned as NNNNN or NNNNN-NNNN. Anything else is rejected.

  • zipCodesstring[]

    The ZIP codes where the patient lived at the time of each visit, not their current ZIP code. Pass every one you know; they widen the clinical-data search. On a live project a patient without one has a requested EHR Search held until a ZIP code is added, and Patient Histories too unless the project's purpose is `InsuranceLife`.

    A US ZIP code: five digits, or ZIP+4 as NNNNN-NNNN. A ZIP+4 without its hyphen is accepted, and a base shorter than five digits is left-padded with zeroes. Surrounding whitespace is trimmed, and the value is always returned as NNNNN or NNNNN-NNNN. Anything else is rejected.

  • cityStatesobject[]

    City and state pairs for locations where the patient received care — one entry per address, each carrying both halves. City and state are always sent together: the clinical data sources match on the pair, and a city without its state matches nothing. A two-letter USPS code or the full state name is accepted and stored as the code; an unrecognized state is rejected with a 422 during deserialization. Values are taken as supplied and are not required to be verified against any external record.

  • cityStates[].citystring

    The city name.

    A city name. Surrounding whitespace is trimmed, and it must contain at least one letter or digit, or it is rejected. Stored as written, with its case unchanged.

  • cityStates[].statestring

    The state the city is in.

    A US state, district or territory: its two-letter USPS code, or its full name in any letter case. Washington DC, Washington D.C., US Virgin Islands, U.S. Virgin Islands, United States Virgin Islands and Virgin Islands are also accepted. Surrounding whitespace is trimmed, and any other value is rejected. Returned as the uppercase code.

  • mobilestring

    The patient's mobile number. Omit the field or send `null` to clear it.

    A phone number, returned in E.164 form (+12025550142). Any common spelling is accepted on input, such as (202) 555-0142 or 202-555-0142; a number without a country code is read as a US number, and other countries need the + and their country code. A number that is not valid for its country is rejected.

  • socialSecurityNumberstring

    The patient's Social Security number. Omit the field or send null for none. Patient responses report only whether one is on file.

    Free text. Surrounding whitespace is trimmed, and an empty or whitespace-only value is rejected.

  • payerInsuranceIdstring

    The patient's insurance or member id. Omit the field or send null for none.

    An insurance or member id, as the patient's provider records it. Surrounding whitespace is trimmed; it must not be blank and may be at most 80 characters, or it is rejected.

  • emailstring

    The patient's email address. Omit the field or send null for none.

    Free text. Surrounding whitespace is trimmed, and an empty or whitespace-only value is rejected.

  • siteSonarboolean

    Request Site Sonar, which finds the facilities where the patient was treated. Omitted means off.

  • patientHistoriesboolean

    Request Patient Histories, which retrieves the patient's diagnoses, procedures, prescription fills and lab results. Omitted means off. Independent of `siteSonar`.

  • ehrSearchboolean

    Request EHR Search, which searches connected EHR networks for the patient's records. Omitted means off. Independent of the other flags.

ReturnsSuccess

Returns The patient object.

Errors

400401403422500

PATCH/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}

Update a patient

Send only the fields you want to change. Changing an identity field (name, date of birth, sex, ZIP) to a genuinely new value resets the authorization for re-approval; non-identity changes never do.

Request bodyapplication/json

object | object | object | object | object | object | object | object | object | object | object | object | object | object | object

ReturnsSuccess

Returns The patient object.

Errors

400401403404422500

DELETE/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}

Delete a patient

Removes the patient record itself. To remove only the retrieved clinical data while keeping the patient, use the clinical-data route instead.

ReturnsSuccess

Errors

400401404500

POST/v0/patients/browse

Browse patients

JSON/CSV patient table browse.

Auth Check is categorically unavailable here: JSON clients may set limit to 1000+, and the S3-backed sidecar column is unsafe at that scale. Explicit select / where / orderBy / aggregate references to authCheck return 400. Absent select still omits the column (never enriched).

Request bodyapplication/json

Optional parameters

  • selectobject
  • select.patientobject

    Which of the patient's columns to return.

  • select.patient.idboolean

    Identifier of the patient within the customer organization and project. Match child-sheet patientId values together with companyId and projectId.

  • select.patient.firstNameboolean

    Patient first name from the patient profile.

  • select.patient.lastNameboolean

    Patient primary last name from the patient profile.

  • select.patient.alternateLastNamesboolean

    Alternate last names on file, excluding the primary lastName. Exported as a JSON array in one cell.

  • select.patient.dateOfBirthboolean

    Patient date of birth.

  • select.patient.sexboolean

    Patient sex as stored. Exported values are male, female, or unknown.

  • select.patient.zipCodesboolean

    Postal codes on the patient profile in stored order. Exported as a JSON array. Preserve leading zeros.

  • select.patient.mobileboolean

    Patient mobile telephone number, when supplied.

  • select.patient.emailboolean

    Patient email address, when supplied.

  • select.patient.createdAtboolean

    Timestamp when the patient record was created.

  • select.patient.updatedAtboolean

    Timestamp of the most recent patient creation, replacement, or profile update. Not the timestamp of every clinical result.

  • select.patient.authorizationStatusboolean

    Current authorization-validation status for the patient. This is a workflow status, not an authorization document.

  • select.patient.searchLevelboolean

    Legacy combined search setting derived from the independent search flags. Values are None, SiteSonar, or PatientHistory. Use the individual flags for current intent.

  • select.patient.siteSonarboolean

    Whether facility discovery is currently requested. This request flag can clear when processing completes. False does not mean no historical results exist.

  • select.patient.patientHistoriesboolean

    Whether clinical-history retrieval is currently requested. This request flag can clear when processing completes. False does not mean no historical results exist.

  • select.patient.ehrSearchboolean

    Whether electronic health record discovery is currently requested. A request flag, not a result-availability indicator.

  • select.patient.searchStatusboolean

    Current overall search-processing status. See the Reading guide for the exported status tokens.

  • select.patient.latestSubmissionErroredboolean
  • select.patient.ownerUserIdboolean

    Identifier of the user assigned to manage the patient. Distinct from the creator userId.

  • select.patient.companyIdboolean

    Identifier of the customer organization associated with the record.

  • select.patient.projectIdboolean

    Identifier of the project containing the record.

  • select.patient.userIdboolean

    Identifier of the user who created the patient record.

  • select.patient.linkboolean

    Relative application path to this record. Requires the application host and appropriate access to open.

  • select.patient.visitCountboolean

    Number of visit records currently associated with the patient.

  • select.patient.requestCountboolean

    Number of record requests associated with the patient, including C-CDA requests.

  • select.patient.recordRequestCountboolean

    Number of medical, imaging, and billing requests associated with the patient. Excludes C-CDA requests.

  • select.patient.ccdaRequestCountboolean

    Number of C-CDA requests associated with the patient.

  • select.patient.requestCompletedOrCanceledCountboolean

    Number of patient requests with status Completed, Canceled, or Void.

  • select.patient.feeTotalboolean

    Sum of non-canceled fees associated with the patient, excluding fees classified as record-request fees. Monetary amount; the field does not carry a currency code.

  • select.patient.lastSonarRunAtboolean

    Creation timestamp of the most recent non-canceled facility-discovery fee. It marks billed search activity, not necessarily when results arrived.

  • select.patient.lastHistoriesRunAtboolean

    Creation timestamp of the most recent non-canceled clinical-history fee. It marks billed search activity, not necessarily when results arrived.

  • select.patient.lastEhrRunAtboolean

    Most recent outbound electronic health record search timestamp across the patient search submissions.

  • select.patient.diagnosisCountboolean

    Number of diagnosis records currently associated with the patient.

  • select.patient.procedureCountboolean

    Number of procedure records currently associated with the patient.

  • select.patient.prescriptionFillCountboolean

    Number of prescription dispensing records currently associated with the patient.

  • select.patient.labResultCountboolean

    Number of laboratory result records currently associated with the patient.

  • select.patient.authorizationExistsboolean

    Populated per request from S3 listings by the patient enricher.

  • select.patient.authorizationDownloadUrlboolean

    Download URL for the patient's HIPAA authorization file. Present only when an authorization file exists for the patient; null otherwise.

  • select.companyobject & object

    Which of the joined company's columns to return. Absent when the row has no company.

  • select.projectobject & object

    Which of the joined project's columns to return. Absent when the row has no project.

  • select.userobject & object

    Which of the joined user's columns to return. Absent when the row has no user.

  • select.authCheckobject

    Which of the auth check's columns to return. Absent when the row has no auth check.

  • select.authCheck.passedboolean

    The number of authorization checks that passed.

  • select.authCheck.warningboolean

    The number of authorization checks that raised a warning.

  • select.authCheck.failedboolean

    The number of authorization checks that failed.

  • select.authCheck.embedUrlboolean

    Relative embed URL (`/ui/auth-check/embed?token=...`) ready to drop straight into an iframe `src`. Read-only, token-authed; meant for external API consumers who iframe the view from their own sites.

  • select.authCheck.interactiveUrlboolean

    Relative interactive URL (`/ui/companies/<company_id>/projects/<project_id>/patients/<patient_id>/auth-check`) for the signed-in auth-check view with audit and correction tools. Absent unless the caller is permitted to audit auth-checks; use `embedUrl` otherwise.

  • select.authCheck.auditedboolean

    `true` when the audit has been marked complete, `false` when not yet. Absent unless the caller is permitted to audit auth-checks.

  • select.authCheck.tokenCostboolean

    USD cost of the LLM tokens spent producing the extraction. Absent unless the caller is permitted to view token costs, or when no cost was recorded.

  • select.authCheck.additionalDocumentsboolean

    Kinds of supporting documents attached to the authorization, from the effective (override-applied) extraction. VOID documents are included — presence is about what accompanies the form — with the void subset flagged in `void_documents`.

  • select.authCheck.voidDocumentsboolean

    The subset of `additional_documents` marked VOID / CANCELLED / REVOKED. Rides the selected row so cells can flag void badges, but is neither filterable nor sortable — filter on `additional_documents`.

  • whereobject
  • where.patientobject

    Filters on the patient's columns.

  • where.patient.idobject | object | object | object | object | object | object | string[]

    Identifier of the patient within the customer organization and project. Match child-sheet patientId values together with companyId and projectId.

  • where.patient.firstNameobject | object | object | object | object | object | object | string[]

    Patient first name from the patient profile.

  • where.patient.lastNameobject | object | object | object | object | object | object | string[]

    Patient primary last name from the patient profile.

  • where.patient.alternateLastNamesobject | object | object | object | object | object | object | string[]

    Alternate last names on file, excluding the primary lastName. Exported as a JSON array in one cell.

  • where.patient.dateOfBirthobject | object | object | object | object | object | object | object | string[]

    Patient date of birth.

  • where.patient.sexobject | object | object | object | string[]

    Patient sex as stored. Exported values are male, female, or unknown.

  • where.patient.zipCodesobject | object | object | object | object | object | object | string[]

    Postal codes on the patient profile in stored order. Exported as a JSON array. Preserve leading zeros.

  • where.patient.mobileobject | object | object | object | object | object | object | string[]

    Patient mobile telephone number, when supplied.

  • where.patient.emailobject | object | object | object | object | object | object | string[]

    Patient email address, when supplied.

  • where.patient.createdAtobject | object | object | object | object | object | object | object | string[]

    Timestamp when the patient record was created.

  • where.patient.updatedAtobject | object | object | object | object | object | object | object | string[]

    Timestamp of the most recent patient creation, replacement, or profile update. Not the timestamp of every clinical result.

  • where.patient.authorizationStatusobject | object | object | object | string[]

    Current authorization-validation status for the patient. This is a workflow status, not an authorization document.

  • where.patient.searchLevelobject | object | object | object | string[]

    Legacy combined search setting derived from the independent search flags. Values are None, SiteSonar, or PatientHistory. Use the individual flags for current intent.

  • where.patient.siteSonarobject | object | object | object | string[]

    Whether facility discovery is currently requested. This request flag can clear when processing completes. False does not mean no historical results exist.

  • where.patient.patientHistoriesobject | object | object | object | string[]

    Whether clinical-history retrieval is currently requested. This request flag can clear when processing completes. False does not mean no historical results exist.

  • where.patient.ehrSearchobject | object | object | object | string[]

    Whether electronic health record discovery is currently requested. A request flag, not a result-availability indicator.

  • where.patient.searchStatusobject | object | object | object | string[]

    Current overall search-processing status. See the Reading guide for the exported status tokens.

  • where.patient.latestSubmissionErroredobject | object | object | object | string[]
  • where.patient.ownerUserIdobject | object | object | object | object | object | object | string[]

    Identifier of the user assigned to manage the patient. Distinct from the creator userId.

  • where.patient.companyIdobject | object | object | object | object | object | object | object | string[]

    Identifier of the customer organization associated with the record.

  • where.patient.projectIdobject | object | object | object | object | object | object | string[]

    Identifier of the project containing the record.

  • where.patient.userIdobject | object | object | object | object | object | object | string[]

    Identifier of the user who created the patient record.

  • where.patient.visitCountobject | object | object | object | object | object | object | object | string[]

    Number of visit records currently associated with the patient.

  • where.patient.requestCountobject | object | object | object | object | object | object | object | string[]

    Number of record requests associated with the patient, including C-CDA requests.

  • where.patient.recordRequestCountobject | object | object | object | object | object | object | object | string[]

    Number of medical, imaging, and billing requests associated with the patient. Excludes C-CDA requests.

  • where.patient.ccdaRequestCountobject | object | object | object | object | object | object | object | string[]

    Number of C-CDA requests associated with the patient.

  • where.patient.requestCompletedOrCanceledCountobject | object | object | object | object | object | object | object | string[]

    Number of patient requests with status Completed, Canceled, or Void.

  • where.patient.feeTotalobject | object | object | object | object | object | object | object | string[]

    Sum of non-canceled fees associated with the patient, excluding fees classified as record-request fees. Monetary amount; the field does not carry a currency code.

  • where.patient.lastSonarRunAtobject | object | object | object | object | object | object | object | string[]

    Creation timestamp of the most recent non-canceled facility-discovery fee. It marks billed search activity, not necessarily when results arrived.

  • where.patient.lastHistoriesRunAtobject | object | object | object | object | object | object | object | string[]

    Creation timestamp of the most recent non-canceled clinical-history fee. It marks billed search activity, not necessarily when results arrived.

  • where.patient.lastEhrRunAtobject | object | object | object | object | object | object | object | string[]

    Most recent outbound electronic health record search timestamp across the patient search submissions.

  • where.patient.diagnosisCountobject | object | object | object | object | object | object | object | string[]

    Number of diagnosis records currently associated with the patient.

  • where.patient.procedureCountobject | object | object | object | object | object | object | object | string[]

    Number of procedure records currently associated with the patient.

  • where.patient.prescriptionFillCountobject | object | object | object | object | object | object | object | string[]

    Number of prescription dispensing records currently associated with the patient.

  • where.patient.labResultCountobject | object | object | object | object | object | object | object | string[]

    Number of laboratory result records currently associated with the patient.

  • where.patient.authorizationExistsobject | object | object | object | string[]

    Populated per request from S3 listings by the patient enricher.

  • where.patient.authorizationDownloadUrlobject | object | object | object | object | object | object | string[]

    Download URL for the patient's HIPAA authorization file. Present only when an authorization file exists for the patient; null otherwise.

  • where.companystring | object & object

    Filters on the joined company's columns. `isNull` or `isNotNull` in place of the filters matches the rows without or with a company.

  • where.projectstring | object & object

    Filters on the joined project's columns. `isNull` or `isNotNull` in place of the filters matches the rows without or with a project.

  • where.userstring | object & object

    Filters on the joined user's columns. `isNull` or `isNotNull` in place of the filters matches the rows without or with a user.

  • where.authCheckobject

    Filters on the auth check's columns. A row with no auth check matches none of these filters.

  • where.authCheck.passedobject | object | object | object | object | object | object | object | string[]

    The number of authorization checks that passed.

  • where.authCheck.warningobject | object | object | object | object | object | object | object | string[]

    The number of authorization checks that raised a warning.

  • where.authCheck.failedobject | object | object | object | object | object | object | object | string[]

    The number of authorization checks that failed.

  • where.authCheck.embedUrlobject | object | object | object | object | object | object | string[]

    Relative embed URL (`/ui/auth-check/embed?token=...`) ready to drop straight into an iframe `src`. Read-only, token-authed; meant for external API consumers who iframe the view from their own sites.

  • where.authCheck.interactiveUrlobject | object | object | object | object | object | object | string[]

    Relative interactive URL (`/ui/companies/<company_id>/projects/<project_id>/patients/<patient_id>/auth-check`) for the signed-in auth-check view with audit and correction tools. Absent unless the caller is permitted to audit auth-checks; use `embedUrl` otherwise.

  • where.authCheck.auditedobject | object | object | object | string[]

    `true` when the audit has been marked complete, `false` when not yet. Absent unless the caller is permitted to audit auth-checks.

  • where.authCheck.tokenCostobject | object | object | object | object | object | object | object | string[]

    USD cost of the LLM tokens spent producing the extraction. Absent unless the caller is permitted to view token costs, or when no cost was recorded.

  • where.authCheck.additionalDocumentsobject | object | object | object | string[]

    Kinds of supporting documents attached to the authorization, from the effective (override-applied) extraction. VOID documents are included — presence is about what accompanies the form — with the void subset flagged in `void_documents`.

  • aggregateobject
  • aggregate.patientobject
  • aggregate.patient.countboolean

    When true, return the number of rows that match the filter.

  • aggregate.patient.sumobject

    Numeric columns to total across the rows that match the filter.

  • aggregate.patient.avgobject

    Numeric columns to average across the rows that match the filter.

  • aggregate.patient.minobject

    Numeric columns to find the smallest value of across the rows that match the filter.

  • aggregate.patient.maxobject

    Numeric columns to find the largest value of across the rows that match the filter.

  • aggregate.companyobject & object
  • aggregate.projectobject & object
  • aggregate.userobject & object
  • aggregate.authCheckobject
  • aggregate.authCheck.countboolean

    When true, return the number of rows that match the filter.

  • aggregate.authCheck.sumobject

    Numeric columns to total across the rows that match the filter.

  • aggregate.authCheck.avgobject

    Numeric columns to average across the rows that match the filter.

  • aggregate.authCheck.minobject

    Numeric columns to find the smallest value of across the rows that match the filter.

  • aggregate.authCheck.maxobject

    Numeric columns to find the largest value of across the rows that match the filter.

  • orderByobject | object | object | object | object[]
  • searchstring
  • takeinteger
  • skipinteger

ReturnsTyped browse response for PatientBrowseResponse

Conditional attributes

  • tableobject[]
  • table[].patientobject & object

    The patient's columns, as selected by the request.

  • table[].companyobject & object & object & object

    The joined company's columns, as selected by the request. Absent when the row has no company.

  • table[].projectobject & object & object

    The joined project's columns, as selected by the request. Absent when the row has no project.

  • table[].userobject & object

    The joined user's columns, as selected by the request. Absent when the row has no user.

  • table[].authCheckobject

    The auth check's columns, as selected by the request. Absent when the row has no auth check.

  • table[].authCheck.passedinteger

    The number of authorization checks that passed.

  • table[].authCheck.warninginteger

    The number of authorization checks that raised a warning.

  • table[].authCheck.failedinteger

    The number of authorization checks that failed.

  • table[].authCheck.embedUrlstring

    Relative embed URL (`/ui/auth-check/embed?token=...`) ready to drop straight into an iframe `src`. Read-only, token-authed; meant for external API consumers who iframe the view from their own sites.

  • table[].authCheck.interactiveUrlstring

    Relative interactive URL (`/ui/companies/<company_id>/projects/<project_id>/patients/<patient_id>/auth-check`) for the signed-in auth-check view with audit and correction tools. Absent unless the caller is permitted to audit auth-checks; use `embedUrl` otherwise.

  • table[].authCheck.auditedboolean

    `true` when the audit has been marked complete, `false` when not yet. Absent unless the caller is permitted to audit auth-checks.

  • table[].authCheck.tokenCoststring

    USD cost of the LLM tokens spent producing the extraction. Absent unless the caller is permitted to view token costs, or when no cost was recorded.

  • table[].authCheck.additionalDocumentsstring[]

    Kinds of supporting documents attached to the authorization, from the effective (override-applied) extraction. VOID documents are included — presence is about what accompanies the form — with the void subset flagged in `void_documents`.

  • table[].authCheck.voidDocumentsstring[]

    The subset of `additional_documents` marked VOID / CANCELLED / REVOKED. Rides the selected row so cells can flag void badges, but is neither filterable nor sortable — filter on `additional_documents`.

  • aggregateobject
  • aggregate.patientobject
  • aggregate.patient.countinteger

    Number of rows that match the filter. Present when `count` was requested.

  • aggregate.patient.sumobject

    Total of each requested numeric column across the rows that match the filter.

  • aggregate.patient.avgobject

    Average of each requested numeric column across the rows that match the filter.

  • aggregate.patient.minobject

    Smallest value of each requested numeric column across the rows that match the filter.

  • aggregate.patient.maxobject

    Largest value of each requested numeric column across the rows that match the filter.

  • aggregate.companyobject & object
  • aggregate.projectobject & object
  • aggregate.userobject & object
  • aggregate.authCheckobject
  • aggregate.authCheck.countinteger

    Number of rows that match the filter. Present when `count` was requested.

  • aggregate.authCheck.sumobject

    Total of each requested numeric column across the rows that match the filter.

  • aggregate.authCheck.avgobject

    Average of each requested numeric column across the rows that match the filter.

  • aggregate.authCheck.minobject

    Smallest value of each requested numeric column across the rows that match the filter.

  • aggregate.authCheck.maxobject

    Largest value of each requested numeric column across the rows that match the filter.

  • totalinteger

Errors

400401500