Getting Started

Installation

To get started, you will need to install our client libraries and configure your environment. We provide packages for popular EMR systems and a REST API for custom integrations.

npm install @intakedesk/client

Configuration

To generate an API Key, use the POST /api/api-keys endpoint (authenticated via your Dashboard session) or contact support to enable the API Keys UI in your dashboard.

Authentication

The API supports two methods of authentication:

• Bearer Token: Standard Firebase ID Token. Used by frontend clients acting on behalf of a user.

  Authorization: Bearer <ID_TOKEN>

• API Key: Secret key for server-side integrations. Grants full access to the organization's resources.

  x-api-key: desk_...

API Reference

The IntakeDesk API provides endpoints for managing referrals, cases, patients, and documents. All endpoints require authentication.

Referrals

Cases

Cases are merged patient records created from one or more referrals. Use these endpoints to manage case lifecycle.

Patients

Documents

Authentication

Session management and user profile endpoints for frontend clients.

Dashboard & Reporting

Read-only endpoints for analytics, backlog monitoring, and operational metrics.

Organization Config

API Keys (Management)

EMR Integration

Queue-based chart creation and document delivery for external EMR systems (e.g., NextGen). Cases are queued manually or automatically, then an external service polls and reports results. When chart creation succeeds, source documents and a Case Summary PDF are automatically queued for delivery. All poll and callback endpoints use API key authentication (X-Api-Key header).

Retry behavior: Polling is read-only — items are not removed from the queue when polled. Every poll returns all non-completed items (both pending and processing). Items are only removed when a success callback is received. A failed/error callback keeps the item in the queue.

Poll Response Format — GET /api/emr/queue

{
  "orgId": "org_001",
  "items": [
    {
      "queueItemId": "abc123...",
      "orgId": "org_001",
      "caseId": "case_456...",
      "status": "pending",
        "patientId": "pat_789...",
        "firstName": "Jane",
        "lastName": "Doe",
        "dob": "1985-03-15",
        "sex": "F",
        "phone": "+15551234567",
        "email": "jane@example.com",
        "address": { "line1": "123 Main St", "city": "Anytown", "state": "CA", "zip": "90210" },
        "insurance": { "provider": "Blue Cross", "memberId": "XYZ123", "groupNumber": "GRP456" }
      },
      "referrer": { ... },
      "locationId": "loc_001",
      "emrLocationId": "EMR_LOC_42",
      "triageLevel": 1,
      "priorityBand": "P1"
    }
  ],
  "count": 1
}

Callback Request Format — POST /api/emr/queue/callback

{
  "orgId": "org_001",
  "results": [
    {
      "queueItemId": "abc123...",
      "status": "success",
      "emrChartId": "MRN12345",
      "message": null
    }
  ]
}

status: "success" | "failed" | "error". On success, include emrChartId (the patient MRN). On failed/error, include an optional message. Failed items revert to pending and will be re-polled.

Callback Response Format

{
  "processed": 1,
  "results": [
    { "queueItemId": "abc123...", "ok": true }
  ]
}

EMR Document Queue

After a patient chart is successfully created, source documents (referral faxes, labs, imaging) and a generated Case Summary PDF are automatically queued. The external service polls for pending documents, receives signed download URLs, and reports delivery results. Each document item includes the patient's mrn (Medical Record Number) for filing into the correct chart.

Retry behavior: Same as chart creation — polling is read-only and always returns all non-completed items. Download URLs are regenerated on each poll (15 min TTL).

Poll Response Format — GET /api/emr/document-queue

{
  "orgId": "org_001",
  "items": [
    {
      "queueItemId": "doc_abc...",
      "orgId": "org_001",
      "caseId": "case_456...",
      "mrn": "MRN12345",
      "status": "pending",
      "documentType": "source",
      "fileName": "referral_fax_001.pdf",
      "contentType": "application/pdf",
      "downloadUrl": "https://storage.googleapis.com/...?X-Goog-Signature=..."
    },
    {
      "queueItemId": "doc_def...",
      "orgId": "org_001",
      "caseId": "case_456...",
      "mrn": "MRN12345",
      "status": "pending",
      "documentType": "summary",
      "fileName": "Case_Summary.pdf",
      "contentType": "application/pdf",
      "downloadUrl": "https://storage.googleapis.com/...?X-Goog-Signature=..."
    }
  ],
  "count": 2
}

Callback Request Format — POST /api/emr/document-queue/callback

{
  "orgId": "org_001",
  "results": [
    { "queueItemId": "doc_abc...", "status": "success" },
    { "queueItemId": "doc_def...", "status": "failed", "message": "File upload timeout" }
  ]
}

status: "success" | "failed" | "error". Failed items revert to pending and will be re-polled with fresh download URLs.