Getting Started

Welcome to the IntakeDesk documentation. This guide will walk you through the basics of setting up and using IntakeDesk to streamline your referral intake process.

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.

Example Code

Here is an example of how to install the necessary packages.

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: sk_...
```

API Reference

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

Referrals

Endpoint	Method	Description
/api/referrals?orgId=...	GET	List referrals for an organization.
/api/referrals	POST	Create a new referral. Returns a signed URL for file upload.
/api/referrals/:id	GET	Get a single referral by ID.
/api/referrals/:id/upload	POST	Upload an additional file to an existing referral.
/api/referrals/:id/process	POST	Trigger processing pipeline for a referral.
/api/referrals/:id/qa	POST	Run quality-assurance checks on extracted data.
/api/referrals/:id/triage	GET	Get current triage result for a referral.
/api/referrals/:id/triage	POST	Set or override triage classification.
/api/referrals/bulk	POST	Perform bulk actions (move to triaged, mark duplicate).
/api/referrals/export?orgId=...&stage=...	GET	Export referrals as CSV. Optional stage filter.

Cases

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

Endpoint	Method	Description
/api/cases/:caseId	PATCH	Update case fields (location, priority band, queue).
/api/cases/:caseId/contact	POST	Log a contact attempt, mark scheduled, close, or add a note.
/api/cases/match-referrer	POST	Match a case to an existing practice/provider and add alias.
/api/cases/create-referrer	POST	Create a new practice/provider from unmatched candidates.

Patients

Endpoint	Method	Description
/api/patients?orgId=...&q=...	GET	Search patients by name or ID.
/api/patients	POST	Create a new patient record.
/api/patients	PATCH	Update an existing patient record.
/api/patients	DELETE	Delete a patient record.

Documents

Endpoint	Method	Description
/api/referral-documents?orgId=...	GET	List documents for a referral or patient.
/api/referral-documents	POST	Attach a document to a referral/patient.
/api/referral-documents/sign-read	POST	Get a short-lived signed URL to read a document.
/api/referral-documents/update-status	PATCH	Update the processing status of a document.

Authentication

Session management and user profile endpoints for frontend clients.

Endpoint	Method	Description
/api/auth/me	GET	Get current authenticated user profile and org context.
/api/auth/session	POST	Create a session cookie from a Firebase ID token.
/api/auth/session	DELETE	Destroy the current session (logout).

Dashboard & Reporting

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

Endpoint	Method	Description
/api/backlog	GET	Backlog statistics with aging buckets and status breakdown.
/api/dashboard/overview-stats	GET	KPI overview stats for the dashboard.
/api/metrics	GET	Detailed operational metrics.
/api/mix	GET	Case mix / referral-type distribution.

Organization Config

Endpoint	Method	Description
/api/orgs/:id/config	PATCH	Update organization configuration settings.

API Keys (Management)

Endpoint	Method	Description
/api/api-keys	POST	Generate a new API Key (requires User Token).
/api/api-keys	GET	List active API Keys.
/api/api-keys	DELETE	Revoke an API Key.

EMR Integration

Queue-based chart creation for external EMR systems (e.g., NextGen). Cases are queued manually or automatically, then an external service polls and reports results. The poll and callback endpoints use API key authentication (X-Api-Key header).

Endpoint	Method	Description
/api/cases/:caseId/emr-queue	POST	Manually queue a case for EMR chart creation. Auth: Bearer token.
/api/emr/queue	GET	Poll pending queue items for chart creation. Returns denormalized patient/case data. Auth: API key.
/api/emr/queue/callback	POST	External service reports chart creation results (success/failed/error). Auth: API key.