Skip to content
Hermes Health API
GuidesOpenAPI spec

Endpoints

Projects

The project object

Attributes

  • projectobject

    The project.

  • project.idstring

    The project's ID.

  • project.companyIdinteger

    ID of the company that owns the project.

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

  • project.namestring

    The project's name.

  • project.descriptionstring

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

  • project.createdAtstring

    When the project was created.

  • project.updatedAtstring

    When the project was last changed.

  • project.medicalInformationRequestedstring[]

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

  • project.statusstring

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

  • project.authorizationMethodstring

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

  • project.selfServeboolean

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

  • companyobject

    The company that owns the project.

  • company.idinteger

    Numeric identifier of the company.

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

  • company.namestring

    Name of the company.

  • requestobject

    Number of record requests in the project.

  • request.countinteger

    Number of related records; zero when there are none.

  • patientobject

    Number of patients in the project.

  • patient.countinteger

    Number of related records; zero when there are none.

  • visitobject

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

  • visit.countinteger

    Number of related records; zero when there are none.

  • 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.

  • requestLetter.uploadHeadersobject

    Extra headers to send with the upload. Normally empty.

  • 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.

  • 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.

  • requestLetter.looseFiles[].urlstring

    Short-lived presigned URL to download the file.

  • requestLetter.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.

  • requestLetter.looseFiles[].keystring

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

  • requestLetter.looseFiles[].sizeinteger

    The file's size in bytes.

  • requestLetter.looseFiles[].lastModifiedstring

    When the file was last written.

  • 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.

  • representationLetter.uploadHeadersobject

    Extra headers to send with the upload. Normally empty.

  • 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.

  • 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.

  • representationLetter.looseFiles[].urlstring

    Short-lived presigned URL to download the file.

  • representationLetter.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.

  • representationLetter.looseFiles[].keystring

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

  • representationLetter.looseFiles[].sizeinteger

    The file's size in bytes.

  • representationLetter.looseFiles[].lastModifiedstring

    When the file was last written.

Conditional attributes

  • project.purposestring

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

  • 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.

  • 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.

  • requestLetter.extractionobject

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

  • requestLetter.verdictsobject

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

  • requestLetter.verdictCountsobject

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

  • 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.

  • requestLetter.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.

  • requestLetter.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.

  • 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.

  • 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.

  • 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.

  • representationLetter.extractionobject

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

  • representationLetter.verdictsobject

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

  • representationLetter.verdictCountsobject

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

  • 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.

  • representationLetter.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.

  • representationLetter.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.

  • 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.

POST/v0/companies/{company_id}/projects

Create a project (Hermes-generated ID)

Creates a new project with a generated id. This call is not idempotent: retrying a request that succeeded creates a second project, so use the PUT form with your own id when you need safe retries. When purpose is omitted the company’s default purpose is used; a sandbox API key can only create sandbox projects. Returns the created project.

Request bodyapplication/json

  • namestring

    The project's name.

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

  • medicalInformationRequestedstring[]

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

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

Optional parameters

  • Idstring

    Ignored. Hermes generates the ID on create, and an upsert takes it from the URL.

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

  • descriptionstring

    A free-text description of the project. Omit it or send null for none.

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

  • statusstring

    The project's status. Omitted or null means `Live` on create and unchanged on upsert. Only Hermes can change the status of an existing project, except that a customer admin may move a `Sandbox` project to `Closed`. The sandbox API key can only create `Sandbox` projects.

  • isSandboxbooleanDeprecated

    Legacy spelling of `status`: `true` creates a `Sandbox` project and overrides `status`. Prefer `status` in new code.

  • purposestring

    Why the project requests records; must be one of the purposes enabled for the company. Omitted or null means the company's default purpose on create (the request is rejected when there is none) and unchanged on upsert. Only Hermes can change the purpose of an existing project.

  • authorizationMethodstring

    Omitted / null means "Authorization PDF on create" or "preserve on upsert".

  • selfServeboolean

    Omitted / null means "default false on create" or "preserve on upsert".

ReturnsSuccess

Returns The project object.

Errors

400401500

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

Retrieve a project

Returns the project with its company name, counts of its patients, record requests, and visits, and presigned URLs for its request and representation letters. Returns 404 when the project does not exist or is not visible to the caller.

ReturnsSuccess

Returns The project object.

Errors

401404500

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

Upsert a project by ID

Creates the project under the id you choose, or replaces it if one already exists at this path, so repeating the same call is safe. On an existing project, omitted status, purpose, authorizationMethod, and selfServe fields keep their current values. A sandbox API key can only write sandbox projects, and changing an existing project’s status, purpose, authorization method, or self-serve flag is not permitted for customer callers and returns 401. Returns the stored project.

Request bodyapplication/json

  • namestring

    The project's name.

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

  • medicalInformationRequestedstring[]

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

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

Optional parameters

  • Idstring

    Ignored. Hermes generates the ID on create, and an upsert takes it from the URL.

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

  • descriptionstring

    A free-text description of the project. Omit it or send null for none.

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

  • statusstring

    The project's status. Omitted or null means `Live` on create and unchanged on upsert. Only Hermes can change the status of an existing project, except that a customer admin may move a `Sandbox` project to `Closed`. The sandbox API key can only create `Sandbox` projects.

  • isSandboxbooleanDeprecated

    Legacy spelling of `status`: `true` creates a `Sandbox` project and overrides `status`. Prefer `status` in new code.

  • purposestring

    Why the project requests records; must be one of the purposes enabled for the company. Omitted or null means the company's default purpose on create (the request is rejected when there is none) and unchanged on upsert. Only Hermes can change the purpose of an existing project.

  • authorizationMethodstring

    Omitted / null means "Authorization PDF on create" or "preserve on upsert".

  • selfServeboolean

    Omitted / null means "default false on create" or "preserve on upsert".

ReturnsSuccess

Returns The project object.

Errors

400401500

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

Update a project

Applies a single field change to the project, such as its name or description, and returns the updated project. Changing the purpose, status, authorization method, or self-serve flag is not permitted for customer callers and returns 401.

Request bodyapplication/json

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

ReturnsSuccess

Returns The project object.

Errors

400401404500

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

Delete a project

Deletes the project’s stored files as well, and is not reversible.

ReturnsSuccess

Errors

401404500