API Overview - Nestmed API Documentation

Overview

The Nestmed API enables you to build two types of integration clients that work in concert: EMR clients that push scheduling data into Nestmed, and application clients that capture clinical artifacts during visits. This architecture creates a complete documentation pipeline from your existing systems through to AI-generated clinical records.

Integration Architecture

EMR Clients

Your EMR integration pushes foundational data into Nestmed:

Patients: Demographics, medical history, insurance information
Episodes: Care periods from admission through discharge
Visits: Scheduled encounters with assigned clinicians
Documents: Admission files, care plans, prior assessments

This data synchronization ensures clinicians have complete context when documenting visits.

Application Clients

Nestmed mobile applications and custom clients consume this scheduling data and capture:

Audio recordings: Ambient conversations during patient encounters
Clinical images: Wounds, medications, home environment
Manual entries: Vital signs, assessment results, interventions performed

The API processes these artifacts through our AI engine to generate structured documentation.

Getting Started

Tenant Configuration

Every Nestmed integration requires a unique tenant identifier. Your organization will be provisioned with a tenantId during onboarding, which becomes part of your API base URL. This tenant-based architecture ensures complete data isolation and enables custom configurations per organization.

Base URL

https://{tenantId}.api.nestmed.com/api/v1

Replace {tenantId} with your organization’s identifier. For example, if your tenant ID is acme-health, your base URL would be:

https://acme-health.api.nestmed.com/api/v1

Authentication

All requests require OAuth 2.0 bearer tokens:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://acme-health.api.nestmed.com/api/v1/visits

Data Model & Hierarchy

Multi-Tenant Architecture

Organization → Agency (Branch)
    ├── Clinicians
    ├── Patients
    └── Visit Types

Patient → Admission
    └── Episode
        └── Visit
            ├── Media (Audio/Images)
            ├── Forms (Generic documentation)
            ├── Medications
            ├── Interventions
            └── Patient Goals

Each agency operates in complete data isolation. No cross-agency access is possible.

Core Entities

Episodes

Represent complete care periods from admission to discharge. All visits and documentation are scoped to an episode, maintaining clinical continuity across the care journey.

Visits

Scheduled clinical encounters that serve as containers for all documentation. Visits transition through states: scheduled → in_progress → completed.

Media Processing

Audio and images uploaded during visits trigger asynchronous AI processing:

Upload media via multipart/form-data
Receive task ID for tracking
Poll task status or receive webhook on completion
Retrieve processed derivatives (transcripts, extracts, captions)

Clinical Documentation Architecture

Forms

Forms are the foundation of Nestmed’s documentation system—flexible JSON schemas that capture any type of clinical data. Each form defines a question with a specific response schema that can include simple selections, multi-select arrays, and complex conditional logic where answers trigger follow-up questions. For example, an infectious disease screening form might start with a yes/no question: “Have you tested positive for any infectious disease in the past 2 weeks?” If the answer is “Yes”, the form dynamically reveals a multi-select list of diseases (COVID-19, C-diff, Influenza, etc.), and selecting “Other” triggers another field for specification. This conditional branching can go multiple levels deep, creating sophisticated documentation trees from simple JSON definitions. The response to a form submission follows the exact structure defined in the schema. Using our infectious disease example:

{
  "infectious_disease_pos_or_exposed_2w": "Yes",
  "infectious_disease_pos_or_exposed_2w__yes__follow_up": {
    "infectious_disease_multi_select": ["Covid 19", "Other"],
    "infectious_disease_multi_select__other__follow_up": {
      "specify": "Norovirus"
    }
  }
}

Each form includes a design specification that controls frontend rendering:

{
  "design_spec": {
    "texts": [
      {"content": "Recent Infectious Exposure", "style": "main_title"}
    ],
    "rows": [
      {
        "objectType": "text",
        "texts": [{"content": "Have you tested positive OR had an exposure?", "style": "body"}]
      },
      {
        "objectType": "value",
        "value": {
          "json_path": "infectious_disease_pos_or_exposed_2w",
          "display_type": "pill_single_select"
        }
      },
      {
        "objectType": "value",
        "value": {
          "json_path": "infectious_disease_pos_or_exposed_2w__yes__follow_up.infectious_disease_multi_select",
          "display_type": "radio_list_multi_select"
        },
        "depends": {
          "json_path": "infectious_disease_pos_or_exposed_2w",
          "value": "Yes"
        }
      }
    ]
  }
}

The design spec defines visual hierarchy through styled text elements, maps data fields to specific UI components (pill selects for yes/no, radio lists for multiple choice), and controls conditional rendering through dependency rules. Application clients parse this specification to automatically generate native interfaces that adapt as users answer questions, showing or hiding fields based on the defined logic. Organizations configure hundreds of these forms covering everything from medication reconciliation workflows to complex wound assessments. Each form maintains validation rules, hard-stop requirements for critical data, and seamless integration with your EMR’s existing documentation modules.

Medications

