# Cobalt API Documentation

> Cobalt provides a unified API for healthcare data, making it easy to read and write to any EHR (Electronic Health Record) system through a single integration.

## Key Concepts

- **Authentication**: All API requests require three headers: `client_id`, `client_secret`, and `access_token`. The access_token is obtained through the Cobalt Link flow.
- **Cobalt Link**: A drop-in UI component that lets healthcare organizations securely authenticate their EHR credentials. Flow: create a `link_token` → user completes Link → exchange `public_token` for a permanent `access_token`.
- **Asynchronous Operations**: Most write operations (create appointment, create patient, etc.) return a `job_id` immediately. Results are delivered via webhooks or can be polled using the Awaiting Results pattern.
- **Dual ID System**: Providers and locations have both a Cobalt `id` (used for Cobalt API management endpoints) and an `ehr_id` (used when referencing them in EMR operations like creating appointments).
- **Webhooks**: Real-time notifications with HMAC-SHA256 signature verification. Events follow a consistent structure: `{ id, access_token_reference_id, object, created, type, job_id, data }`. Failure events include structured error codes.
- **Awaiting Results (Polling)**: Alternative to webhooks. Poll `GET /v1/webhook-events?job_id={job_id}` at 1-second intervals with a 2-3 minute timeout.

## Guides

