Create a project

A project is the container for a piece of work. Patients belong to it, and every record request under it inherits its purpose and its record types.

1. Find your company ID

Every route starts with /v0/companies/{companyId}. Get yours, and see what your account may do, from your own profile with GET /v0/user-profile:

curl https://api.hermeshealth.ai/v0/user-profile \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.hermeshealth.ai/v0/user-profile",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.hermeshealth.ai/v0/user-profile", {
    method: "GET",
    headers: {
        Authorization: "Bearer YOUR_API_KEY",
    },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

The response’s companyId is the value to use. permissions lists what your API key may do.

2. Create the project

Create it with POST /v0/companies/{companyId}/projects:

curl https://api.hermeshealth.ai/v0/companies/COMPANY_ID/projects \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Life underwriting 2026",
  "medicalInformationRequested": [
    "Progress notes",
    "Lab results"
  ],
  "purpose": "InsuranceLife"
}'

import requests

response = requests.post(
    "https://api.hermeshealth.ai/v0/companies/COMPANY_ID/projects",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "Life underwriting 2026",
        "medicalInformationRequested": [
            "Progress notes",
            "Lab results",
        ],
        "purpose": "InsuranceLife",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.hermeshealth.ai/v0/companies/COMPANY_ID/projects", {
    method: "POST",
    headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "name": "Life underwriting 2026",
      "medicalInformationRequested": [
        "Progress notes",
        "Lab results"
      ],
      "purpose": "InsuranceLife"
    }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

name and medicalInformationRequested are always required, and purpose is required unless your company has a default purpose. The response carries the new project’s ID, which you pass on every route below it.

The two fields that decide what the project does

purpose states why you are requesting records. It belongs to the project, not to each patient. Facilities use it to route each request to the right department, and it decides whether a patient needs an uploaded authorization before any search runs.

Your company is enabled for some of these purposes, not all of them. A purpose it isn’t enabled for is rejected with 400. Ask your Hermes Health contact which purposes are enabled, or to enable another.

medicalInformationRequested is the list of record types sent to the facility on every request in this project.

Sandbox or live

Add isSandbox to create a sandbox project:

{
  "name":                        "Integration sandbox",
  "medicalInformationRequested": ["Progress notes"],
  "purpose":                     "LegalPlaintiff",
  "isSandbox":                   true
}

Use a purpose your company is enabled for. Sandbox projects follow the same purpose rules as live ones.

Sandbox projects complete searches and record requests on their own against sample data, and never contact a real facility. Omit isSandbox and the project is Live.

Your sandbox API key works only on sandbox projects, and live projects reject it, so sandbox traffic cannot touch production data even by mistake.

A project’s status is fixed when you create it. To go to production, create a live project, since you cannot convert a sandbox one, and switch to your production API key. The calls themselves do not change.

Next steps

• Add a patient to the project.
• Find where a patient was treated, Get clinical history for a patient or Request records from a facility, once the patient is in.