The medications module tracks the complete medication lifecycle with intelligent reconciliation across multiple sources. When medications appear in admission packets, are verbally confirmed during visits, or captured in photos, the system reconciles these into a unified medication list. Each medication maintains usage status (active/discontinued), dosing schedules, and financial responsibility for billing compliance. The clinician-reviewed flag ensures that once a provider confirms a medication, it remains in the record with appropriate versioning. The module also documents medication education: whether the patient understands the purpose, directions for use, and potential side effects.

Interventions

Interventions document skilled clinical actions as paired intervention-goal relationships. Each entry tracks whether the intervention was provided, captures implementation details, and assesses if the associated goal was met. When interventions aren’t provided or goals aren’t achieved, the system requires selection from a standardized list of exception reasons—from clinical factors like cognitive barriers to operational issues like equipment availability. Agencies maintain libraries of standard interventions with pre-configured goals, ensuring consistent documentation while supporting individualized care.

Patient Goals

Patient goals capture what matters most to the individual receiving care, distinct from clinical intervention goals. These document the collaborative planning process between patients and clinicians, whether the goal is maintaining independence, managing symptoms, or achieving functional milestones. Each goal includes the goal statement plus contextual comments about barriers and progress indicators. The clinician review flag ensures AI-suggested goals are validated before becoming part of the official care plan, creating a narrative thread that connects individual visits to the patient’s broader health journey.

Implementation Patterns

EMR Integration Flow

// 1. Create or update patient
POST /patients
{
  "mrn": "12345",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1950-01-15"
}

// 2. Create episode for admission
POST /episodes
{
  "patientId": "pat_123",
  "startDate": "2024-01-15",
  "admissionType": "routine"
}

// 3. Schedule visits
POST /visits
{
  "episodeId": "ep_456",
  "clinicianId": "cln_789",
  "scheduledDate": "2024-01-16T10:00:00Z",
  "visitType": "SN"
}

Application Client Flow

// 1. Start visit documentation
PUT /visits/{visitId}
{
  "status": "in_progress"
}

// 2. Upload clinical artifacts
POST /visits/{visitId}/audio
Content-Type: multipart/form-data

// 3. Add structured documentation
POST /visits/{visitId}/medications
{
  "name": "Metformin",
  "dosage": "500mg",
  "frequency": "twice daily"
}

// 4. Complete visit
PUT /visits/{visitId}
{
  "status": "completed"
}

Processing & Task Management

Asynchronous Operations

Long-running operations like audio processing, image analysis, and bulk data imports operate asynchronously to maintain API responsiveness. When you upload media or initiate complex processing, the API immediately returns a task ID that serves as your handle for monitoring progress. Tasks transition through states from pending to processing to completed or failed, with detailed progress information available at each stage. The task system supports automatic retries for transient failures, maintains processing logs for debugging, and can trigger webhook notifications upon completion to enable event-driven architectures. Media processing and bulk operations return task IDs for tracking:

// Initial response
{
  "taskId": "task_abc123",
  "status": "processing"
}

// Poll for completion
GET /tasks/task_abc123
{
  "status": "completed",
  "result": {
    "transcriptId": "tr_xyz",
    "extractedMedications": 12,
    "identifiedInterventions": 8
  }
}

Response Format

Consistent structure across all endpoints:

{
  "success": true,
  "data": { /* entity or collection */ },
  "meta": {
    "timestamp": "2024-01-15T10:00:00Z",
    "request_id": "req_123abc"
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid episode status transition",
    "details": {
      "current_status": "completed",
      "requested_status": "active"
    }
  }
}

Rate Limiting

Standard tier: 100 requests/second per API key
Bulk operations: 10 concurrent operations
Media uploads: 50 MB max file size, 100 uploads/minute

Next Steps

Explore the API reference for detailed endpoint documentation, request/response schemas, and integration examples.

Getting Started

Endpoints

​Overview

​Integration Architecture

​EMR Clients

​Application Clients

​Getting Started

​Tenant Configuration

​Base URL

​Authentication

​Data Model & Hierarchy

​Multi-Tenant Architecture

​Core Entities

​Episodes

​Visits

​Media Processing

​Clinical Documentation Architecture

​Forms

​Medications

​Interventions

​Patient Goals

​Implementation Patterns

​EMR Integration Flow

​Application Client Flow

​Processing & Task Management

​Asynchronous Operations

​Response Format

​Error Responses

​Rate Limiting

​Next Steps

Overview

Integration Architecture

EMR Clients

Application Clients

Getting Started

Tenant Configuration

Base URL

Authentication

Data Model & Hierarchy

Multi-Tenant Architecture

Core Entities

Episodes

Visits

Media Processing

Clinical Documentation Architecture

Forms

Medications

Interventions

Patient Goals

Implementation Patterns

EMR Integration Flow

Application Client Flow

Processing & Task Management

Asynchronous Operations

Response Format

Error Responses

Rate Limiting

Next Steps