- [Introduction](https://docs.usecobalt.com/docs/introduction): Overview of Cobalt's unified healthcare API, features, and getting started
- [Link Overview](https://docs.usecobalt.com/docs/link/overview): How the Cobalt Link authentication flow works (link_token → Link UI → public_token → access_token)
- [Link Setup](https://docs.usecobalt.com/docs/link/setup): Implementation guide with JavaScript/React code examples for Lightbox and New Window modes
- [Link Update Mode](https://docs.usecobalt.com/docs/link/update-mode): Re-authentication for existing connections when login_required errors occur
- [Webhooks Overview](https://docs.usecobalt.com/docs/webhooks/overview): Webhook basics, HTTPS requirements, secret rotation, and best practices
- [Webhooks Setup](https://docs.usecobalt.com/docs/webhooks/setup): Register, retrieve, and remove webhooks with example requests
- [Receiving Webhooks](https://docs.usecobalt.com/docs/webhooks/receiving): Signature verification using HMAC-SHA256 with code examples
- [Operation Events](https://docs.usecobalt.com/docs/webhooks/operation-events): Events fired when Cobalt performs an RPA action in the EHR — appointment/patient/task/note/document/message/telephone_encounter created and failed events, structured error codes
- [Sync Events](https://docs.usecobalt.com/docs/webhooks/sync-events): Events fired when Cobalt detects changes EHR staff made directly — appointment.created/updated/status_updated and patient.updated
- [Account Events](https://docs.usecobalt.com/docs/webhooks/account-events): Events fired when an end-user's stored EHR credentials need attention — access_token.login_required and access_token.password_change_warning
- [Awaiting Results Overview](https://docs.usecobalt.com/docs/awaiting-results/overview): Polling-based alternative to webhooks for tracking operation results
- [Awaiting Results Implementation](https://docs.usecobalt.com/docs/awaiting-results/implementation): Full polling code examples in JavaScript, Python, and cURL
- [Awaiting Results Best Practices](https://docs.usecobalt.com/docs/awaiting-results/best-practices): Recommended poll intervals (1s), timeouts (2-3 min), and when to use webhooks vs polling

## API Reference

### Link

- [Create Link Token](https://docs.usecobalt.com/api-reference/link/create-token): `POST /link/token/create` — Create a link_token with user_id, org_id, optional EMR details. Use access_token param for update mode.
- [Exchange Token](https://docs.usecobalt.com/api-reference/link/exchange-token): `GET /link/token/exchange` — Exchange a public_token for a permanent access_token.

### Account

- [Activate Account](https://docs.usecobalt.com/api-reference/account/activate): `POST /account/activate` — Activate a deactivated account.
- [Deactivate Account](https://docs.usecobalt.com/api-reference/account/deactivate): `POST /account/deactivate` — Deactivate an active account.
- [Last Schedule Sync](https://docs.usecobalt.com/api-reference/system/last-schedule-sync): `GET /last-schedule-sync` — Returns timestamp of last successful schedule sync from the EMR.

### Appointments

- [Create Appointment](https://docs.usecobalt.com/api-reference/appointments/create): `POST /appointments` — Create an appointment with datetime (ISO 8601 or separate date/time), mrn, location, provider, type, note, reason. Returns job_id. Async — results via webhook.
- [List Appointments](https://docs.usecobalt.com/api-reference/appointments/get): `GET /appointments` — List appointments with filtering and pagination.
- [Get Appointment](https://docs.usecobalt.com/api-reference/appointments/get-by-id): `GET /appointments/{id}` — Full appointment details: datetime, mode, type, location, patient, provider, insurance, status.
- [Update Appointment](https://docs.usecobalt.com/api-reference/appointments/update): `PATCH /appointments/{id}` — Update pending/failed appointments (any field) or scheduled appointments (status/note only).
- [Fetch Appointments](https://docs.usecobalt.com/api-reference/appointments/fetch): `POST /appointments/fetch` — Live fetch appointment data from the EMR for a date range. Async with webhook completion.

### Patients

- [Create Patient](https://docs.usecobalt.com/api-reference/patients/create): `POST /patients` — Create patient with demographics, insurance, referring provider, PCP. Returns patient_id and job_id. Async — webhook includes MRN on success.
- [List Patients](https://docs.usecobalt.com/api-reference/patients/get): `GET /patients` — List patients with first_name/last_name filtering. Pagination: default 30, max 100.
- [Update Patient](https://docs.usecobalt.com/api-reference/patients/update): `PATCH /patients/{id}` — Update pending/failed patients with demographic or insurance fields.
- [Fetch Patient](https://docs.usecobalt.com/api-reference/patients/fetch): `POST /patients/fetch` — Live fetch from EMR including medications (name, strength, frequency) and pharmacies.
- [Add Patient Insurance](https://docs.usecobalt.com/api-reference/patients/insurances/add): `POST /patients/{patient_mrn}/insurances` — Add insurance with three resolution methods (provider ID, name+payer_id, name only). Supports priority levels and relationship codes.

### Providers

- [List Providers](https://docs.usecobalt.com/api-reference/providers/get): `GET /providers` — Returns Cobalt id, ehr_id, status, NPI, timezone, schedule with shifts and visit type rules.
- [Update Provider](https://docs.usecobalt.com/api-reference/providers/update): `PATCH /providers/{id}` — Update status, hide_in_availability, working hours, facility_id, date ranges (by Cobalt ID).
- [Update Provider by EHR ID](https://docs.usecobalt.com/api-reference/providers/update-by-ehr): `PATCH /providers/ehr/{ehr_id}` — Same as above but using the EMR's provider ID.

### Availability

- [Get Availability](https://docs.usecobalt.com/api-reference/availability/get): `GET /availability` — Query by start_date, end_date, buffer (minutes), visit_type, calculation_method (gaps/slots/equal_slots). Returns time slots with provider, facility, duration. Only includes active providers with hide_in_availability=false.

### Locations

- [List Locations](https://docs.usecobalt.com/api-reference/locations/get): `GET /locations` — Returns Cobalt id, ehr_id, name, address, phone, fax, status.
- [Update Location](https://docs.usecobalt.com/api-reference/locations/update): `PATCH /locations/{id}` — Update status (active/inactive).

### Visit Configuration

- [List Visit Types](https://docs.usecobalt.com/api-reference/visit-types/get): `GET /visit-types` — Available visit type codes and descriptions (e.g., AWV, BH Visit).
- [List Visit Statuses](https://docs.usecobalt.com/api-reference/visit-statuses/get): `GET /visit-statuses` — Available appointment status codes (e.g., CANC, R/S) for use in appointment updates.

### Insurance

- [Search Insurance Providers](https://docs.usecobalt.com/api-reference/insurance-providers/get): `GET /insurance-providers` — Search by name with pagination. Returns id (for add insurance), name, payer_id, active status.

### Pharmacies

- [List Pharmacies](https://docs.usecobalt.com/api-reference/pharmacies/get): `GET /pharmacies` — Returns Cobalt id, ehr_id, address, phone, email, status.

### Referring Providers

- [List Referring Providers](https://docs.usecobalt.com/api-reference/referring-providers/get): `GET /referring-providers` — Filter by first_name, last_name, phone, fax, NPI. Returns id, ehr_id, specialty, contact info.
- [Create Referring Provider](https://docs.usecobalt.com/api-reference/referring-providers/create): `POST /referring-providers` — Required: first_name, last_name, npi. Phone/fax format: XXX-XXX-XXXX. Returns referring_provider_id and job_id.

### Clinical Operations

- [Create Note](https://docs.usecobalt.com/api-reference/notes/create): `POST /notes` — Create note with appointment_id, content (string or structured object for eCW), optional ICD-10 and CPT codes. Async with webhook.
- [Upload Document](https://docs.usecobalt.com/api-reference/documents/upload): `POST /documents` — Multipart upload with folder_name, patient_mrn, and document file. Returns document_id. Async with webhook.
- [Send Message](https://docs.usecobalt.com/api-reference/messages/create): `POST /messages` — Send message to provider with provider ehr_id, subject, and message content.
- [Create Task](https://docs.usecobalt.com/api-reference/tasks/create): `POST /tasks` — Create task with description, patient_mrn, subject, assignee. Returns task_id and job_id.

### Telephone Encounters

- [Create Telephone Encounter](https://docs.usecobalt.com/api-reference/telephone-encounters/create): `POST /telephone-encounters` — Create encounter with patient_mrn, provider_id, location_id, assigned_to_id. Optional: reason, refill_medication_name, pharmacy, caller, message, priority. Async with webhook.
- [Create Encounter Action](https://docs.usecobalt.com/api-reference/telephone-encounters/create-action): `POST /telephone-encounters/actions` — Add timestamped action to existing encounter with emr_appointment_id and action text.

### Claims & Orders

- [List Claims](https://docs.usecobalt.com/api-reference/claims/get): `GET /claims` — Query by date range. Returns claim number, status, PDF URLs, service date, patient, insurance details.
- [List Orders](https://docs.usecobalt.com/api-reference/orders/get): `GET /orders` — Query by patient_mrn and date range. Returns lab/imaging orders with type, status, ordered_date.

### Webhooks Management

- [Create Webhook](https://docs.usecobalt.com/api-reference/webhooks/create): `POST /webhook` — Register a webhook endpoint. Returns webhook_id and signing secret.
- [List Webhooks](https://docs.usecobalt.com/api-reference/webhooks/get): `GET /webhook` — List all configured webhook URLs.
- [Delete Webhook](https://docs.usecobalt.com/api-reference/webhooks/delete): `DELETE /webhook/{id}` — Remove a webhook.
- [Rotate Secret](https://docs.usecobalt.com/api-reference/webhooks/rotate-secret): `POST /webhook/{id}/rotate-secret` — Rotate signing secret. Previous secret remains valid for 24 hours.
- [Get Webhook Events](https://docs.usecobalt.com/api-reference/webhook-events/get): `GET /webhook-events` — Query events by job_id, event_type, delivery_status, date range. Pagination: default 50, max 100.
- [Get Webhook Event by ID](https://docs.usecobalt.com/api-reference/webhook-events/get-by-id): `GET /webhook-events/{id}` — Retrieve a specific webhook event with audit trail.

### Settings

- [Get Settings](https://docs.usecobalt.com/api-reference/settings/get): `GET /settings` — Returns access_token_reference_id, visit_types, visit_statuses, required_patient_fields, timezone.
- [Update Settings](https://docs.usecobalt.com/api-reference/settings/update): `POST /settings` — Update access_token_reference_id.

## Common Patterns

### Creating an Appointment (End-to-End)
1. `GET /providers` to find the provider's `ehr_id`
2. `GET /locations` to find the location's `ehr_id`
3. `GET /visit-types` to find valid visit type codes
4. `GET /availability` to find open slots
5. `POST /appointments` with the above details — returns `job_id`
6. Listen for `appointment.created` webhook or poll `GET /webhook-events?job_id={job_id}`

### Creating a Patient (End-to-End)
1. `POST /patients` with demographics — returns `patient_id` and `job_id`
2. Listen for `patient.created` webhook — includes the EMR-assigned `mrn`
3. Optionally `POST /patients/{mrn}/insurances` to add insurance

### Authentication Flow
1. `POST /link/token/create` with `user_id` and `org_id` — returns `link_token`
2. Initialize Cobalt Link UI with the `link_token`
3. User completes EHR authentication in Link
4. `GET /link/token/exchange?public_token={token}` — returns permanent `access_token`