{ "openapi": "3.1.0", "info": { "title": "Cobalt API", "version": "1.0.1", "description": "API for interacting with Cobalt's EHR integration services" }, "servers": [ { "url": "https://api.usecobalt.com/v1", "description": "Production" } ], "security": [ { "ClientCredentials": [], "ClientSecret": [], "AccessToken": [] } ], "components": { "responses": { "BadRequest": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "message": { "type": "string", "example": "Request could not be completed." } }, "required": ["success", "message"] }, "example": { "success": false, "message": "Bad request — missing or invalid parameters" } } } }, "Unauthorized": { "description": "Unauthorized — missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "message": { "type": "string", "example": "Request could not be completed." } }, "required": ["success", "message"] }, "example": { "success": false, "message": "Unauthorized — missing or invalid credentials" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "message": { "type": "string", "example": "Request could not be completed." } }, "required": ["success", "message"] }, "example": { "success": false, "message": "Resource not found" } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "message": { "type": "string", "example": "Request could not be completed." } }, "required": ["success", "message"] }, "example": { "success": false, "message": "Internal server error" } } } } }, "securitySchemes": { "ClientCredentials": { "type": "apiKey", "in": "header", "name": "client_id" }, "ClientSecret": { "type": "apiKey", "in": "header", "name": "client_secret" }, "AccessToken": { "type": "apiKey", "in": "header", "name": "access_token" } }, "schemas": { "WebhookEventType": { "type": "string", "description": "The type of webhook event. New types can be added at any time, so clients must accept values that are not listed. Each `x-cobalt-event-types` entry's `category` is the `action` its deliveries carry.", "example": "appointment.created", "x-extensible-enum": [ "access_token.login_required", "access_token.password_change_warning", "appointment.created", "appointment.deleted", "appointment.failed", "appointment.live_fetch_completed", "appointment.status_updated", "appointment.update_failed", "appointment.updated", "availability.created", "availability.failed", "availability.live_fetch_completed", "claim.created", "claim.failed", "claim.updated", "codes.added", "codes.failed", "codes.removed", "document.created", "document.updated", "document.upload_failed", "document.uploaded", "encounter.created", "encounter.failed", "encounter.update_failed", "encounter.updated", "fee_schedules.synced", "forms.synced", "lab_result.create_failed", "lab_result.created", "message.created", "message.failed", "note.failed", "note.uploaded", "order.create_failed", "order.created", "order.update_failed", "order.updated", "order_catalog.search_failed", "order_catalog.searched", "org_settings.synced", "patient.created", "patient.deleted", "patient.failed", "patient.insurance.added", "patient.insurance.created", "patient.insurance.eligibility_completed", "patient.insurance.eligibility_started", "patient.insurance.failed", "patient.insurance.updated", "patient.live_fetch_completed", "patient.update_failed", "patient.updated", "patient_note.created", "patient_note.failed", "payment.created", "payment.failed", "pharmacies.synced", "recall.created", "recall.failed", "recall_action.created", "recall_action.failed", "referral.created", "referral.failed", "referral.updated", "referring_provider.created", "referring_provider.failed", "task.created", "task.failed", "task_note.created", "task_note.failed", "telephone_encounter.created", "telephone_encounter.created_partial", "telephone_encounter.failed", "telephone_encounter.updated", "telephone_encounter_action.created", "telephone_encounter_action.failed", "test.event" ], "x-cobalt-event-types": [ { "eventName": "access_token.login_required", "category": "cobalt_operation", "description": "Sent when an access token requires the user to log in again." }, { "eventName": "access_token.password_change_warning", "category": "cobalt_operation", "description": "Sent when an access token password is about to expire or must be changed." }, { "eventName": "appointment.created", "category": "cobalt_operation", "description": "Appointment created by Cobalt" }, { "eventName": "appointment.created", "category": "ehr_sync", "description": "Appointment created in EHR" }, { "eventName": "appointment.failed", "category": "cobalt_operation", "description": "Cobalt failed to create appointment" }, { "eventName": "appointment.deleted", "category": "ehr_sync", "description": "Sent when an appointment is deleted in the EHR." }, { "eventName": "appointment.live_fetch_completed", "category": "cobalt_operation", "description": "Sent when an on-demand appointment fetch completes." }, { "eventName": "appointment.status_updated", "category": "ehr_sync", "description": "Appointment status updated in EHR" }, { "eventName": "appointment.updated", "category": "cobalt_operation", "description": "Appointment updated by Cobalt" }, { "eventName": "appointment.updated", "category": "ehr_sync", "description": "Appointment updated in EHR" }, { "eventName": "appointment.update_failed", "category": "cobalt_operation", "description": "Cobalt failed to update appointment" }, { "eventName": "availability.created", "category": "cobalt_operation", "description": "Sent when availability is created in the EHR." }, { "eventName": "availability.failed", "category": "cobalt_operation", "description": "Sent when availability creation in the EHR fails." }, { "eventName": "availability.live_fetch_completed", "category": "cobalt_operation", "description": "Sent when an on-demand availability fetch completes." }, { "eventName": "claim.created", "category": "ehr_sync", "description": "Sent when a new claim is synced from the EHR." }, { "eventName": "claim.created", "category": "cobalt_operation", "description": "Sent when a claim is created in the EHR." }, { "eventName": "claim.failed", "category": "cobalt_operation", "description": "Sent when claim creation in the EHR fails." }, { "eventName": "claim.updated", "category": "ehr_sync", "description": "Sent when a synced claim's fields change in the EHR." }, { "eventName": "codes.added", "category": "cobalt_operation", "description": "Sent when clinical codes are added to an encounter." }, { "eventName": "codes.failed", "category": "cobalt_operation", "description": "Sent when a clinical-code add/remove operation fails." }, { "eventName": "codes.removed", "category": "cobalt_operation", "description": "Sent when clinical codes are removed from an encounter." }, { "eventName": "document.created", "category": "ehr_sync", "description": "Sent when a new document is synced from the EHR." }, { "eventName": "document.updated", "category": "ehr_sync", "description": "Sent when a document is updated during an EHR sync." }, { "eventName": "document.uploaded", "category": "cobalt_operation", "description": "Sent when a document is uploaded to the EHR." }, { "eventName": "document.upload_failed", "category": "cobalt_operation", "description": "Sent when a document upload to the EHR fails." }, { "eventName": "fee_schedules.synced", "category": "ehr_sync", "description": "Sent when a fee schedules sync completes." }, { "eventName": "forms.synced", "category": "ehr_sync", "description": "Sent when a forms sync (EHR form definitions: categories, questions, answers) completes." }, { "eventName": "message.created", "category": "cobalt_operation", "description": "Sent when a message is created in the EHR." }, { "eventName": "message.failed", "category": "cobalt_operation", "description": "Sent when message creation in the EHR fails." }, { "eventName": "note.failed", "category": "cobalt_operation", "description": "Sent when a note upload to the EHR fails." }, { "eventName": "note.uploaded", "category": "cobalt_operation", "description": "Note uploaded by Cobalt" }, { "eventName": "lab_result.created", "category": "cobalt_operation", "description": "Sent when a lab result is created in the EHR." }, { "eventName": "lab_result.create_failed", "category": "cobalt_operation", "description": "Sent when lab result creation in the EHR fails." }, { "eventName": "order.created", "category": "cobalt_operation", "description": "Sent when an order is created in the EHR." }, { "eventName": "order.create_failed", "category": "cobalt_operation", "description": "Sent when order creation in the EHR fails." }, { "eventName": "order.updated", "category": "cobalt_operation", "description": "Sent when an order is updated in the EHR." }, { "eventName": "order.update_failed", "category": "cobalt_operation", "description": "Sent when an order update in the EHR fails." }, { "eventName": "order_catalog.searched", "category": "cobalt_operation", "description": "Sent when an order catalog search completes." }, { "eventName": "order_catalog.search_failed", "category": "cobalt_operation", "description": "Sent when an order catalog search fails." }, { "eventName": "org_settings.synced", "category": "ehr_sync", "description": "Sent when an organization settings sync (providers, locations, visit types, etc.) completes." }, { "eventName": "patient.created", "category": "cobalt_operation", "description": "Patient created by Cobalt" }, { "eventName": "patient.created", "category": "ehr_sync", "description": "Patient created in EHR" }, { "eventName": "patient.deleted", "category": "ehr_sync", "description": "Sent when a patient is deleted in the EHR." }, { "eventName": "patient.failed", "category": "cobalt_operation", "description": "Sent when patient creation in the EHR fails." }, { "eventName": "patient.insurance.added", "category": "cobalt_operation", "description": "Cobalt added insurance to patient" }, { "eventName": "patient.insurance.created", "category": "cobalt_operation", "description": "Sent when patient insurance is created in the EHR." }, { "eventName": "patient.insurance.eligibility_completed", "category": "cobalt_operation", "description": "Sent when a patient insurance eligibility check completes." }, { "eventName": "patient.insurance.eligibility_started", "category": "cobalt_operation", "description": "Sent when a patient insurance eligibility check starts." }, { "eventName": "patient.insurance.failed", "category": "cobalt_operation", "description": "Cobalt failed to add insurance to patient" }, { "eventName": "patient.insurance.updated", "category": "cobalt_operation", "description": "Sent when patient insurance is updated in the EHR." }, { "eventName": "patient.updated", "category": "cobalt_operation", "description": "Sent when a patient is updated in the EHR." }, { "eventName": "patient.live_fetch_completed", "category": "cobalt_operation", "description": "Sent when an on-demand patient fetch completes." }, { "eventName": "patient_note.created", "category": "cobalt_operation", "description": "Sent when a patient note is created in the EHR." }, { "eventName": "patient_note.failed", "category": "cobalt_operation", "description": "Sent when patient note creation in the EHR fails." }, { "eventName": "payment.created", "category": "cobalt_operation", "description": "Sent when a payment is created in the EHR." }, { "eventName": "payment.failed", "category": "cobalt_operation", "description": "Sent when payment creation in the EHR fails." }, { "eventName": "patient.updated", "category": "ehr_sync", "description": "Patient updated in EHR" }, { "eventName": "patient.update_failed", "category": "cobalt_operation", "description": "Sent when patient update in the EHR fails." }, { "eventName": "pharmacies.synced", "category": "ehr_sync", "description": "Sent when a pharmacies sync completes." }, { "eventName": "recall_action.created", "category": "cobalt_operation", "description": "Sent when an action is logged on a recall." }, { "eventName": "recall_action.failed", "category": "cobalt_operation", "description": "Sent when a recall action operation fails." }, { "eventName": "recall.created", "category": "cobalt_operation", "description": "Sent when a recall is created in the EHR." }, { "eventName": "recall.failed", "category": "cobalt_operation", "description": "Sent when a recall create operation fails." }, { "eventName": "referral.created", "category": "cobalt_operation", "description": "Sent when a referral is created in the EHR." }, { "eventName": "referral.created", "category": "ehr_sync", "description": "Sent when a new referral is synced from the EHR." }, { "eventName": "referral.failed", "category": "cobalt_operation", "description": "Sent when referral creation or update in the EHR fails." }, { "eventName": "referral.updated", "category": "cobalt_operation", "description": "Sent when a referral is updated in the EHR." }, { "eventName": "referral.updated", "category": "ehr_sync", "description": "Sent when a referral is updated during an EHR sync." }, { "eventName": "referring_provider.created", "category": "cobalt_operation", "description": "Sent when a referring provider is created in the EHR." }, { "eventName": "referring_provider.failed", "category": "cobalt_operation", "description": "Sent when referring provider creation in the EHR fails." }, { "eventName": "encounter.created", "category": "cobalt_operation", "description": "Sent when a encounter is created in the EHR." }, { "eventName": "encounter.failed", "category": "cobalt_operation", "description": "Sent when encounter creation in the EHR fails." }, { "eventName": "encounter.updated", "category": "cobalt_operation", "description": "Sent when an encounter is updated (approved) in the EHR." }, { "eventName": "encounter.update_failed", "category": "cobalt_operation", "description": "Sent when an encounter update (approve) in the EHR fails." }, { "eventName": "task.created", "category": "cobalt_operation", "description": "Sent when a task is created in the EHR." }, { "eventName": "task.failed", "category": "cobalt_operation", "description": "Sent when task creation in the EHR fails." }, { "eventName": "task_note.created", "category": "cobalt_operation", "description": "Sent when a task note is created in the EHR." }, { "eventName": "task_note.failed", "category": "cobalt_operation", "description": "Sent when task note creation in the EHR fails." }, { "eventName": "test.event", "category": "cobalt_operation", "description": "Sent when a configured webhook endpoint is tested." }, { "eventName": "telephone_encounter_action.created", "category": "cobalt_operation", "description": "Sent when a telephone encounter action is created in the EHR." }, { "eventName": "telephone_encounter_action.failed", "category": "cobalt_operation", "description": "Sent when telephone encounter action creation in the EHR fails." }, { "eventName": "telephone_encounter.created", "category": "cobalt_operation", "description": "Telephone Encounter created by Cobalt" }, { "eventName": "telephone_encounter.created_partial", "category": "cobalt_operation", "description": "Telephone Encounter created by Cobalt but medication refill failed" }, { "eventName": "telephone_encounter.failed", "category": "cobalt_operation", "description": "Cobalt failed to create telephone encounter" }, { "eventName": "telephone_encounter.updated", "category": "ehr_sync", "description": "Sent when a telephone encounter is updated during an EHR sync." } ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique webhook delivery ID." }, "object": { "type": "string" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "action": { "type": "string", "enum": ["cobalt_operation", "ehr_sync"] }, "created": { "type": "string" }, "timestamp": { "type": "string" }, "access_token_id": { "type": "string" }, "access_token_reference_id": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["id", "type", "data"], "additionalProperties": {}, "description": "An event delivered by Cobalt to a configured webhook URL. Event-specific data is contained in data.", "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "object": "event", "type": "appointment.created", "action": "cobalt_operation", "created": "2026-09-17T18:24:05.000Z", "timestamp": "2026-09-17T18:24:05.000Z", "access_token_id": "b7c4f1d2-8a3e-4b56-9c01-2d3e4f5a6b7c", "access_token_reference_id": "account-42", "data": { "appointment_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "patient_mrn": "12345" } } }, "FormMetadata": { "type": "object", "properties": { "id": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "emr_form_id": { "type": "string", "example": "form-123" }, "emr_fvid": { "type": ["string", "null"], "example": "form-version-1" }, "name": { "type": "string", "example": "Patient intake" }, "type": { "type": ["string", "null"], "example": "intake" }, "version": { "type": ["string", "null"], "example": "1" }, "status": { "type": ["string", "null"], "example": "active" }, "build_date": { "type": ["string", "null"], "example": "2026-01-01" }, "synced_at": { "type": ["string", "null"], "example": "2026-06-15T21:30:00Z" }, "created_at": { "type": ["string", "null"], "example": "2026-06-15T21:30:00Z" }, "updated_at": { "type": ["string", "null"], "example": "2026-06-15T21:30:00Z" } }, "required": [ "id", "emr_form_id", "emr_fvid", "name", "type", "version", "status", "build_date", "synced_at", "created_at", "updated_at" ] }, "Form": { "allOf": [ { "$ref": "#/components/schemas/FormMetadata" }, { "type": "object", "properties": { "definition": { "$ref": "#/components/schemas/FormDefinition" } }, "required": ["definition"] } ] }, "FormDefinition": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "example": [ { "name": "Medical history", "questions": [ { "label": "Current medications", "type": "text" } ] } ] } }, "required": ["categories"] }, "PatientInsurance": { "type": "object", "properties": { "emr_insurance_id": { "type": "string", "description": "EMR insurance record ID. Pass to PATCH /v1/patients/{patient_mrn}/insurances/{emr_insurance_id}." }, "priority": { "type": "integer", "description": "1 = primary, 2 = secondary, 3 = tertiary." }, "insurance_ehr_id": { "type": ["string", "null"], "description": "EMR ID of the insurance company / plan." }, "insurance_name": { "type": ["string", "null"], "description": "Insurance company / package name." }, "insurance_policy_type": { "type": ["string", "null"], "description": "Insurance policy / package type." }, "insurance_subscriber_number": { "type": ["string", "null"], "description": "Insurance member / policy ID number." }, "group_id": { "type": ["string", "null"], "description": "Insurance group number." }, "plan_begin_date": { "type": ["string", "null"], "format": "date", "description": "Coverage start date." }, "plan_end_date": { "type": ["string", "null"], "format": "date", "description": "Coverage end date." }, "copayment": { "type": ["string", "null"], "description": "Copayment amount." }, "relationship_to_subscriber": { "type": ["string", "null"], "description": "Patient relationship to the policy holder." }, "guarantor_id": { "type": ["string", "null"], "description": "EMR guarantor ID." }, "is_guarantor_patient": { "type": "boolean", "description": "Whether the patient is the guarantor." }, "active_status": { "type": "string", "description": "EMR active status of the policy." }, "eligibility_status": { "type": "string", "description": "Last eligibility status." } }, "required": ["emr_insurance_id", "priority"], "example": { "emr_insurance_id": "51638", "priority": 1, "insurance_ehr_id": "insurance-provider-123", "insurance_name": "Blue Cross Anthem", "insurance_policy_type": "PPO", "insurance_subscriber_number": "INS123456789", "group_id": "GRP98999", "plan_begin_date": "2026-01-01", "plan_end_date": "2026-12-31", "copayment": "25", "relationship_to_subscriber": "self", "guarantor_id": "guarantor-123", "is_guarantor_patient": true, "active_status": "active", "eligibility_status": "eligible" } } }, "parameters": {} }, "paths": { "/account/activate": { "post": { "operationId": "activateAccount", "summary": "Activate account", "description": "Reactivates the account so its sync jobs run and webhooks are delivered again.", "tags": ["Account"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Account activated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account activated" } }, "required": ["success", "message"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/account/deactivate": { "post": { "operationId": "deactivateAccount", "summary": "Deactivate account", "description": "Deactivates the account so its sync jobs stop running and webhooks are no longer delivered.", "tags": ["Account"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Account deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account deactivated" } }, "required": ["success", "message"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/access-token/rotate": { "post": { "operationId": "rotateAccessToken", "summary": "Rotate access token", "description": "Rotates the access token, invalidating the old token immediately and returning the new one.", "tags": ["Account"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Access token rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Access token rotated" }, "access_token": { "type": "string", "example": "access-token-example-not-valid" } }, "required": ["success", "message", "access_token"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/credentials/{credentialId}/enable": { "patch": { "operationId": "enableCredential", "summary": "Enable a credential", "description": "Re-enables a previously disabled credential set.", "tags": ["Account"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "parameters": [ { "name": "credentialId", "in": "path", "description": "Credential set ID (UUID).", "schema": { "type": "string", "example": "3f1c2a5e-9b7d-4c21-8f0a-6d5e4b3a2c10" }, "required": true } ], "responses": { "200": { "description": "Credential enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Credential enabled" } }, "required": ["success", "message"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/credentials/{credentialId}/disable": { "patch": { "operationId": "disableCredential", "summary": "Disable a credential", "description": "Disables a credential set so it is no longer used for EMR sessions (the last active set cannot be disabled).", "tags": ["Account"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "parameters": [ { "name": "credentialId", "in": "path", "description": "Credential set ID (UUID).", "schema": { "type": "string", "example": "3f1c2a5e-9b7d-4c21-8f0a-6d5e4b3a2c10" }, "required": true } ], "responses": { "200": { "description": "Credential disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Credential disabled" } }, "required": ["success", "message"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/credentials/{credentialId}": { "delete": { "operationId": "deleteCredential", "summary": "Delete a credential", "description": "Deletes a credential set (the last active set cannot be deleted).", "tags": ["Account"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "parameters": [ { "name": "credentialId", "in": "path", "description": "Credential set ID (UUID).", "schema": { "type": "string", "example": "3f1c2a5e-9b7d-4c21-8f0a-6d5e4b3a2c10" }, "required": true } ], "responses": { "200": { "description": "Credential deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Credential deleted" } }, "required": ["success", "message"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/client/rotate-secret": { "post": { "operationId": "rotateClientSecret", "summary": "Rotate client secret", "description": "Rotates the client secret. The previous secret remains valid for 24 hours.", "tags": ["Account"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Client secret rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Client secret rotated" }, "client_secret": { "type": "string", "example": "client-secret-example-not-valid" }, "previous_secret_expires_at": { "type": "string", "example": "2026-06-16T21:30:00Z" } }, "required": [ "success", "message", "client_secret", "previous_secret_expires_at" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/client/lock": { "post": { "operationId": "lockAccount", "summary": "Lock account", "description": "Locks the account: invalidates the client secret, EMR sessions, and access tokens, and deactivates users. Contact support to unlock.", "tags": ["Account"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Account locked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account locked" }, "data": { "type": "object", "properties": { "cookies_invalidated": { "type": "integer", "example": 1 }, "tokens_deactivated": { "type": "integer", "example": 1 }, "users_deactivated": { "type": "integer", "example": 1 }, "locked_at": { "type": "string", "example": "2026-06-15T21:30:00Z" } } } }, "required": ["success", "message", "data"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/appointments/{appointment_id}/codes": { "post": { "operationId": "addAppointmentCodes", "summary": "Add appointment codes", "description": "Queues an operation to add ICD-10 diagnosis codes to an appointment. A webhook event is sent on completion.", "tags": ["Appointments"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "appointment_id", "in": "path", "description": "Cobalt appointment ID.", "schema": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["codes"], "properties": { "codes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Code system. Currently only \"icd10\".", "example": "icd10" }, "code": { "type": "string", "description": "The diagnosis code value.", "example": "R51" }, "add_to_problem_list": { "type": "string", "description": "When \"true\", also add this diagnosis to the patient Problem List, not just the encounter assessment (matches the eCW \"PL\" checkbox). One of: \"true\", \"false\". Defaults to \"false\". Ignored on remove. eClinicalWorks only." } }, "required": ["type", "code"] }, "x-supported-emrs": ["eClinicalWorks"], "description": "ICD-10 diagnosis codes to add or remove. CPT/procedure codes are not yet supported.", "example": [ { "type": "icd10", "code": "R51" } ], "x-required-for-emrs": ["eClinicalWorks"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this operation, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Operation queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation queued for processing" }, "job_id": { "type": "integer", "example": 12345 } }, "required": ["success", "message", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "removeAppointmentCodes", "summary": "Remove appointment codes", "description": "Queues an operation to remove ICD-10 diagnosis codes from an appointment. A webhook event is sent on completion.", "tags": ["Appointments"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "appointment_id", "in": "path", "description": "Cobalt appointment ID.", "schema": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["codes"], "properties": { "codes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Code system. Currently only \"icd10\".", "example": "icd10" }, "code": { "type": "string", "description": "The diagnosis code value.", "example": "R51" }, "add_to_problem_list": { "type": "string", "description": "When \"true\", also add this diagnosis to the patient Problem List, not just the encounter assessment (matches the eCW \"PL\" checkbox). One of: \"true\", \"false\". Defaults to \"false\". Ignored on remove. eClinicalWorks only." } }, "required": ["type", "code"] }, "x-supported-emrs": ["eClinicalWorks"], "description": "ICD-10 diagnosis codes to add or remove. CPT/procedure codes are not yet supported.", "example": [ { "type": "icd10", "code": "R51" } ], "x-required-for-emrs": ["eClinicalWorks"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this operation, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Operation queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation queued for processing" }, "job_id": { "type": "integer", "example": 12345 } }, "required": ["success", "message", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/appointments": { "post": { "operationId": "createAppointment", "summary": "Create an appointment", "description": "Queues an appointment for creation in the connected EMR.", "tags": ["Appointments"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mrn": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Patient MRN. One of mrn or patient_name is required (bespoke check).", "example": "12345" }, "patient_name": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Patient name, used when the MRN is not known.", "example": "Jane Doe" }, "location": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "EMR location ID. Validated against the account's locations.", "example": "location-1" }, "datetime": { "type": "string", "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Appointment start as an ISO 8601 datetime. Provide either datetime, or date and time.", "example": "2026-06-15T14:30:00-07:00" }, "date": { "type": "string", "format": "date", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Appointment date (YYYY-MM-DD). Used together with time.", "example": "2026-06-15" }, "time": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Appointment time (h:mm am/pm). Used together with date.", "example": "2:30 pm" }, "timezone": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "IANA time zone name (e.g. \"America/Chicago\") to book the appointment in, overriding the account timezone. Use for eClinicalWorks instances whose facilities span multiple time zones: the datetime (or date and time) is interpreted in this zone and booked at that exact facility-local wall-clock time. Omit to use the account timezone.", "example": "America/Chicago" }, "provider": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Rendering provider EMR ID. Validated against the account's providers.", "example": "provider-123" }, "secondary_provider": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Secondary provider / resource EMR ID. Sent to the EMR by eClinicalWorks and PTPracticePro only; for every EMR it is stored and counts toward that provider's availability.", "example": "provider-456", "x-required-for-emrs": ["PTPracticePro"] }, "type": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Visit type code. Validated against the account's visit types.", "example": "NP" }, "note": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "WebPt", "Credible" ], "description": "Appointment note as a plain string.", "example": "Purpose of visit: Annual checkup" }, "duration": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": [ "eClinicalWorks", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Appointment duration in minutes, as a positive integer.", "example": "30", "x-required-when": { "eClinicalWorks": [ { "field": "skip_visit_type_validation", "equals": "true" } ] } }, "reason": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Reason for the visit.", "example": "Annual checkup" }, "billing_note": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Billing note to set on the appointment. Read it back with the appointment_notes include on the fetch endpoints.", "example": "Copay collected at check-in" }, "check_eligibility": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": [], "description": "Whether to run an eligibility check on creation. Accepted, but no EMR uses it, so it has no effect.", "example": "false" }, "complaint_type": { "type": "string", "x-supported-emrs": ["EZDERM"], "description": "Complaint type ID. Validated against the account's complaint types.", "example": "complaint-123", "x-required-for-emrs": ["EZDERM"] }, "prevent_double_booking": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks", "PracticeFusion"], "description": "Whether to reject the appointment if the slot is already booked.", "example": "true" }, "max_overlapping_appointments": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "With prevent_double_booking, reject only when the requested time already overlaps this many patient visits for the provider. A visit counts if any part of it falls inside the requested start to end; cancelled and rescheduled visits do not count. Schedule blocks always reject. Defaults to 1.", "example": "2" }, "skip_visit_type_validation": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Skip visit-type validation. Requires duration, since the visit type is not read.", "example": "false" }, "skip_confidential_charts": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Fail the appointment instead of creating it when the patient chart is confidential (restricted) for the connected user.", "example": "false" }, "include_inactive_patients": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Also match a patient chart that is inactive in the EMR when looking up the patient. By default only active charts are matched.", "example": "false" }, "new_patient": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA" ], "description": "Whether the patient is new.", "example": "true" }, "practice_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "eClinicalWorks practice ID (for multi-practice provider/location pairs).", "example": "practice-1" }, "department_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "eClinicalWorks department ID, validated against the synced departments.", "example": "department-1" }, "non_billable": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Whether the appointment is non-billable.", "example": "false" }, "recall_id": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "Cobalt recall ID to link the new appointment to (from GET /v1/recalls).", "example": "recall-abc-123" }, "callback_urls": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "Credible" ], "description": "URL(s) to receive the completion webhook for this appointment, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Appointment queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Appointment queued for creation" }, "appointment_id": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "job_id": { "type": "integer", "example": 12345 } }, "required": ["success", "message", "appointment_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An appointment already exists for this patient/date/time", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false] }, "message": { "type": "string", "example": "An appointment already exists for this patient/date/time" }, "appointment_id": { "type": "null" } }, "required": ["success", "message", "appointment_id"] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getAppointments", "summary": "List appointments", "description": "Returns the appointments Cobalt has synced for the account, filtered by date range and optional criteria.", "tags": ["Appointments"], "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ], "parameters": [ { "name": "start_date", "in": "query", "description": "Start of the date range (YYYY-MM-DD). Not needed when emr_appointment_id is supplied.", "schema": { "type": "string", "format": "date", "example": "2026-06-15" }, "required": true, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "end_date", "in": "query", "description": "End of the date range (YYYY-MM-DD). Not needed when emr_appointment_id is supplied.", "schema": { "type": "string", "format": "date", "example": "2026-06-15" }, "required": true, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "patient_mrn", "in": "query", "description": "Filter by patient MRN.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "patient_phone", "in": "query", "description": "Filter by patient phone.", "schema": { "type": "string", "example": "555-123-4567" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "patient_dob", "in": "query", "description": "Filter by patient date of birth (YYYY-MM-DD).", "schema": { "type": "string", "format": "date", "example": "1980-01-15" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "patient_name", "in": "query", "description": "Filter by patient name.", "schema": { "type": "string", "example": "Jane Doe" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "include_note", "in": "query", "description": "Include the appointment note in each result.", "schema": { "type": "string", "enum": ["true", "false"], "example": "true" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "appointment_mode", "in": "query", "description": "Appointment mode filter.", "schema": { "type": "string", "example": "office" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "category", "in": "query", "description": "Comma-separated allowlist of Cobalt record categories to return: 'appointment' (real appointments), 'schedule_slot' (open availability), 'schedule_block' (blocked time). Any subset is allowed, e.g. 'schedule_slot,schedule_block'. Distinct from appointment_type (the EHR visit type). Defaults to 'appointment' when omitted.", "schema": { "type": "string", "example": "appointment,schedule_slot" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "include_schedule_blocks", "in": "query", "description": "Deprecated. Use `category` instead. When true, schedule blocks are included alongside real appointments (equivalent to category='appointment,schedule_block'). Ignored when `category` is supplied.", "schema": { "type": "string", "enum": ["true", "false"], "deprecated": true, "example": "false" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "status", "in": "query", "description": "Filter by appointment status.", "schema": { "type": "string", "example": "cancelled" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "provider_ehr_id", "in": "query", "description": "Filter by rendering provider EMR ID.", "schema": { "type": "string", "example": "provider-123" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "location_ehr_id", "in": "query", "description": "Filter by location EMR ID.", "schema": { "type": "string", "example": "location-1" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "appointment_type", "in": "query", "description": "Filter by visit type.", "schema": { "type": "string", "example": "NP" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "secondary_provider_ehr_id", "in": "query", "description": "Filter by secondary provider EMR ID.", "schema": { "type": "string", "example": "provider-456" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] }, { "name": "emr_appointment_id", "in": "query", "description": "Look up a single appointment by its EMR appointment ID (makes start_date / end_date optional).", "schema": { "type": "string", "example": "appt-emr-789" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ] } ], "responses": { "200": { "description": "Appointments for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "appointments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt appointment ID (dashless UUID)." }, "datetime": { "type": ["string", "null"], "format": "date-time", "description": "Appointment start in the account's timezone." }, "local_datetime": { "type": ["string", "null"], "description": "Appointment start as the EHR wall-clock time, no offset (e.g. \"2026-10-14T10:00:00.000\"). Apply the location's timezone to get the instant." }, "status": { "type": "string", "description": "Appointment status." }, "reason": { "type": ["string", "null"], "description": "Reason for the visit." }, "schedule_block_label": { "type": ["string", "null"], "description": "Human-readable label for a schedule block (e.g. \"OUT\", \"SAME DAY\"). Populated only on schedule_block rows; null otherwise." }, "schedule_block_color": { "type": ["string", "null"], "description": "Schedule block color as a #RRGGBB hex string. Populated only on schedule_block rows; null otherwise." }, "note": { "type": "string", "description": "Appointment note (plain text). Present on the list only when include_note=true." }, "location": { "type": ["string", "null"], "description": "EMR location ID." }, "appointment_type": { "type": ["string", "null"], "description": "EHR visit type (from type_description)." }, "appointment_mode": { "type": "string", "description": "Appointment mode (e.g. office, telehealth)." }, "complaint_type": { "type": ["string", "null"], "description": "Complaint type." }, "duration": { "type": ["integer", "null"], "description": "Appointment duration in minutes." }, "ehr_appointment_id": { "type": "string", "description": "EHR appointment ID." }, "emr_appointment_id": { "type": "string", "description": "EMR appointment ID (alias of ehr_appointment_id)." }, "provider_ehr_id": { "type": ["string", "null"], "description": "Rendering provider EMR ID." }, "provider_name": { "type": ["string", "null"], "description": "Rendering provider name." }, "provider_npi": { "type": "string", "description": "Rendering provider NPI." }, "secondary_provider_ehr_id": { "type": ["string", "null"], "description": "Secondary rendering provider EMR ID." }, "patient_first_name": { "type": "string", "description": "Patient first name." }, "patient_last_name": { "type": "string", "description": "Patient last name." }, "patient_phone": { "type": "string", "description": "Patient phone." }, "patient_name": { "type": ["string", "null"], "description": "Patient name as stored on the appointment (EMR patient ID)." }, "patient_mrn": { "type": "string", "description": "Patient MRN." }, "patient_ehr_id": { "type": "string", "description": "Patient EHR ID." }, "patient_dob": { "type": ["string", "null"], "description": "Patient date of birth (YYYY-MM-DD)." }, "patient_gender": { "type": ["string", "null"], "description": "Patient gender." }, "insurance": { "type": ["string", "null"], "description": "Primary insurance name." }, "insurances": { "type": ["array", "null"], "items": { "type": "object", "properties": { "insurance_id": { "type": ["string", "null"], "description": "EMR insurance record ID." }, "name": { "type": ["string", "null"], "description": "Payer/plan name." }, "subscriber_number": { "type": ["string", "null"], "description": "Member ID." }, "group_number": { "type": ["string", "null"], "description": "Group number. Empty when the EMR has none." }, "start_date": { "type": ["string", "null"], "description": "Coverage start date (MM/DD/YYYY)." }, "end_date": { "type": ["string", "null"], "description": "Coverage end date (MM/DD/YYYY). Empty when open-ended." }, "active_status": { "type": ["string", "null"], "description": "Active flag as the EMR reports it ('A' / 'I', or '1' / '0')." }, "sequence_number": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "description": "Coverage order: 1 = primary, 2 = secondary, 3 = tertiary." }, "sequence_description": { "type": ["string", "null"], "description": "'primary', 'secondary', 'tertiary', or 'other'." }, "subscriber_name": { "type": ["string", "null"], "description": "Name of the insured person." } }, "required": [ "insurance_id", "name", "subscriber_number", "group_number", "active_status", "sequence_number", "sequence_description", "subscriber_name" ], "additionalProperties": {} }, "description": "The patient's current insurance coverages, ordered by sequence_number." }, "insurance_subscriber": { "type": ["string", "null"], "description": "Primary insurance subscriber name." }, "insurance_number": { "type": ["string", "null"], "description": "Primary insurance member number." }, "insurance_group_number": { "type": ["string", "null"], "description": "Primary insurance group number." }, "secondary_insurance": { "type": ["string", "null"], "description": "Secondary insurance name." }, "secondary_insurance_number": { "type": ["string", "null"], "description": "Secondary insurance member number." }, "diagnoses": { "type": ["array", "null"], "items": { "type": "object", "additionalProperties": {} }, "description": "Diagnosis records." }, "medications": { "type": ["array", "null"], "items": { "type": "object", "additionalProperties": {} }, "description": "Medication records." }, "progress_note": { "type": ["string", "null"], "description": "Progress note content. Present on the list only when include_note=true." }, "practice_id": { "type": ["string", "null"], "description": "Practice ID." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "Record creation timestamp." }, "object_metadata": { "type": "object", "properties": { "source": { "type": "string", "description": "Record origin: ehr_sync, cobalt_operation, or unknown." }, "created_at": { "type": "string", "format": "date-time", "description": "When a cobalt_operation created the record (present only for that source)." } }, "required": ["source"], "description": "Provenance metadata for the record." } }, "example": { "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "datetime": "2026-06-15T14:30:00-07:00", "local_datetime": "2026-06-15T14:30:00.000", "status": "cancelled", "reason": "Annual checkup", "schedule_block_label": null, "schedule_block_color": null, "note": "Purpose of visit: Annual checkup", "location": "location-1", "appointment_type": "NP", "appointment_mode": "office", "complaint_type": "complaint-123", "duration": 30, "ehr_appointment_id": "appt-emr-789", "emr_appointment_id": "appt-emr-789", "provider_ehr_id": "provider-123", "provider_name": "Dr. Alex Smith", "provider_npi": "1234567890", "secondary_provider_ehr_id": "provider-456", "patient_first_name": "Jane", "patient_last_name": "Doe", "patient_phone": "555-123-4567", "patient_name": "12345", "patient_mrn": "12345", "patient_ehr_id": "12345", "patient_dob": "1980-01-15", "patient_gender": "female", "insurance": "Blue Cross Anthem", "insurances": [ { "insurance_id": "51638", "name": "Blue Cross Anthem", "subscriber_number": "MEM123456789", "group_number": "GRP98999", "start_date": "01/01/2026", "end_date": "", "active_status": "A", "sequence_number": 1, "sequence_description": "primary", "subscriber_name": "Jane Doe" } ], "insurance_subscriber": "Jane Doe", "insurance_number": "MEM123456789", "insurance_group_number": "GRP98999", "secondary_insurance": null, "secondary_insurance_number": null, "diagnoses": [ { "code": "R51", "description": "Headache" } ], "medications": [ { "name": "Lisinopril 10mg" } ], "progress_note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.", "practice_id": "practice-1", "created_at": "2026-06-01T16:00:00Z", "object_metadata": { "source": "cobalt_operation", "created_at": "2026-06-01T16:00:00Z" } } }, "example": [ { "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "datetime": "2026-06-15T14:30:00-07:00", "local_datetime": "2026-06-15T14:30:00.000", "status": "cancelled", "reason": "Annual checkup", "schedule_block_label": null, "schedule_block_color": null, "note": "Purpose of visit: Annual checkup", "location": "location-1", "appointment_type": "NP", "appointment_mode": "office", "complaint_type": "complaint-123", "duration": 30, "ehr_appointment_id": "appt-emr-789", "emr_appointment_id": "appt-emr-789", "provider_ehr_id": "provider-123", "provider_name": "Dr. Alex Smith", "provider_npi": "1234567890", "secondary_provider_ehr_id": "provider-456", "patient_first_name": "Jane", "patient_last_name": "Doe", "patient_phone": "555-123-4567", "patient_name": "12345", "patient_mrn": "12345", "patient_ehr_id": "12345", "patient_dob": "1980-01-15", "patient_gender": "female", "insurance": "Blue Cross Anthem", "insurances": [ { "insurance_id": "51638", "name": "Blue Cross Anthem", "subscriber_number": "MEM123456789", "group_number": "GRP98999", "start_date": "01/01/2026", "end_date": "", "active_status": "A", "sequence_number": 1, "sequence_description": "primary", "subscriber_name": "Jane Doe" } ], "insurance_subscriber": "Jane Doe", "insurance_number": "MEM123456789", "insurance_group_number": "GRP98999", "secondary_insurance": null, "secondary_insurance_number": null, "diagnoses": [ { "code": "R51", "description": "Headache" } ], "medications": [ { "name": "Lisinopril 10mg" } ], "progress_note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.", "practice_id": "practice-1", "created_at": "2026-06-01T16:00:00Z", "object_metadata": { "source": "cobalt_operation", "created_at": "2026-06-01T16:00:00Z" } } ] }, "warnings": { "type": "array", "items": { "type": "string" }, "example": [] } }, "required": ["success", "appointments"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/appointments/{id}": { "patch": { "operationId": "updateAppointment", "summary": "Update an appointment", "description": "Queues an update (status, note, or, for failed appointments, retry fields) for an existing appointment.", "tags": ["Appointments"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt appointment ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "New appointment status. Validated against the account's visit statuses.", "example": "cancelled", "x-required-when": { "ModmedEMA": [ { "field": "note", "present": true } ], "WebPt": [ { "field": "note", "present": true } ] } }, "note": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "ModmedEMA", "ModmedGastro", "PracticeFusion", "WebPt", "Credible" ], "description": "Replacement appointment note.", "example": "Purpose of visit: Annual checkup" }, "cancellation_reason": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Reason for a cancel / no-show / reschedule. Must accompany a status change to Cancelled, Rescheduled, or No Show, and must match one of the practice's configured reasons (eClinicalWorks only).", "example": "Patient Illness" }, "confirmation_method": { "type": "string", "x-supported-emrs": ["PracticeFusion"], "description": "Confirmation method code, passed through to PracticeFusion as-is. Must accompany a status change to Confirmed (PracticeFusion only).", "example": "LPV" }, "type": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "New visit type code. On a scheduled appointment, eClinicalWorks only.", "example": "NP" }, "duration": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "New duration in minutes. On a scheduled appointment, updatable only together with type (eClinicalWorks only).", "example": "30" }, "skip_visit_type_validation": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Skip visit-type validation on a type update (eClinicalWorks only).", "example": "false" }, "skip_confidential_charts": { "type": "string", "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Fail the update instead of applying it when the patient chart is confidential (restricted) for the connected user. Must accompany another update field (eClinicalWorks only).", "example": "false" }, "provider": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "New rendering provider EMR ID. On a scheduled appointment, eClinicalWorks only.", "example": "provider-123" }, "secondary_provider": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "New secondary provider / resource EMR ID. On a scheduled appointment, eClinicalWorks only.", "example": "provider-456" }, "practice_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "eClinicalWorks practice ID.", "example": "practice-1" }, "mrn": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Patient MRN (retry of a failed appointment only).", "example": "12345" }, "datetime": { "type": "string", "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "New appointment datetime, ISO 8601 (retry of a failed appointment only).", "example": "2026-06-15T14:30:00-07:00" }, "callback_urls": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "URL(s) to receive the completion webhook for this update.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt", "Credible" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Appointment update queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Appointment update queued" }, "appointment_id": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "job_id": { "type": "integer", "example": 12345 } }, "required": ["success", "message", "appointment_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getAppointmentById", "summary": "Get an appointment", "description": "Returns a single synced appointment by its Cobalt ID.", "tags": ["Appointments"], "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt appointment ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "required": true } ], "responses": { "200": { "description": "The requested appointment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "appointment": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt appointment ID (dashless UUID)." }, "datetime": { "type": ["string", "null"], "format": "date-time", "description": "Appointment start in the account's timezone." }, "local_datetime": { "type": ["string", "null"], "description": "Appointment start as the EHR wall-clock time, no offset (e.g. \"2026-10-14T10:00:00.000\"). Apply the location's timezone to get the instant." }, "status": { "type": "string", "description": "Appointment status." }, "reason": { "type": ["string", "null"], "description": "Reason for the visit." }, "schedule_block_label": { "type": ["string", "null"], "description": "Human-readable label for a schedule block (e.g. \"OUT\", \"SAME DAY\"). Populated only on schedule_block rows; null otherwise." }, "schedule_block_color": { "type": ["string", "null"], "description": "Schedule block color as a #RRGGBB hex string. Populated only on schedule_block rows; null otherwise." }, "note": { "type": "string", "description": "Appointment note (plain text). Present on the list only when include_note=true." }, "location": { "type": ["string", "null"], "description": "EMR location ID." }, "appointment_type": { "type": ["string", "null"], "description": "EHR visit type (from type_description)." }, "appointment_mode": { "type": "string", "description": "Appointment mode (e.g. office, telehealth)." }, "complaint_type": { "type": ["string", "null"], "description": "Complaint type." }, "duration": { "type": ["integer", "null"], "description": "Appointment duration in minutes." }, "ehr_appointment_id": { "type": "string", "description": "EHR appointment ID." }, "emr_appointment_id": { "type": "string", "description": "EMR appointment ID (alias of ehr_appointment_id)." }, "provider_ehr_id": { "type": ["string", "null"], "description": "Rendering provider EMR ID." }, "provider_name": { "type": ["string", "null"], "description": "Rendering provider name." }, "provider_npi": { "type": "string", "description": "Rendering provider NPI." }, "secondary_provider_ehr_id": { "type": ["string", "null"], "description": "Secondary rendering provider EMR ID." }, "patient_first_name": { "type": "string", "description": "Patient first name." }, "patient_last_name": { "type": "string", "description": "Patient last name." }, "patient_phone": { "type": "string", "description": "Patient phone." }, "patient_name": { "type": ["string", "null"], "description": "Patient name as stored on the appointment (EMR patient ID)." }, "patient_mrn": { "type": "string", "description": "Patient MRN." }, "patient_ehr_id": { "type": "string", "description": "Patient EHR ID." }, "patient_dob": { "type": ["string", "null"], "description": "Patient date of birth (YYYY-MM-DD)." }, "patient_gender": { "type": ["string", "null"], "description": "Patient gender." }, "insurance": { "type": ["string", "null"], "description": "Primary insurance name." }, "insurances": { "type": ["array", "null"], "items": { "type": "object", "properties": { "insurance_id": { "type": ["string", "null"], "description": "EMR insurance record ID." }, "name": { "type": ["string", "null"], "description": "Payer/plan name." }, "subscriber_number": { "type": ["string", "null"], "description": "Member ID." }, "group_number": { "type": ["string", "null"], "description": "Group number. Empty when the EMR has none." }, "start_date": { "type": ["string", "null"], "description": "Coverage start date (MM/DD/YYYY)." }, "end_date": { "type": ["string", "null"], "description": "Coverage end date (MM/DD/YYYY). Empty when open-ended." }, "active_status": { "type": ["string", "null"], "description": "Active flag as the EMR reports it ('A' / 'I', or '1' / '0')." }, "sequence_number": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "description": "Coverage order: 1 = primary, 2 = secondary, 3 = tertiary." }, "sequence_description": { "type": ["string", "null"], "description": "'primary', 'secondary', 'tertiary', or 'other'." }, "subscriber_name": { "type": ["string", "null"], "description": "Name of the insured person." } }, "required": [ "insurance_id", "name", "subscriber_number", "group_number", "active_status", "sequence_number", "sequence_description", "subscriber_name" ], "additionalProperties": {} }, "description": "The patient's current insurance coverages, ordered by sequence_number." }, "insurance_subscriber": { "type": ["string", "null"], "description": "Primary insurance subscriber name." }, "insurance_number": { "type": ["string", "null"], "description": "Primary insurance member number." }, "insurance_group_number": { "type": ["string", "null"], "description": "Primary insurance group number." }, "secondary_insurance": { "type": ["string", "null"], "description": "Secondary insurance name." }, "secondary_insurance_number": { "type": ["string", "null"], "description": "Secondary insurance member number." }, "diagnoses": { "type": ["array", "null"], "items": { "type": "object", "additionalProperties": {} }, "description": "Diagnosis records." }, "medications": { "type": ["array", "null"], "items": { "type": "object", "additionalProperties": {} }, "description": "Medication records." }, "progress_note": { "type": ["string", "null"], "description": "Progress note content. Present on the list only when include_note=true." }, "practice_id": { "type": ["string", "null"], "description": "Practice ID." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "Record creation timestamp." }, "object_metadata": { "type": "object", "properties": { "source": { "type": "string", "description": "Record origin: ehr_sync, cobalt_operation, or unknown." }, "created_at": { "type": "string", "format": "date-time", "description": "When a cobalt_operation created the record (present only for that source)." } }, "required": ["source"], "description": "Provenance metadata for the record." } }, "example": { "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "datetime": "2026-06-15T14:30:00-07:00", "local_datetime": "2026-06-15T14:30:00.000", "status": "cancelled", "reason": "Annual checkup", "schedule_block_label": null, "schedule_block_color": null, "note": "Purpose of visit: Annual checkup", "location": "location-1", "appointment_type": "NP", "appointment_mode": "office", "complaint_type": "complaint-123", "duration": 30, "ehr_appointment_id": "appt-emr-789", "emr_appointment_id": "appt-emr-789", "provider_ehr_id": "provider-123", "provider_name": "Dr. Alex Smith", "provider_npi": "1234567890", "secondary_provider_ehr_id": "provider-456", "patient_first_name": "Jane", "patient_last_name": "Doe", "patient_phone": "555-123-4567", "patient_name": "12345", "patient_mrn": "12345", "patient_ehr_id": "12345", "patient_dob": "1980-01-15", "patient_gender": "female", "insurance": "Blue Cross Anthem", "insurances": [ { "insurance_id": "51638", "name": "Blue Cross Anthem", "subscriber_number": "MEM123456789", "group_number": "GRP98999", "start_date": "01/01/2026", "end_date": "", "active_status": "A", "sequence_number": 1, "sequence_description": "primary", "subscriber_name": "Jane Doe" } ], "insurance_subscriber": "Jane Doe", "insurance_number": "MEM123456789", "insurance_group_number": "GRP98999", "secondary_insurance": null, "secondary_insurance_number": null, "diagnoses": [ { "code": "R51", "description": "Headache" } ], "medications": [ { "name": "Lisinopril 10mg" } ], "progress_note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.", "practice_id": "practice-1", "created_at": "2026-06-01T16:00:00Z", "object_metadata": { "source": "cobalt_operation", "created_at": "2026-06-01T16:00:00Z" } } } }, "required": ["success", "appointment"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/appointments/fetch": { "post": { "operationId": "liveFetchAppointments", "summary": "Live-fetch appointments", "description": "Queues an on-demand fetch of appointments from the EMR. Results are delivered via webhook.", "tags": ["Appointments"], "x-supported-emrs": ["eClinicalWorks", "Credible", "ModmedGastro"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "search_by": { "type": "string", "default": "date_range", "enum": ["date_range", "mrn", "provider"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro" ], "description": "Search mode. Defaults to date_range.", "example": "date_range", "x-allowed-values-for-emrs": { "ModmedGastro": ["date_range", "provider"] } }, "start_date": { "type": "string", "format": "date", "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro" ], "description": "Start of the date range (YYYY-MM-DD). Required for date_range and provider modes.", "example": "2026-06-15" }, "end_date": { "type": "string", "format": "date", "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro" ], "description": "End of the date range (YYYY-MM-DD). Required for date_range and provider modes.", "example": "2026-06-15" }, "mrn": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Patient MRN. Required for mrn mode.", "example": "12345" }, "provider_ids": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro" ], "description": "EMR provider IDs (1-10). Required for provider mode.", "example": ["PROV-1"] }, "include": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "enum": [ "ehr_audit_log", "appointment_notes", "referral", "progress_note", "insurances", "schedule_blocks" ], "x-supported-emrs": ["eClinicalWorks"], "description": "Additional data to enrich each appointment with, as a comma-separated string or an array of tokens. Works in every search mode. Accepted tokens depend on the EMR (see x-allowed-values-for-emrs). ehr_audit_log returns the appointment change history (who changed which field from what to what, and when) plus created_at and created_by; one log lookup per appointment. schedule_blocks also returns schedule block rows (appointment_type schedule_block, with schedule_block_label and schedule_block_color); not supported with search_by=mrn.", "example": "ehr_audit_log", "x-allowed-values-for-emrs": { "eClinicalWorks": [ "ehr_audit_log", "appointment_notes", "referral", "progress_note", "insurances", "schedule_blocks" ] } }, "callback_urls": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro" ], "description": "URL(s) to receive the completion webhook for this live fetch.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Live fetch request accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Live fetch request accepted" }, "job_id": { "type": "integer", "example": 12345 } }, "required": ["success", "message"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/availability": { "get": { "operationId": "getAvailability", "summary": "Get computed availability", "description": "Returns open scheduling slots computed from synced provider hours and booked appointments over a date range.", "tags": ["Availability"], "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ], "parameters": [ { "name": "start_date", "in": "query", "description": "Range start (ISO 8601 / YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-15" }, "required": true, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "end_date", "in": "query", "description": "Range end (ISO 8601 / YYYY-MM-DD). Must be on/after start_date and within 12 months.", "schema": { "type": "string", "example": "2026-03-20" }, "required": true, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "provider_ids", "in": "query", "description": "Comma-separated EMR provider IDs to filter by.", "schema": { "type": "string", "example": "PROV-1,PROV-2" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "location_ids", "in": "query", "description": "Comma-separated EMR location IDs to filter slots by.", "schema": { "type": "string", "example": "LOC-1,LOC-2" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "buffer", "in": "query", "description": "Minutes of buffer between slots (0–59).", "schema": { "type": ["integer", "null"], "minimum": 0, "example": 15 }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "visit_type", "in": "query", "description": "Visit-type code to size slots for. Requires buffer.", "schema": { "type": "string", "example": "FOLLOW-UP" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "calculation_method", "in": "query", "description": "Slot calculation method.", "schema": { "type": "string", "enum": ["gaps", "slots", "equal_slots"], "default": "gaps", "example": "gaps" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "daily_appointment_limit", "in": "query", "description": "Max appointments per day. Requires daily_limit_type.", "schema": { "type": ["integer", "null"], "minimum": 1, "example": 8 }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "daily_limit_type", "in": "query", "description": "Visit-type code the daily limit applies to. Requires daily_appointment_limit.", "schema": { "type": "string", "example": "all" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "provider_type", "in": "query", "description": "Which provider slot to match on.", "schema": { "type": "string", "enum": ["primary", "secondary"], "example": "primary" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "fallback_to_default_hours", "in": "query", "description": "Use default business hours when a provider has no configured hours.", "schema": { "type": "string", "enum": ["true", "false"], "example": "false" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "max_slot_duration", "in": "query", "description": "Cap on slot length in minutes (5–60, multiples of 5).", "schema": { "type": ["integer", "null"], "example": 30 }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "facility_scoped_scheduling", "in": "query", "description": "Scope slots per facility rather than per provider (auto-enabled for Practice Fusion).", "schema": { "type": "string", "enum": ["true", "false"], "example": "true" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "cancelled_statuses", "in": "query", "description": "Comma-separated appointment statuses to treat as cancelled, freeing the slot. When provided, this overrides the default cancelled/rescheduled detection. The default detection treats \"c\", \"cancelled\", \"canc\", \"rescheduled\", \"r/s\" and \"deleted\" as cancelled (PTPracticePro uses \"3\" in place of \"c\"); for eClinicalWorks it also treats any status containing \"canc\", \"r/s\" or \"resched\" as cancelled. Statuses are matched case-insensitively. To keep the default detection and add your own statuses, use additional_cancelled_statuses instead.", "schema": { "type": "string", "example": "canc,rs,cancsms" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "additional_cancelled_statuses", "in": "query", "description": "Comma-separated appointment statuses to treat as cancelled in addition to the default cancelled/rescheduled detection (or to cancelled_statuses, when provided); statuses are matched case-insensitively. Use this to add custom status codes without losing the defaults.", "schema": { "type": "string", "example": "no show,bumped" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] } ], "responses": { "200": { "description": "Computed availability for the requested range", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "availability": { "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "description": "Day of week the slot falls on (Luxon weekday, 1=Mon..7=Sun).", "example": 5 }, "date": { "type": "string", "description": "Slot date (ISO 8601 date).", "example": "2024-04-05" }, "duration_string": { "type": "string", "description": "Human-readable slot duration.", "example": "540m" }, "range_start": { "type": "string", "description": "Slot start (ISO 8601).", "example": "2024-04-05T08:00:00.000-07:00" }, "range_end": { "type": "string", "description": "Slot end (ISO 8601).", "example": "2024-04-05T17:00:00.000-07:00" }, "provider_id": { "type": "string", "description": "EMR provider ID the slot belongs to.", "example": "provider-123" }, "visit_type": { "type": "string", "description": "Appointment type bookable in this slot, when the schedule provides one.", "example": "New Patient" }, "available_appointments": { "type": "integer", "description": "Remaining bookable appointments in this slot. Present only when the EHR provides detailed slot capacity.", "example": 3 }, "max_visits": { "type": "integer", "description": "Total capacity of this slot. Present only when the EHR provides detailed slot capacity.", "example": 5 }, "facility_id": { "type": "string", "description": "EMR facility/location ID, when available in the EHR.", "example": "1" }, "facility_name": { "type": "string", "description": "Facility/location name, when available in the EHR.", "example": "Main St Clinic" } }, "required": [ "day_of_week", "date", "duration_string", "range_start", "range_end", "provider_id" ], "example": { "day_of_week": 5, "date": "2024-04-05", "duration_string": "540m", "range_start": "2024-04-05T08:00:00.000-07:00", "range_end": "2024-04-05T17:00:00.000-07:00", "provider_id": "provider-123", "visit_type": "New Patient", "available_appointments": 3, "max_visits": 5, "facility_id": "1", "facility_name": "Main St Clinic" } }, "example": [ { "day_of_week": 5, "date": "2024-04-05", "duration_string": "540m", "range_start": "2024-04-05T08:00:00.000-07:00", "range_end": "2024-04-05T17:00:00.000-07:00", "provider_id": "provider-123", "visit_type": "New Patient", "available_appointments": 3, "max_visits": 5, "facility_id": "1", "facility_name": "Main St Clinic" } ] }, "timezone": { "type": "string", "example": "America/Los_Angeles" }, "warnings": { "type": "array", "items": { "type": "string" }, "example": [] } }, "required": ["success", "availability", "timezone"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createAvailabilityLegacy", "summary": "Create an availability block (legacy, synchronous)", "description": "Creates an availability block in the connected EMR and returns the result synchronously. Superseded by POST /v1/availabilities.", "tags": ["Availability"], "deprecated": true, "x-supported-emrs": ["TheraNest"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "staff_id", "start_datetime", "end_datetime", "location_ids", "appointment_types", "all_service_types" ], "properties": { "title": { "type": "string", "x-supported-emrs": ["TheraNest"], "description": "Title for the availability block (max 255 characters).", "example": "Morning Openings", "x-required-for-emrs": ["TheraNest"] }, "staff_id": { "type": "string", "x-supported-emrs": ["TheraNest"], "description": "EMR staff/provider ID the availability belongs to.", "example": "STAFF-123", "x-required-for-emrs": ["TheraNest"] }, "start_datetime": { "type": "string", "format": "date-time", "x-supported-emrs": ["TheraNest"], "description": "Block start, ISO 8601 with timezone offset (e.g. 2026-03-15T09:30:00-08:00).", "example": "2026-03-15T09:30:00-08:00", "x-required-for-emrs": ["TheraNest"] }, "end_datetime": { "type": "string", "format": "date-time", "x-supported-emrs": ["TheraNest"], "description": "Block end, ISO 8601 with timezone offset. Must be after start_datetime; block is 5 minutes to 24 hours long.", "example": "2026-03-15T14:30:00-08:00", "x-required-for-emrs": ["TheraNest"] }, "location_ids": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["TheraNest"], "description": "EMR location IDs the block applies to (1–50).", "example": ["LOC-1"], "x-required-for-emrs": ["TheraNest"] }, "appointment_types": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["TheraNest"], "description": "Appointment delivery types: in_person and/or telehealth.", "example": ["in_person"], "x-required-for-emrs": ["TheraNest"] }, "all_service_types": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "x-supported-emrs": ["TheraNest"], "description": "Whether the block accepts all service types. When false, service_type_ids is required.", "example": true, "x-required-for-emrs": ["TheraNest"] }, "service_type_ids": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["TheraNest"], "description": "EMR service type IDs (max 100). Required when all_service_types is false.", "example": ["SVC-1"] }, "client_scheduling_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "x-supported-emrs": ["TheraNest"], "description": "Allow clients to self-schedule into this block.", "example": true }, "client_referral_scheduling_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "x-supported-emrs": ["TheraNest"], "description": "Allow client referrals to schedule into this block.", "example": false }, "recurrence": { "type": "object", "properties": { "type": { "type": "string", "description": "Recurrence frequency: daily, weekly, or monthly.", "example": "weekly" }, "interval": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "description": "Repeat every N periods (positive integer).", "example": 1 }, "days": { "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "ISO weekday numbers (1=Monday … 7=Sunday). Required when type is \"weekly\".", "example": [1, 3, 5] }, "end": { "type": "object", "properties": { "type": { "type": "string", "description": "How the recurrence ends: date, count, or never.", "example": "count" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Ending date (YYYY-MM-DD) when type is \"date\", or occurrence count when type is \"count\".", "example": 12 } } } }, "x-supported-emrs": ["TheraNest"], "description": "Optional recurrence rule. Omit for a one-off block. See field descriptions for per-type requirements.", "example": { "type": "weekly", "interval": 1, "days": [1, 3, 5], "end": { "type": "count", "value": 12 } } }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": [], "description": "URLs to receive the completion webhook, in addition to the account webhook. Accepted, but no EMR uses it, so it has no effect.", "example": ["https://example.com/webhooks/cobalt"] } } } } } }, "responses": { "200": { "description": "Availability block created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Availability block created" }, "availability_id": { "type": "string", "example": "availability-123" }, "staff_id": { "type": "string", "example": "STAFF-123" } }, "required": [ "success", "message", "availability_id", "staff_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/availabilities": { "post": { "operationId": "createAvailability", "summary": "Create an availability block", "description": "Queues an availability block for creation in the connected EMR. A webhook event is sent on completion.", "tags": ["Availability"], "x-supported-emrs": ["TheraNest"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "staff_id", "start_datetime", "end_datetime", "location_ids", "appointment_types", "all_service_types" ], "properties": { "title": { "type": "string", "x-supported-emrs": ["TheraNest"], "description": "Title for the availability block (max 255 characters).", "example": "Morning Openings", "x-required-for-emrs": ["TheraNest"] }, "staff_id": { "type": "string", "x-supported-emrs": ["TheraNest"], "description": "EMR staff/provider ID the availability belongs to.", "example": "STAFF-123", "x-required-for-emrs": ["TheraNest"] }, "start_datetime": { "type": "string", "format": "date-time", "x-supported-emrs": ["TheraNest"], "description": "Block start, ISO 8601 with timezone offset (e.g. 2026-03-15T09:30:00-08:00).", "example": "2026-03-15T09:30:00-08:00", "x-required-for-emrs": ["TheraNest"] }, "end_datetime": { "type": "string", "format": "date-time", "x-supported-emrs": ["TheraNest"], "description": "Block end, ISO 8601 with timezone offset. Must be after start_datetime; block is 5 minutes to 24 hours long.", "example": "2026-03-15T14:30:00-08:00", "x-required-for-emrs": ["TheraNest"] }, "location_ids": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["TheraNest"], "description": "EMR location IDs the block applies to (1–50).", "example": ["LOC-1"], "x-required-for-emrs": ["TheraNest"] }, "appointment_types": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["TheraNest"], "description": "Appointment delivery types: in_person and/or telehealth.", "example": ["in_person"], "x-required-for-emrs": ["TheraNest"] }, "all_service_types": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "x-supported-emrs": ["TheraNest"], "description": "Whether the block accepts all service types. When false, service_type_ids is required.", "example": true, "x-required-for-emrs": ["TheraNest"] }, "service_type_ids": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["TheraNest"], "description": "EMR service type IDs (max 100). Required when all_service_types is false.", "example": ["SVC-1"] }, "client_scheduling_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "x-supported-emrs": ["TheraNest"], "description": "Allow clients to self-schedule into this block.", "example": true }, "client_referral_scheduling_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "x-supported-emrs": ["TheraNest"], "description": "Allow client referrals to schedule into this block.", "example": false }, "recurrence": { "type": "object", "properties": { "type": { "type": "string", "description": "Recurrence frequency: daily, weekly, or monthly.", "example": "weekly" }, "interval": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "description": "Repeat every N periods (positive integer).", "example": 1 }, "days": { "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "ISO weekday numbers (1=Monday … 7=Sunday). Required when type is \"weekly\".", "example": [1, 3, 5] }, "end": { "type": "object", "properties": { "type": { "type": "string", "description": "How the recurrence ends: date, count, or never.", "example": "count" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Ending date (YYYY-MM-DD) when type is \"date\", or occurrence count when type is \"count\".", "example": 12 } } } }, "x-supported-emrs": ["TheraNest"], "description": "Optional recurrence rule. Omit for a one-off block. See field descriptions for per-type requirements.", "example": { "type": "weekly", "interval": 1, "days": [1, 3, 5], "end": { "type": "count", "value": 12 } } }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["TheraNest"], "description": "URLs to receive the completion webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["TheraNest"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Availability block queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Availability block queued for creation" }, "availability_id": { "type": "string", "example": "availability-123" }, "job_id": { "type": "integer", "example": 12345 } }, "required": [ "success", "message", "availability_id", "job_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/availability/fetch": { "post": { "operationId": "liveFetchAvailability", "summary": "Live-fetch availability", "description": "Queues a real-time fetch of availability from the EMR for one or more providers. Results are delivered by webhook.", "tags": ["Availability"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["start_date", "end_date", "provider_ids"], "properties": { "start_date": { "type": "string", "format": "date", "x-supported-emrs": ["eClinicalWorks"], "description": "Range start (YYYY-MM-DD).", "example": "2026-03-15", "x-required-for-emrs": ["eClinicalWorks"] }, "end_date": { "type": "string", "format": "date", "x-supported-emrs": ["eClinicalWorks"], "description": "Range end (YYYY-MM-DD). One provider spans up to 5 days; 2–10 providers must share a single day.", "example": "2026-03-20", "x-required-for-emrs": ["eClinicalWorks"] }, "provider_ids": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "EMR provider IDs to fetch availability for (1–10).", "example": ["PROV-1"], "x-required-for-emrs": ["eClinicalWorks"] }, "buffer": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "Minutes of buffer between slots (0–59).", "example": 15 }, "visit_type": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Visit-type code to size slots for. Requires buffer to be set.", "example": "FOLLOW-UP" }, "calculation_method": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Slot calculation method: gaps, slots, or equal_slots.", "example": "gaps" }, "daily_appointment_limit": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "Max appointments per day (positive integer). Requires daily_limit_type.", "example": 8 }, "daily_limit_type": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Visit-type code the daily limit applies to. Requires daily_appointment_limit.", "example": "all" }, "provider_type": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Which provider slot to match on: primary or secondary.", "example": "primary" }, "fallback_to_default_hours": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "Use default business hours when a provider has no configured hours.", "example": false }, "max_slot_duration": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "Cap on slot length in minutes (5–60, multiples of 5).", "example": 30 }, "facility_scoped_scheduling": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "x-supported-emrs": ["eClinicalWorks"], "description": "Scope slots per facility rather than per provider.", "example": true }, "location_ids": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "Filter returned slots to these EMR location IDs.", "example": ["LOC-1"] }, "cancelled_statuses": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "Appointment statuses to treat as cancelled, freeing the slot. When provided, this overrides the default cancelled/rescheduled detection. The default detection treats \"c\", \"cancelled\", \"canc\", \"rescheduled\", \"r/s\" and \"deleted\" as cancelled (PTPracticePro uses \"3\" in place of \"c\"); for eClinicalWorks it also treats any status containing \"canc\", \"r/s\" or \"resched\" as cancelled. Statuses are matched case-insensitively. To keep the default detection and add your own statuses, use additional_cancelled_statuses instead.", "example": ["canc", "rs", "cancsms"] }, "additional_cancelled_statuses": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "Appointment statuses to treat as cancelled in addition to the default cancelled/rescheduled detection (or to cancelled_statuses, when provided); statuses are matched case-insensitively. Use this to add custom status codes without losing the defaults.", "example": ["no show", "bumped"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the results webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Live-fetch request accepted; results delivered by webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Live-fetch request accepted" }, "job_id": { "type": "integer", "example": 12345 } }, "required": ["success", "message", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/claims": { "post": { "operationId": "createClaim", "summary": "Create a claim", "description": "Queues a claim for creation in the connected EMR.", "tags": ["Claims"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["appointment_id"], "properties": { "appointment_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Cobalt appointment ID (UUID, with or without dashes) to create the claim for. The appointment must belong to the caller and have an emr_appointment_id.", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "x-required-for-emrs": ["eClinicalWorks"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this claim, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Claim creation queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Claim creation queued" }, "claim_id": { "type": "string", "example": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3" }, "appointment_id": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": [ "success", "message", "claim_id", "appointment_id", "job_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "A claim for this appointment is already pending or completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false] }, "message": { "type": "string", "example": "A claim for this appointment is already pending or completed" } }, "required": ["success", "message"] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getClaims", "summary": "List claims", "description": "Returns the claims Cobalt has synced for the account, with filtering and pagination.", "tags": ["Claims"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "parameters": [ { "name": "start_date", "in": "query", "description": "Start of the claim service-date range (ISO 8601, YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-15" }, "required": true, "x-supported-emrs": ["eClinicalWorks", "Credible"] }, { "name": "end_date", "in": "query", "description": "End of the claim service-date range (ISO 8601, YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-20" }, "required": true, "x-supported-emrs": ["eClinicalWorks", "Credible"] }, { "name": "patient_mrn", "in": "query", "description": "Filter by patient Medical Record Number.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "Credible"] }, { "name": "claim_status", "in": "query", "description": "Filter by claim status.", "schema": { "type": "string", "example": "submitted" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "Credible"] }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": ["eClinicalWorks", "Credible"] }, { "name": "page_size", "in": "query", "description": "Items per page (max 1000).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 100 }, "required": false, "x-supported-emrs": ["eClinicalWorks", "Credible"] } ], "responses": { "200": { "description": "Claims for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "claims": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt claim ID (dashless UUID)." }, "emr_claim_id": { "type": "string", "description": "EMR claim ID." }, "emr_appointment_id": { "type": ["string", "null"], "description": "EMR appointment ID." }, "service_date": { "type": ["string", "null"], "format": "date", "description": "Date of service." }, "claim_date": { "type": ["string", "null"], "format": "date", "description": "Date the claim was created." }, "claim_status": { "type": ["string", "null"], "description": "Raw EMR claim status code (e.g. \"48CL\")." }, "claim_status_description": { "type": ["string", "null"], "description": "Human-readable claim status." }, "claim_type": { "type": ["string", "null"], "description": "EMR claim type code." }, "void_flag": { "type": ["boolean", "null"], "description": "Whether the claim is voided." }, "emr_patient_id": { "type": ["string", "null"], "description": "EMR patient ID." }, "patient_name": { "type": ["string", "null"], "description": "Patient name." }, "emr_provider_id": { "type": ["string", "null"], "description": "EMR provider ID." }, "provider_name": { "type": ["string", "null"], "description": "Provider name." }, "total_charge": { "type": ["string", "null"], "description": "Total charge amount (decimal string)." }, "total_payment": { "type": ["string", "null"], "description": "Total payment amount (decimal string)." }, "net_payment": { "type": ["string", "null"], "description": "Net payment amount (decimal string)." }, "balance": { "type": ["string", "null"], "description": "Outstanding balance (decimal string)." }, "net_adjustment": { "type": ["string", "null"], "description": "Net adjustment amount (decimal string)." }, "patient_responsibility": { "type": ["string", "null"], "description": "Patient responsibility amount (decimal string)." }, "insurances": { "type": ["array", "null"], "items": { "type": "object", "properties": { "insurance_id": { "type": "string", "description": "EMR insurance record ID." }, "insurance_name": { "type": "string", "description": "Payer/plan name." }, "insurance_type": { "type": "string", "description": "EMR insurance type code." }, "claim_indicator": { "type": "string", "description": "Claim order indicator (e.g. \"P\", \"S\", \"T\")." }, "claim_indicator_description": { "type": "string", "description": "Human-readable claim order (e.g. \"Primary\")." }, "sequence_number": { "type": "string", "description": "Payer sequence number." }, "subscriber_name": { "type": "string", "description": "Subscriber name." }, "subscriber_number": { "type": "string", "description": "Subscriber/member ID." }, "subscriber_dob": { "type": ["string", "null"], "format": "date", "description": "Subscriber date of birth." }, "subscriber_relation": { "type": "string", "description": "Subscriber relationship code." }, "group_name": { "type": "string", "description": "Plan group name." }, "group_number": { "type": "string", "description": "Plan group number." }, "provider_number": { "type": "string", "description": "Payer-specific provider number." }, "payment_source": { "type": "string", "description": "Payment source / filing indicator code." }, "assign_benefits": { "type": "string", "description": "Assignment of benefits flag (e.g. \"Y\"/\"N\")." }, "insurance_address_1": { "type": "string", "description": "Payer address line 1." }, "insurance_address_2": { "type": "string", "description": "Payer address line 2." }, "insurance_city": { "type": "string", "description": "Payer city." }, "insurance_state": { "type": "string", "description": "Payer state." }, "insurance_zip": { "type": "string", "description": "Payer ZIP code." }, "medicaid_id": { "type": "string", "description": "Medicaid ID, when present." }, "ins_id": { "type": "string", "description": "Credible insurance record ID." }, "billing_order": { "type": ["string", "null"], "description": "Credible payer billing order." }, "payer_name": { "type": ["string", "null"], "description": "Credible payer name." }, "start_date": { "type": ["string", "null"], "format": "date", "description": "Coverage start date." }, "end_date": { "type": ["string", "null"], "format": "date", "description": "Coverage end date." }, "current": { "type": "boolean", "description": "Whether Credible marks coverage current." }, "is_primary": { "type": "boolean", "description": "Whether Credible marks the payer primary." } } }, "description": "Insurance policies attached to the claim." }, "balances": { "type": ["object", "null"], "properties": { "invoice_amount": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Total invoiced amount." }, "total_payment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Total payment received." }, "net_payment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Net payment received." }, "balance": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Outstanding balance." }, "patient_balance": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Outstanding patient balance." }, "patient_payment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Payment received from the patient." }, "patient_responsibility": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Patient responsibility amount." }, "total_charge": { "type": "number", "description": "Credible total charge." }, "adjusted_amount": { "type": "number", "description": "Credible total adjusted amount." }, "on_plan": { "type": "string", "description": "Stringified boolean; whether the claim is on a plan." } }, "description": "Claim-level balance rollup." }, "icd_codes": { "type": ["array", "null"], "items": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "icd_version": { "type": "string" }, "primary": { "type": "string" }, "specify": { "type": "string" }, "notes": { "type": "string" } } }, "description": "ICD-10 diagnosis-code details for the claim." }, "void_claim": { "type": ["object", "null"], "properties": { "void_to_claim_id": { "type": "string", "description": "Claim this one was voided to (\"-1\" if none)." }, "void_from_claim_id": { "type": "string", "description": "Claim this one was voided from (\"-1\" if none)." }, "copy_to_claim_id": { "type": "string", "description": "Claim this one was copied to (\"-1\" if none)." }, "copy_from_claim_id": { "type": "string", "description": "Claim this one was copied from (\"-1\" if none)." } }, "description": "Void/copy linkage for the claim." }, "submission_history": { "anyOf": [ { "type": "object", "properties": { "created_by": { "type": ["string", "null"], "description": "User who created the claim." }, "entries": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Submission history entries." }, "auto_claim_data": { "type": ["object", "null"], "properties": { "isUserInactive": { "type": "string", "description": "Stringified boolean; user inactive." }, "schedulerJobId": { "type": "string", "description": "Scheduler job ID (\"-1\" if none)." }, "isClaimCreatedByJob": { "type": "string", "description": "Stringified boolean; created by a job." } }, "description": "Automated-claim scheduler metadata." } } }, { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Submission history for the claim." }, "billing_activity_log": { "type": ["array", "null"], "items": { "type": "object", "properties": { "date": { "type": ["string", "null"], "description": "Activity timestamp (EMR local time)." }, "action": { "type": ["string", "null"], "description": "Action taken (e.g. \"Modified\")." }, "category": { "type": ["string", "null"], "description": "Activity category." }, "notes": { "type": ["string", "null"], "description": "Activity notes." }, "user_name": { "type": ["string", "null"], "description": "User who performed the action." }, "service_id": { "type": "string", "description": "Credible source service ID." }, "claimId": { "type": "string", "description": "Credible claim ID." }, "postingDate": { "type": "string", "description": "Credible posting date." }, "batch": { "type": "string", "description": "Credible batch identifier." }, "paymentId": { "type": "string", "description": "Credible payment identifier." }, "payer": { "type": "string", "description": "Credible payer name." }, "flag835": { "type": "string", "description": "Credible 835 flag." }, "eobDate": { "type": "string", "description": "Credible EOB date." }, "accntgDate": { "type": "string", "description": "Credible accounting date." }, "amount": { "type": "string", "description": "Credible activity amount." }, "balance": { "type": "string", "description": "Credible activity balance." }, "adjustment": { "type": "string", "description": "Credible adjustment detail." }, "user": { "type": "string", "description": "Credible activity user." } } }, "description": "Billing activity log entries." }, "billing_notes": { "type": ["string", "null"], "description": "Free-text billing notes." }, "synced_at": { "type": ["string", "null"], "format": "date-time", "description": "When the claim was last synced." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "When the claim record was created." }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "When the claim record was updated." }, "progress_note": { "type": "string", "description": "Associated appointment progress note; empty when unavailable." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt line-item ID (dashless UUID)." }, "line_number": { "type": "integer", "description": "Line number on the claim." }, "cpt_code": { "type": ["string", "null"], "description": "CPT procedure code." }, "description": { "type": ["string", "null"], "description": "Procedure description." }, "modifiers": { "type": "array", "items": { "type": "string" }, "description": "CPT modifiers." }, "units": { "type": ["integer", "null"], "description": "Units billed." }, "billed_amount": { "type": ["string", "null"], "description": "Billed amount for the line (decimal string)." }, "allowed_amount": { "type": ["string", "null"], "description": "Allowed amount for the line (decimal string)." }, "billed_unit_fee": { "type": ["string", "null"], "description": "Billed fee per unit (decimal string)." }, "icd_pointers": { "type": "array", "items": { "type": "string" }, "description": "Diagnosis pointer indices into the claim icd_codes." }, "place_of_service": { "type": ["string", "null"], "description": "Place of service code." }, "type_of_service": { "type": ["string", "null"], "description": "Type of service code." }, "service_date_start": { "type": ["string", "null"], "format": "date", "description": "Line service start date." }, "service_date_end": { "type": ["string", "null"], "format": "date", "description": "Line service end date." }, "rendering_provider_npi": { "type": ["string", "null"], "description": "Rendering provider NPI." }, "ordering_provider_npi": { "type": ["string", "null"], "description": "Ordering provider NPI." }, "referring_provider_npi": { "type": ["string", "null"], "description": "Referring provider NPI." } } }, "description": "CPT line items." }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt payment ID (dashless UUID)." }, "emr_payment_id": { "type": ["string", "null"], "description": "EMR payment ID." }, "emr_payment_detail_id": { "type": ["string", "null"], "description": "EMR payment-detail ID." }, "check_number": { "type": ["string", "null"], "description": "Check or EFT number." }, "payment_date": { "type": ["string", "null"], "format": "date", "description": "Date the payment was posted." }, "amount": { "type": ["string", "null"], "description": "Payment amount (decimal string)." }, "payment_type": { "type": ["string", "null"], "description": "Payment type (e.g. \"Insurance\")." }, "payer_name": { "type": ["string", "null"], "description": "Payer name." }, "payer_id": { "type": ["string", "null"], "description": "Payer ID." }, "payer_type": { "type": ["string", "null"], "description": "Payer type (e.g. \"Insurance\")." }, "adjustment": { "type": ["string", "null"], "description": "Adjustment amount (decimal string)." }, "deductible": { "type": ["string", "null"], "description": "Deductible amount (decimal string)." }, "coinsurance": { "type": ["string", "null"], "description": "Coinsurance amount (decimal string)." }, "allowed": { "type": ["string", "null"], "description": "Allowed amount (decimal string)." }, "member_balance": { "type": ["string", "null"], "description": "Member balance (decimal string)." }, "withheld": { "type": ["string", "null"], "description": "Withheld amount (decimal string)." }, "era_claim_status": { "type": ["string", "null"], "description": "ERA claim status description." }, "era_claim_status_code": { "type": ["string", "null"], "description": "ERA claim status code." }, "era_filing_indicator": { "type": ["string", "null"], "description": "ERA filing indicator." }, "is_reversal": { "type": ["boolean", "null"], "description": "True when this ERA entry reverses a previous payment (835 CLP02 = 22). Null when the payment has no ERA status code." }, "payer_position": { "type": ["integer", "null"], "description": "Payer position from the ERA claim status: 1 = primary, 2 = secondary, 3 = tertiary. Null for reversals and payments with no ERA status code." }, "era_service_lines": { "description": "ERA service-line details. Each line carries claim_line_number (the line_items[].line_number it pays, or null), procedure_code, modifiers, and ndc_code / revenue_code when the payer reported those instead of a CPT/HCPCS code." }, "era_payer_name": { "type": ["string", "null"], "description": "ERA payer name." }, "era_check_amount": { "type": ["string", "null"], "description": "ERA check amount (decimal string)." }, "era_reference_id": { "type": ["string", "null"], "description": "ERA remittance reference ID." }, "era_payer_claim_id": { "type": ["string", "null"], "description": "Payer claim control number (ICN) from the ERA/835, distinct per remittance event." }, "era_adjustment_codes": { "type": ["array", "null"], "items": { "type": "object", "additionalProperties": {} }, "description": "ERA adjustment codes; null when none." } } }, "description": "Payments and adjustments." } }, "example": { "id": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_claim_id": "claim-emr-123", "emr_appointment_id": "appt-emr-789", "service_date": "2026-06-15", "claim_date": "2026-06-15", "claim_status": "48CL", "claim_status_description": "submitted", "claim_type": "Professional", "void_flag": false, "emr_patient_id": "12345", "patient_name": "Jane Doe", "emr_provider_id": "provider-123", "provider_name": "Dr. Alex Smith", "total_charge": "150.00", "total_payment": "100.00", "net_payment": "100.00", "balance": "25.00", "net_adjustment": "25.00", "patient_responsibility": "25.00", "insurances": [ { "insurance_id": "51638", "insurance_name": "Blue Cross Anthem", "insurance_type": "PPO", "claim_indicator": "P", "claim_indicator_description": "Primary", "sequence_number": "1", "subscriber_name": "Jane Doe", "subscriber_number": "MEM123456789", "subscriber_dob": "1980-01-15", "subscriber_relation": "self", "group_name": "Group A", "group_number": "GRP98999", "provider_number": "1234567890", "payment_source": "CI", "assign_benefits": "Y", "insurance_address_1": "123 Main Street", "insurance_address_2": "Suite 100", "insurance_city": "Los Angeles", "insurance_state": "CA", "insurance_zip": "90001", "medicaid_id": "", "ins_id": "51638", "billing_order": "1", "payer_name": "Blue Cross Anthem", "start_date": "2026-01-01", "end_date": "2026-12-31", "current": true, "is_primary": true } ], "balances": { "invoice_amount": "150.00", "total_payment": "100.00", "net_payment": "100.00", "balance": "25.00", "patient_balance": "25.00", "patient_payment": "0.00", "patient_responsibility": "25.00", "total_charge": 150, "adjusted_amount": 25, "on_plan": "false" }, "icd_codes": [ { "code": "R51", "description": "Headache", "icd_version": "10", "primary": "true", "specify": "", "notes": "Primary diagnosis" } ], "void_claim": { "void_to_claim_id": "-1", "void_from_claim_id": "-1", "copy_to_claim_id": "-1", "copy_from_claim_id": "-1" }, "submission_history": { "created_by": "STAFF-123", "entries": [ { "status": "submitted", "submitted_at": "2026-06-15T21:30:00Z" } ], "auto_claim_data": { "isUserInactive": "false", "schedulerJobId": "-1", "isClaimCreatedByJob": "false" } }, "billing_activity_log": [ { "date": "2026-06-16T09:00:00", "action": "Payment posted", "category": "Payment", "notes": "Insurance payment received", "user_name": "Billing Staff", "service_id": "service-123", "claimId": "claim-emr-123", "postingDate": "2026-06-16", "batch": "batch-123", "paymentId": "payment-emr-123", "payer": "Blue Cross Anthem", "flag835": "true", "eobDate": "2026-06-16", "accntgDate": "2026-06-16", "amount": "100.00", "balance": "25.00", "adjustment": "25.00", "user": "STAFF-123" } ], "billing_notes": "Balance due at next visit.", "synced_at": "2026-06-16T17:00:00Z", "created_at": "2026-06-15T21:30:00Z", "updated_at": "2026-06-16T17:00:00Z", "progress_note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.", "line_items": [ { "id": "d1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "line_number": 1, "cpt_code": "99213", "description": "Office outpatient visit", "modifiers": ["25"], "units": 1, "billed_amount": "150.00", "allowed_amount": "125.00", "billed_unit_fee": "150.00", "icd_pointers": ["1"], "place_of_service": "11", "type_of_service": "1", "service_date_start": "2026-06-15", "service_date_end": "2026-06-15", "rendering_provider_npi": "1234567890", "ordering_provider_npi": "1234567890", "referring_provider_npi": "1234567890" } ], "payments": [ { "id": "e1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_payment_id": "payment-emr-123", "emr_payment_detail_id": "payment-detail-123", "check_number": "EFT-12345", "payment_date": "2026-06-16", "amount": "100.00", "payment_type": "Insurance", "payer_name": "Blue Cross Anthem", "payer_id": "98999", "payer_type": "Insurance", "adjustment": "25.00", "deductible": "0.00", "coinsurance": "25.00", "allowed": "125.00", "member_balance": "25.00", "withheld": "0.00", "era_claim_status": "Processed as primary", "era_claim_status_code": "1", "era_filing_indicator": "CI", "era_service_lines": [ { "cpt_code": "99213", "paid_amount": "100.00" } ], "era_payer_name": "Blue Cross Anthem", "era_check_amount": "100.00", "era_reference_id": "ERA-12345", "era_payer_claim_id": "ICN-12345", "era_adjustment_codes": [ { "group_code": "CO", "reason_code": "45", "amount": "25.00" } ] } ] } }, "example": [ { "id": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_claim_id": "claim-emr-123", "emr_appointment_id": "appt-emr-789", "service_date": "2026-06-15", "claim_date": "2026-06-15", "claim_status": "48CL", "claim_status_description": "submitted", "claim_type": "Professional", "void_flag": false, "emr_patient_id": "12345", "patient_name": "Jane Doe", "emr_provider_id": "provider-123", "provider_name": "Dr. Alex Smith", "total_charge": "150.00", "total_payment": "100.00", "net_payment": "100.00", "balance": "25.00", "net_adjustment": "25.00", "patient_responsibility": "25.00", "insurances": [ { "insurance_id": "51638", "insurance_name": "Blue Cross Anthem", "insurance_type": "PPO", "claim_indicator": "P", "claim_indicator_description": "Primary", "sequence_number": "1", "subscriber_name": "Jane Doe", "subscriber_number": "MEM123456789", "subscriber_dob": "1980-01-15", "subscriber_relation": "self", "group_name": "Group A", "group_number": "GRP98999", "provider_number": "1234567890", "payment_source": "CI", "assign_benefits": "Y", "insurance_address_1": "123 Main Street", "insurance_address_2": "Suite 100", "insurance_city": "Los Angeles", "insurance_state": "CA", "insurance_zip": "90001", "medicaid_id": "", "ins_id": "51638", "billing_order": "1", "payer_name": "Blue Cross Anthem", "start_date": "2026-01-01", "end_date": "2026-12-31", "current": true, "is_primary": true } ], "balances": { "invoice_amount": "150.00", "total_payment": "100.00", "net_payment": "100.00", "balance": "25.00", "patient_balance": "25.00", "patient_payment": "0.00", "patient_responsibility": "25.00", "total_charge": 150, "adjusted_amount": 25, "on_plan": "false" }, "icd_codes": [ { "code": "R51", "description": "Headache", "icd_version": "10", "primary": "true", "specify": "", "notes": "Primary diagnosis" } ], "void_claim": { "void_to_claim_id": "-1", "void_from_claim_id": "-1", "copy_to_claim_id": "-1", "copy_from_claim_id": "-1" }, "submission_history": { "created_by": "STAFF-123", "entries": [ { "status": "submitted", "submitted_at": "2026-06-15T21:30:00Z" } ], "auto_claim_data": { "isUserInactive": "false", "schedulerJobId": "-1", "isClaimCreatedByJob": "false" } }, "billing_activity_log": [ { "date": "2026-06-16T09:00:00", "action": "Payment posted", "category": "Payment", "notes": "Insurance payment received", "user_name": "Billing Staff", "service_id": "service-123", "claimId": "claim-emr-123", "postingDate": "2026-06-16", "batch": "batch-123", "paymentId": "payment-emr-123", "payer": "Blue Cross Anthem", "flag835": "true", "eobDate": "2026-06-16", "accntgDate": "2026-06-16", "amount": "100.00", "balance": "25.00", "adjustment": "25.00", "user": "STAFF-123" } ], "billing_notes": "Balance due at next visit.", "synced_at": "2026-06-16T17:00:00Z", "created_at": "2026-06-15T21:30:00Z", "updated_at": "2026-06-16T17:00:00Z", "progress_note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.", "line_items": [ { "id": "d1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "line_number": 1, "cpt_code": "99213", "description": "Office outpatient visit", "modifiers": ["25"], "units": 1, "billed_amount": "150.00", "allowed_amount": "125.00", "billed_unit_fee": "150.00", "icd_pointers": ["1"], "place_of_service": "11", "type_of_service": "1", "service_date_start": "2026-06-15", "service_date_end": "2026-06-15", "rendering_provider_npi": "1234567890", "ordering_provider_npi": "1234567890", "referring_provider_npi": "1234567890" } ], "payments": [ { "id": "e1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_payment_id": "payment-emr-123", "emr_payment_detail_id": "payment-detail-123", "check_number": "EFT-12345", "payment_date": "2026-06-16", "amount": "100.00", "payment_type": "Insurance", "payer_name": "Blue Cross Anthem", "payer_id": "98999", "payer_type": "Insurance", "adjustment": "25.00", "deductible": "0.00", "coinsurance": "25.00", "allowed": "125.00", "member_balance": "25.00", "withheld": "0.00", "era_claim_status": "Processed as primary", "era_claim_status_code": "1", "era_filing_indicator": "CI", "era_service_lines": [ { "cpt_code": "99213", "paid_amount": "100.00" } ], "era_payer_name": "Blue Cross Anthem", "era_check_amount": "100.00", "era_reference_id": "ERA-12345", "era_payer_claim_id": "ICN-12345", "era_adjustment_codes": [ { "group_code": "CO", "reason_code": "45", "amount": "25.00" } ] } ] } ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 100 }, "total_count": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 } }, "required": [ "page", "page_size", "total_count", "total_pages" ] } }, "required": ["success", "claims", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/claims/{id}": { "get": { "operationId": "getClaimById", "summary": "Get a claim", "description": "Returns a single synced claim by its Cobalt ID.", "tags": ["Claims"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt claim ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3" }, "required": true } ], "responses": { "200": { "description": "The requested claim", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "claim": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt claim ID (dashless UUID)." }, "emr_claim_id": { "type": "string", "description": "EMR claim ID." }, "emr_appointment_id": { "type": ["string", "null"], "description": "EMR appointment ID." }, "service_date": { "type": ["string", "null"], "format": "date", "description": "Date of service." }, "claim_date": { "type": ["string", "null"], "format": "date", "description": "Date the claim was created." }, "claim_status": { "type": ["string", "null"], "description": "Raw EMR claim status code (e.g. \"48CL\")." }, "claim_status_description": { "type": ["string", "null"], "description": "Human-readable claim status." }, "claim_type": { "type": ["string", "null"], "description": "EMR claim type code." }, "void_flag": { "type": ["boolean", "null"], "description": "Whether the claim is voided." }, "emr_patient_id": { "type": ["string", "null"], "description": "EMR patient ID." }, "patient_name": { "type": ["string", "null"], "description": "Patient name." }, "emr_provider_id": { "type": ["string", "null"], "description": "EMR provider ID." }, "provider_name": { "type": ["string", "null"], "description": "Provider name." }, "total_charge": { "type": ["string", "null"], "description": "Total charge amount (decimal string)." }, "total_payment": { "type": ["string", "null"], "description": "Total payment amount (decimal string)." }, "net_payment": { "type": ["string", "null"], "description": "Net payment amount (decimal string)." }, "balance": { "type": ["string", "null"], "description": "Outstanding balance (decimal string)." }, "net_adjustment": { "type": ["string", "null"], "description": "Net adjustment amount (decimal string)." }, "patient_responsibility": { "type": ["string", "null"], "description": "Patient responsibility amount (decimal string)." }, "insurances": { "type": ["array", "null"], "items": { "type": "object", "properties": { "insurance_id": { "type": "string", "description": "EMR insurance record ID." }, "insurance_name": { "type": "string", "description": "Payer/plan name." }, "insurance_type": { "type": "string", "description": "EMR insurance type code." }, "claim_indicator": { "type": "string", "description": "Claim order indicator (e.g. \"P\", \"S\", \"T\")." }, "claim_indicator_description": { "type": "string", "description": "Human-readable claim order (e.g. \"Primary\")." }, "sequence_number": { "type": "string", "description": "Payer sequence number." }, "subscriber_name": { "type": "string", "description": "Subscriber name." }, "subscriber_number": { "type": "string", "description": "Subscriber/member ID." }, "subscriber_dob": { "type": ["string", "null"], "format": "date", "description": "Subscriber date of birth." }, "subscriber_relation": { "type": "string", "description": "Subscriber relationship code." }, "group_name": { "type": "string", "description": "Plan group name." }, "group_number": { "type": "string", "description": "Plan group number." }, "provider_number": { "type": "string", "description": "Payer-specific provider number." }, "payment_source": { "type": "string", "description": "Payment source / filing indicator code." }, "assign_benefits": { "type": "string", "description": "Assignment of benefits flag (e.g. \"Y\"/\"N\")." }, "insurance_address_1": { "type": "string", "description": "Payer address line 1." }, "insurance_address_2": { "type": "string", "description": "Payer address line 2." }, "insurance_city": { "type": "string", "description": "Payer city." }, "insurance_state": { "type": "string", "description": "Payer state." }, "insurance_zip": { "type": "string", "description": "Payer ZIP code." }, "medicaid_id": { "type": "string", "description": "Medicaid ID, when present." }, "ins_id": { "type": "string", "description": "Credible insurance record ID." }, "billing_order": { "type": ["string", "null"], "description": "Credible payer billing order." }, "payer_name": { "type": ["string", "null"], "description": "Credible payer name." }, "start_date": { "type": ["string", "null"], "format": "date", "description": "Coverage start date." }, "end_date": { "type": ["string", "null"], "format": "date", "description": "Coverage end date." }, "current": { "type": "boolean", "description": "Whether Credible marks coverage current." }, "is_primary": { "type": "boolean", "description": "Whether Credible marks the payer primary." } } }, "description": "Insurance policies attached to the claim." }, "balances": { "type": ["object", "null"], "properties": { "invoice_amount": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Total invoiced amount." }, "total_payment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Total payment received." }, "net_payment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Net payment received." }, "balance": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Outstanding balance." }, "patient_balance": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Outstanding patient balance." }, "patient_payment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Payment received from the patient." }, "patient_responsibility": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Patient responsibility amount." }, "total_charge": { "type": "number", "description": "Credible total charge." }, "adjusted_amount": { "type": "number", "description": "Credible total adjusted amount." }, "on_plan": { "type": "string", "description": "Stringified boolean; whether the claim is on a plan." } }, "description": "Claim-level balance rollup." }, "icd_codes": { "type": ["array", "null"], "items": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "icd_version": { "type": "string" }, "primary": { "type": "string" }, "specify": { "type": "string" }, "notes": { "type": "string" } } }, "description": "ICD-10 diagnosis-code details for the claim." }, "void_claim": { "type": ["object", "null"], "properties": { "void_to_claim_id": { "type": "string", "description": "Claim this one was voided to (\"-1\" if none)." }, "void_from_claim_id": { "type": "string", "description": "Claim this one was voided from (\"-1\" if none)." }, "copy_to_claim_id": { "type": "string", "description": "Claim this one was copied to (\"-1\" if none)." }, "copy_from_claim_id": { "type": "string", "description": "Claim this one was copied from (\"-1\" if none)." } }, "description": "Void/copy linkage for the claim." }, "submission_history": { "anyOf": [ { "type": "object", "properties": { "created_by": { "type": ["string", "null"], "description": "User who created the claim." }, "entries": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Submission history entries." }, "auto_claim_data": { "type": ["object", "null"], "properties": { "isUserInactive": { "type": "string", "description": "Stringified boolean; user inactive." }, "schedulerJobId": { "type": "string", "description": "Scheduler job ID (\"-1\" if none)." }, "isClaimCreatedByJob": { "type": "string", "description": "Stringified boolean; created by a job." } }, "description": "Automated-claim scheduler metadata." } } }, { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Submission history for the claim." }, "billing_activity_log": { "type": ["array", "null"], "items": { "type": "object", "properties": { "date": { "type": ["string", "null"], "description": "Activity timestamp (EMR local time)." }, "action": { "type": ["string", "null"], "description": "Action taken (e.g. \"Modified\")." }, "category": { "type": ["string", "null"], "description": "Activity category." }, "notes": { "type": ["string", "null"], "description": "Activity notes." }, "user_name": { "type": ["string", "null"], "description": "User who performed the action." }, "service_id": { "type": "string", "description": "Credible source service ID." }, "claimId": { "type": "string", "description": "Credible claim ID." }, "postingDate": { "type": "string", "description": "Credible posting date." }, "batch": { "type": "string", "description": "Credible batch identifier." }, "paymentId": { "type": "string", "description": "Credible payment identifier." }, "payer": { "type": "string", "description": "Credible payer name." }, "flag835": { "type": "string", "description": "Credible 835 flag." }, "eobDate": { "type": "string", "description": "Credible EOB date." }, "accntgDate": { "type": "string", "description": "Credible accounting date." }, "amount": { "type": "string", "description": "Credible activity amount." }, "balance": { "type": "string", "description": "Credible activity balance." }, "adjustment": { "type": "string", "description": "Credible adjustment detail." }, "user": { "type": "string", "description": "Credible activity user." } } }, "description": "Billing activity log entries." }, "billing_notes": { "type": ["string", "null"], "description": "Free-text billing notes." }, "synced_at": { "type": ["string", "null"], "format": "date-time", "description": "When the claim was last synced." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "When the claim record was created." }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "When the claim record was updated." }, "progress_note": { "type": "string", "description": "Associated appointment progress note; empty when unavailable." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt line-item ID (dashless UUID)." }, "line_number": { "type": "integer", "description": "Line number on the claim." }, "cpt_code": { "type": ["string", "null"], "description": "CPT procedure code." }, "description": { "type": ["string", "null"], "description": "Procedure description." }, "modifiers": { "type": "array", "items": { "type": "string" }, "description": "CPT modifiers." }, "units": { "type": ["integer", "null"], "description": "Units billed." }, "billed_amount": { "type": ["string", "null"], "description": "Billed amount for the line (decimal string)." }, "allowed_amount": { "type": ["string", "null"], "description": "Allowed amount for the line (decimal string)." }, "billed_unit_fee": { "type": ["string", "null"], "description": "Billed fee per unit (decimal string)." }, "icd_pointers": { "type": "array", "items": { "type": "string" }, "description": "Diagnosis pointer indices into the claim icd_codes." }, "place_of_service": { "type": ["string", "null"], "description": "Place of service code." }, "type_of_service": { "type": ["string", "null"], "description": "Type of service code." }, "service_date_start": { "type": ["string", "null"], "format": "date", "description": "Line service start date." }, "service_date_end": { "type": ["string", "null"], "format": "date", "description": "Line service end date." }, "rendering_provider_npi": { "type": ["string", "null"], "description": "Rendering provider NPI." }, "ordering_provider_npi": { "type": ["string", "null"], "description": "Ordering provider NPI." }, "referring_provider_npi": { "type": ["string", "null"], "description": "Referring provider NPI." } } }, "description": "CPT line items." }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt payment ID (dashless UUID)." }, "emr_payment_id": { "type": ["string", "null"], "description": "EMR payment ID." }, "emr_payment_detail_id": { "type": ["string", "null"], "description": "EMR payment-detail ID." }, "check_number": { "type": ["string", "null"], "description": "Check or EFT number." }, "payment_date": { "type": ["string", "null"], "format": "date", "description": "Date the payment was posted." }, "amount": { "type": ["string", "null"], "description": "Payment amount (decimal string)." }, "payment_type": { "type": ["string", "null"], "description": "Payment type (e.g. \"Insurance\")." }, "payer_name": { "type": ["string", "null"], "description": "Payer name." }, "payer_id": { "type": ["string", "null"], "description": "Payer ID." }, "payer_type": { "type": ["string", "null"], "description": "Payer type (e.g. \"Insurance\")." }, "adjustment": { "type": ["string", "null"], "description": "Adjustment amount (decimal string)." }, "deductible": { "type": ["string", "null"], "description": "Deductible amount (decimal string)." }, "coinsurance": { "type": ["string", "null"], "description": "Coinsurance amount (decimal string)." }, "allowed": { "type": ["string", "null"], "description": "Allowed amount (decimal string)." }, "member_balance": { "type": ["string", "null"], "description": "Member balance (decimal string)." }, "withheld": { "type": ["string", "null"], "description": "Withheld amount (decimal string)." }, "era_claim_status": { "type": ["string", "null"], "description": "ERA claim status description." }, "era_claim_status_code": { "type": ["string", "null"], "description": "ERA claim status code." }, "era_filing_indicator": { "type": ["string", "null"], "description": "ERA filing indicator." }, "is_reversal": { "type": ["boolean", "null"], "description": "True when this ERA entry reverses a previous payment (835 CLP02 = 22). Null when the payment has no ERA status code." }, "payer_position": { "type": ["integer", "null"], "description": "Payer position from the ERA claim status: 1 = primary, 2 = secondary, 3 = tertiary. Null for reversals and payments with no ERA status code." }, "era_service_lines": { "description": "ERA service-line details. Each line carries claim_line_number (the line_items[].line_number it pays, or null), procedure_code, modifiers, and ndc_code / revenue_code when the payer reported those instead of a CPT/HCPCS code." }, "era_payer_name": { "type": ["string", "null"], "description": "ERA payer name." }, "era_check_amount": { "type": ["string", "null"], "description": "ERA check amount (decimal string)." }, "era_reference_id": { "type": ["string", "null"], "description": "ERA remittance reference ID." }, "era_payer_claim_id": { "type": ["string", "null"], "description": "Payer claim control number (ICN) from the ERA/835, distinct per remittance event." }, "era_adjustment_codes": { "type": ["array", "null"], "items": { "type": "object", "additionalProperties": {} }, "description": "ERA adjustment codes; null when none." } } }, "description": "Payments and adjustments." } }, "example": { "id": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_claim_id": "claim-emr-123", "emr_appointment_id": "appt-emr-789", "service_date": "2026-06-15", "claim_date": "2026-06-15", "claim_status": "48CL", "claim_status_description": "submitted", "claim_type": "Professional", "void_flag": false, "emr_patient_id": "12345", "patient_name": "Jane Doe", "emr_provider_id": "provider-123", "provider_name": "Dr. Alex Smith", "total_charge": "150.00", "total_payment": "100.00", "net_payment": "100.00", "balance": "25.00", "net_adjustment": "25.00", "patient_responsibility": "25.00", "insurances": [ { "insurance_id": "51638", "insurance_name": "Blue Cross Anthem", "insurance_type": "PPO", "claim_indicator": "P", "claim_indicator_description": "Primary", "sequence_number": "1", "subscriber_name": "Jane Doe", "subscriber_number": "MEM123456789", "subscriber_dob": "1980-01-15", "subscriber_relation": "self", "group_name": "Group A", "group_number": "GRP98999", "provider_number": "1234567890", "payment_source": "CI", "assign_benefits": "Y", "insurance_address_1": "123 Main Street", "insurance_address_2": "Suite 100", "insurance_city": "Los Angeles", "insurance_state": "CA", "insurance_zip": "90001", "medicaid_id": "", "ins_id": "51638", "billing_order": "1", "payer_name": "Blue Cross Anthem", "start_date": "2026-01-01", "end_date": "2026-12-31", "current": true, "is_primary": true } ], "balances": { "invoice_amount": "150.00", "total_payment": "100.00", "net_payment": "100.00", "balance": "25.00", "patient_balance": "25.00", "patient_payment": "0.00", "patient_responsibility": "25.00", "total_charge": 150, "adjusted_amount": 25, "on_plan": "false" }, "icd_codes": [ { "code": "R51", "description": "Headache", "icd_version": "10", "primary": "true", "specify": "", "notes": "Primary diagnosis" } ], "void_claim": { "void_to_claim_id": "-1", "void_from_claim_id": "-1", "copy_to_claim_id": "-1", "copy_from_claim_id": "-1" }, "submission_history": { "created_by": "STAFF-123", "entries": [ { "status": "submitted", "submitted_at": "2026-06-15T21:30:00Z" } ], "auto_claim_data": { "isUserInactive": "false", "schedulerJobId": "-1", "isClaimCreatedByJob": "false" } }, "billing_activity_log": [ { "date": "2026-06-16T09:00:00", "action": "Payment posted", "category": "Payment", "notes": "Insurance payment received", "user_name": "Billing Staff", "service_id": "service-123", "claimId": "claim-emr-123", "postingDate": "2026-06-16", "batch": "batch-123", "paymentId": "payment-emr-123", "payer": "Blue Cross Anthem", "flag835": "true", "eobDate": "2026-06-16", "accntgDate": "2026-06-16", "amount": "100.00", "balance": "25.00", "adjustment": "25.00", "user": "STAFF-123" } ], "billing_notes": "Balance due at next visit.", "synced_at": "2026-06-16T17:00:00Z", "created_at": "2026-06-15T21:30:00Z", "updated_at": "2026-06-16T17:00:00Z", "progress_note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.", "line_items": [ { "id": "d1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "line_number": 1, "cpt_code": "99213", "description": "Office outpatient visit", "modifiers": ["25"], "units": 1, "billed_amount": "150.00", "allowed_amount": "125.00", "billed_unit_fee": "150.00", "icd_pointers": ["1"], "place_of_service": "11", "type_of_service": "1", "service_date_start": "2026-06-15", "service_date_end": "2026-06-15", "rendering_provider_npi": "1234567890", "ordering_provider_npi": "1234567890", "referring_provider_npi": "1234567890" } ], "payments": [ { "id": "e1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_payment_id": "payment-emr-123", "emr_payment_detail_id": "payment-detail-123", "check_number": "EFT-12345", "payment_date": "2026-06-16", "amount": "100.00", "payment_type": "Insurance", "payer_name": "Blue Cross Anthem", "payer_id": "98999", "payer_type": "Insurance", "adjustment": "25.00", "deductible": "0.00", "coinsurance": "25.00", "allowed": "125.00", "member_balance": "25.00", "withheld": "0.00", "era_claim_status": "Processed as primary", "era_claim_status_code": "1", "era_filing_indicator": "CI", "era_service_lines": [ { "cpt_code": "99213", "paid_amount": "100.00" } ], "era_payer_name": "Blue Cross Anthem", "era_check_amount": "100.00", "era_reference_id": "ERA-12345", "era_payer_claim_id": "ICN-12345", "era_adjustment_codes": [ { "group_code": "CO", "reason_code": "45", "amount": "25.00" } ] } ] } } }, "required": ["success", "claim"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/claims/fetch": { "post": { "operationId": "liveFetchClaims", "summary": "Fetch claims", "description": "Queues a live fetch of claims from the EMR for one service date or a list of claim numbers. Refreshed claims are stored and returned by GET /v1/claims; the result is delivered by webhook.", "tags": ["Claims"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "service_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Service date to refresh (ISO 8601, YYYY-MM-DD). Every claim with this date of service is fetched from the EMR. Send either service_date or claim_ids.", "example": "2026-03-15" }, "claim_ids": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "EMR claim numbers to refresh (1-25), the emr_claim_id of a claim. Send either service_date or claim_ids.", "example": ["16382", "16383"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this fetch, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Claims fetch accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Claims fetch accepted" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/codes": { "post": { "operationId": "submitCodes", "summary": "Submit billing codes", "description": "Validates and saves ICD-10 billing codes for an appointment in the connected EMR.", "tags": ["Codes"], "x-supported-emrs": ["DrChrono"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["appointment_id", "codes"], "properties": { "appointment_id": { "type": "string", "x-supported-emrs": ["DrChrono"], "description": "EMR appointment ID to attach the billing codes to.", "example": "appt-emr-789", "x-required-for-emrs": ["DrChrono"] }, "codes": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["DrChrono"], "description": "ICD-10 diagnosis codes to validate and save.", "example": ["R51", "M54.5"], "x-required-for-emrs": ["DrChrono"] } } } } } }, "responses": { "200": { "description": "Codes validated and saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "results": { "example": { "validCodes": ["R51", "M54.5"], "invalidCodes": [] } } }, "required": ["success"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/documents": { "post": { "operationId": "createDocument", "summary": "Upload a document", "description": "Uploads a document and queues it for delivery to the connected EMR.", "tags": ["Documents"], "x-supported-emrs": ["eClinicalWorks", "Athena", "Credible"], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["document", "patient_mrn"], "properties": { "document": { "type": "string", "format": "binary", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible" ], "description": "The document file to upload (PDF, JPEG, or PNG; max 30MB).", "example": "lab-results.pdf", "x-required-for-emrs": [ "eClinicalWorks", "Athena", "Credible" ] }, "patient_mrn": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible" ], "description": "Medical Record Number of the patient the document is for.", "example": "12345", "x-required-for-emrs": [ "eClinicalWorks", "Athena", "Credible" ] }, "folder_name": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible" ], "description": "Destination folder in the EMR. Either folder_name or template_name is required; EMRs that do not use template_name require folder_name.", "example": "Lab Results", "x-required-for-emrs": ["Athena", "Credible"] }, "template_name": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Destination template in the EMR (max 255 chars). Either folder_name or template_name is required; EMRs that do not use template_name require folder_name.", "example": "Progress Note" }, "emr_assigned_to_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR staff ID to assign the document to. Validated against the account’s staff; valid ids are the `ehr_id` values from GET /v1/staff.", "example": "staff-123" }, "review_required": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible" ], "description": "Whether the document should be flagged for review in the EMR. One of: \"true\", \"false\".", "example": "false" }, "notes": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Free-text notes for the document (max 1000 characters).", "example": "Please review before the next visit." }, "is_high_priority": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Whether the document is high priority. One of: \"true\", \"false\".", "example": "false" }, "location_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR location ID the document belongs to. Validated against the account’s locations.", "example": "location-1" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "x-supported-emrs": ["eClinicalWorks"], "description": "Tags to attach to the document. Repeat the field for multiple tags.", "example": ["lab", "urgent"] }, "association_type": { "type": "string", "enum": ["referral", "order"], "x-supported-emrs": ["eClinicalWorks"], "description": "Attach the document to an existing entity instead of a chart folder. One of: \"referral\", \"order\". When set, association_id is required and folder_name/template_name must be omitted. eClinicalWorks only.", "example": "referral" }, "association_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Cobalt id of the entity to attach to (the referral `id` from GET /v1/referrals, or the order `id` from GET /v1/orders). Required when association_type is set.", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "callback_urls": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible" ], "description": "URLs to receive the completion webhook for this document, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Document uploaded and queued for delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Document uploaded and queued for delivery" }, "document_id": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "document_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getDocuments", "summary": "List documents", "description": "Lists stored documents, newest first: the synced EHR document inbox, documents from patient and appointment live fetches, referral attachments and uploads. Metadata only; download a file with GET /v1/documents/{id}.", "tags": ["Documents"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "ModmedEMA", "Sunwave", "EZDERM" ], "parameters": [ { "name": "start_date", "in": "query", "description": "Start of the date range (YYYY-MM-DD, inclusive). Matches the EHR scan date for inbox documents, otherwise the day Cobalt stored the document.", "schema": { "type": "string", "example": "2026-03-15" }, "required": true, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "ModmedEMA", "Sunwave", "EZDERM" ] }, { "name": "end_date", "in": "query", "description": "End of the date range (YYYY-MM-DD, inclusive).", "schema": { "type": "string", "example": "2026-03-20" }, "required": true, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "ModmedEMA", "Sunwave", "EZDERM" ] }, { "name": "patient_mrn", "in": "query", "description": "Filter by patient Medical Record Number.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "ModmedEMA", "Sunwave", "EZDERM" ] }, { "name": "document_type", "in": "query", "description": "Filter by type: \"file\" (a stored file), \"visit_note\" (an encounter visit note, fetched as PDF) or \"eligibility_report\" (an insurance eligibility check report, fetched as PDF).", "schema": { "type": "string", "enum": ["file", "visit_note", "eligibility_report"], "example": "file" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "ModmedEMA", "Sunwave", "EZDERM" ] }, { "name": "inbox", "in": "query", "description": "\"true\" returns only documents synced from the EHR document inbox; \"false\" excludes them.", "schema": { "type": "string", "enum": ["true", "false"], "example": "true" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "folder_ehr_id", "in": "query", "description": "Filter by EHR folder (category) ID.", "schema": { "type": "string", "example": "folder-123" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "folder_name", "in": "query", "description": "Filter by folder (category) name, case-insensitive. Inbox documents use the full folder path, e.g. \"Fax Inbox/Referrals\".", "schema": { "type": "string", "example": "Lab Results" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "Athena", "Credible"] }, { "name": "assigned_to_ehr_id", "in": "query", "description": "Filter by assignee: a staff `ehr_id` from GET /v1/staff.", "schema": { "type": "string", "example": "staff-123" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "assigned_to_name", "in": "query", "description": "Filter by assignee name as shown in the EHR (e.g. \"Smith,Jane\"), case- and space-insensitive. Use for group assignees, which have no staff ID.", "schema": { "type": "string", "example": "Smith,Alex" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "review_required", "in": "query", "description": "Filter by whether the document is marked for review.", "schema": { "type": "string", "enum": ["true", "false"], "example": "true" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "Athena", "Credible"] }, { "name": "page", "in": "query", "description": "Page number (default 1).", "schema": { "type": "string", "example": "1" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "ModmedEMA", "Sunwave", "EZDERM" ] }, { "name": "page_size", "in": "query", "description": "Results per page (1-100, default 100).", "schema": { "type": "string", "example": "100" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "ModmedEMA", "Sunwave", "EZDERM" ] } ], "responses": { "200": { "description": "Documents for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt document ID (dashless UUID)." }, "file_name": { "type": "string" }, "description": { "type": ["string", "null"] }, "mime_type": { "type": "string" }, "document_type": { "type": "string", "enum": [ "file", "visit_note", "eligibility_report" ], "description": "\"file\" (a stored file), \"visit_note\" (an encounter visit note, fetched as PDF) or \"eligibility_report\" (an insurance eligibility check report, fetched as PDF)." }, "patient_mrn": { "type": ["string", "null"] }, "patient_ehr_id": { "type": ["string", "null"] }, "encounter_ehr_id": { "type": ["string", "null"] }, "folder_ehr_id": { "type": ["string", "null"] }, "folder_name": { "type": ["string", "null"] }, "assigned_to_ehr_id": { "type": ["string", "null"], "description": "Assignee staff `ehr_id` (GET /v1/staff). Null for group assignees." }, "assigned_to_name": { "type": ["string", "null"] }, "review_required": { "type": "boolean", "description": "Whether the document is marked for review in the EHR." }, "is_high_priority": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "scanned_date": { "type": ["string", "null"], "description": "Date the document was filed in the EHR (YYYY-MM-DD)." }, "service_date": { "type": ["string", "null"] }, "has_file": { "type": "boolean", "description": "Whether the file is stored. When false, request it with POST /v1/documents/fetch before GET /v1/documents/{id}." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "file_name", "description", "mime_type", "document_type", "patient_mrn", "patient_ehr_id", "encounter_ehr_id", "folder_ehr_id", "folder_name", "assigned_to_ehr_id", "assigned_to_name", "review_required", "is_high_priority", "tags", "scanned_date", "service_date", "has_file", "created_at", "updated_at" ] }, "example": [ { "id": "f47ac10b58cc4372a5670e02b2c3d479", "file_name": "lab-results.pdf", "description": "Please review before the next visit.", "mime_type": "application/pdf", "document_type": "file", "patient_mrn": "12345", "patient_ehr_id": "patient-123", "encounter_ehr_id": "encounter-123", "folder_ehr_id": "folder-123", "folder_name": "Lab Results", "assigned_to_ehr_id": "staff-123", "assigned_to_name": "Alex Smith", "review_required": true, "is_high_priority": false, "tags": ["lab", "urgent"], "scanned_date": "2026-06-15", "service_date": "2026-06-15", "has_file": true, "created_at": "2026-06-15T21:30:00Z", "updated_at": "2026-06-15T21:30:00Z" } ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 25 }, "total_count": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 } }, "required": [ "page", "page_size", "total_count", "total_pages" ] } }, "required": ["success", "documents", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/documents/{id}": { "get": { "operationId": "getDocumentById", "summary": "Download a document", "description": "Streams a stored document back by its Cobalt ID.", "tags": ["Documents"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "ModmedEMA", "Sunwave", "EZDERM" ], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt document ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "required": true } ], "responses": { "200": { "description": "The document file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "example": "%PDF-1.4" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The document exists but its file has not been fetched yet. Request it with POST /v1/documents/fetch, then retrieve it here after the document.live_fetch_completed webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "message": { "type": "string", "example": "Document file has not been fetched yet" } }, "required": ["success", "message"] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/documents/fetch": { "post": { "operationId": "liveFetchDocument", "summary": "Fetch a document", "description": "Queues a live fetch of a document's file from the EMR and stores it; the result is delivered by webhook and retrievable via GET /v1/documents/{id}.", "tags": ["Documents"], "x-supported-emrs": ["Sunwave", "eClinicalWorks", "EZDERM"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "x-supported-emrs": ["Sunwave"], "description": "Cobalt document id identifying the EMR document to fetch (e.g. from the patient live-fetch response).", "example": "swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9", "x-required-for-emrs": ["Sunwave"] }, "document_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 10, "x-supported-emrs": ["eClinicalWorks", "EZDERM"], "description": "Cobalt document ids to fetch (1-10), e.g. documents[].id, visit_note_document_id or insurances[].eligibility_checks[].document_id from the patient or appointment live fetch. Each document's file is fetched from the EMR (visit notes are rendered to PDF) and stored; results arrive per document in the webhook.", "example": ["3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12"], "x-required-for-emrs": ["eClinicalWorks", "EZDERM"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["Sunwave", "eClinicalWorks", "EZDERM"], "description": "URLs to receive the completion webhook for this fetch, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["Sunwave", "eClinicalWorks", "EZDERM"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } }, "required": ["document_id", "document_ids"] } } } }, "responses": { "202": { "description": "Document fetch accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Document fetch accepted" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/eligibility-checks": { "get": { "operationId": "getEligibilityChecks", "summary": "List eligibility checks", "description": "Returns the eligibility checks Cobalt has synced for the account, with filtering and pagination.", "tags": ["Eligibility"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "start_date", "in": "query", "description": "Start of the check date range (ISO 8601, YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-15" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "end_date", "in": "query", "description": "End of the check date range (ISO 8601, YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-20" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "patient_mrn", "in": "query", "description": "Filter by patient Medical Record Number.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "coverage_status", "in": "query", "description": "Filter by coverage status.", "schema": { "type": "string", "example": "active" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page_size", "in": "query", "description": "Items per page.", "schema": { "type": "integer", "minimum": 1, "example": 25 }, "required": false, "x-supported-emrs": ["eClinicalWorks"] } ], "responses": { "200": { "description": "Eligibility checks for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "eligibility_checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt's eligibility check identifier (dashless UUID). Use this in the benefits endpoint path." }, "emr_id": { "type": "string", "description": "The eligibility request identifier as it appears in the EMR." }, "emr_patient_id": { "type": ["string", "null"], "description": "EMR patient identifier the check was run for." }, "patient_name": { "type": ["string", "null"], "description": "Patient name." }, "patient_dob": { "type": ["string", "null"], "format": "date", "description": "Patient date of birth (YYYY-MM-DD)." }, "emr_encounter_id": { "type": ["string", "null"], "description": "The encounter/visit the check is tied to." }, "provider_name": { "type": ["string", "null"], "description": "Rendering provider." }, "payer_name": { "type": ["string", "null"], "description": "Payer that responded." }, "subscriber_name": { "type": ["string", "null"], "description": "Subscriber name." }, "subscriber_member_id": { "type": ["string", "null"], "description": "Subscriber member ID." }, "patient_relationship": { "type": ["string", "null"], "description": "Patient relationship to subscriber: 'self' or 'dependent'." }, "plan_name": { "type": ["string", "null"], "description": "Plan description from the 271." }, "coverage_status": { "type": ["string", "null"], "description": "Coverage status: 'active', 'inactive', 'error' (payer could not process the request), or 'unknown'." }, "status_message": { "type": ["string", "null"], "description": "Payer reject reason when coverage_status is 'error'." }, "service_date": { "type": ["string", "null"], "format": "date", "description": "Date of service (YYYY-MM-DD)." }, "response_at": { "type": ["string", "null"], "description": "When the payer response was received (ISO 8601)." }, "plan_begin_date": { "type": ["string", "null"], "format": "date", "description": "Plan effective start date (YYYY-MM-DD); may be null." }, "plan_end_date": { "type": ["string", "null"], "format": "date", "description": "Plan effective end date (YYYY-MM-DD); may be null." }, "benefits_summary": { "type": ["object", "null"], "properties": { "deductible": { "type": "object", "properties": { "individual": { "type": "object", "properties": { "total": { "type": "number", "description": "Plan total for this coverage level." }, "remaining": { "type": "number", "description": "Amount remaining for this coverage level." } } }, "family": { "type": "object", "properties": { "total": { "type": "number", "description": "Plan total for this coverage level." }, "remaining": { "type": "number", "description": "Amount remaining for this coverage level." } } } } }, "out_of_pocket": { "type": "object", "properties": { "individual": { "type": "object", "properties": { "total": { "type": "number", "description": "Plan total for this coverage level." }, "remaining": { "type": "number", "description": "Amount remaining for this coverage level." } } }, "family": { "type": "object", "properties": { "total": { "type": "number", "description": "Plan total for this coverage level." }, "remaining": { "type": "number", "description": "Amount remaining for this coverage level." } } } } } }, "description": "Headline EOB rollup. deductible and out_of_pocket are each split by individual / family into total and remaining amounts." }, "benefit_count": { "type": "integer", "description": "Number of benefit lines parsed from the 271." }, "synced_at": { "type": ["string", "null"], "description": "When Cobalt synced the check (ISO 8601)." } }, "required": [ "id", "emr_id", "emr_patient_id", "patient_name", "patient_dob", "emr_encounter_id", "provider_name", "payer_name", "subscriber_name", "subscriber_member_id", "patient_relationship", "plan_name", "coverage_status", "status_message", "service_date", "response_at", "plan_begin_date", "plan_end_date", "benefits_summary", "benefit_count", "synced_at" ] }, "example": [ { "id": "f47ac10b58cc4372a5670e02b2c3d479", "emr_id": "eligibility-123", "emr_patient_id": "patient-123", "patient_name": "Jane Doe", "patient_dob": "1980-01-15", "emr_encounter_id": "encounter-123", "provider_name": "Alex Smith", "payer_name": "Blue Cross Anthem", "subscriber_name": "Jane Doe", "subscriber_member_id": "MEM123456789", "patient_relationship": "self", "plan_name": "Preferred PPO", "coverage_status": "active", "status_message": null, "service_date": "2026-06-15", "response_at": "2026-06-15T21:30:00Z", "plan_begin_date": "2026-01-01", "plan_end_date": "2026-12-31", "benefits_summary": { "deductible": { "individual": { "total": 1500, "remaining": 500 }, "family": { "total": 3000, "remaining": 1000 } }, "out_of_pocket": { "individual": { "total": 5000, "remaining": 3500 }, "family": { "total": 10000, "remaining": 7000 } } }, "benefit_count": 1, "synced_at": "2026-06-15T21:35:00Z" } ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 25 }, "total_records": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 } }, "required": [ "page", "page_size", "total_records", "total_pages" ] } }, "required": ["success", "eligibility_checks", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/eligibility-checks/{id}/benefits": { "get": { "operationId": "getEligibilityBenefits", "summary": "List eligibility benefits", "description": "Returns the benefit lines for a single eligibility check, with filtering and pagination.", "tags": ["Eligibility"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt eligibility check ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "required": true }, { "name": "benefit_type", "in": "query", "description": "Filter by benefit type.", "schema": { "type": "string", "example": "medical" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page_size", "in": "query", "description": "Items per page.", "schema": { "type": "integer", "minimum": 1, "example": 25 }, "required": false, "x-supported-emrs": ["eClinicalWorks"] } ], "responses": { "200": { "description": "Benefit lines for the eligibility check", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "benefits": { "type": "array", "items": { "type": "object", "properties": { "line_number": { "type": "integer", "description": "Segment order within the 271." }, "benefit_type": { "type": ["string", "null"], "description": "Decoded benefit category, e.g. Active Coverage, Deductible, Co-Payment, Co-Insurance, Out of Pocket, Limitations, Non-Covered." }, "benefit_type_code": { "type": ["string", "null"], "description": "The raw X12 EB01 code." }, "coverage_level": { "type": ["string", "null"], "description": "Coverage level: 'IND' (individual) or 'FAM' (family)." }, "service_type_codes": { "type": "array", "items": { "type": "string" }, "description": "X12 service type codes the benefit applies to." }, "insurance_type": { "type": ["string", "null"], "description": "Insurance type code, when present." }, "time_period": { "type": ["string", "null"], "description": "Decoded time period, e.g. Calendar Year or Remaining." }, "amount": { "type": ["number", "null"], "description": "Monetary amount (deductible, copay, or out-of-pocket)." }, "percent": { "type": ["number", "null"], "description": "Coinsurance percentage as a decimal (e.g. 0.2 = 20%)." }, "network_indicator": { "type": ["string", "null"], "description": "Network scope: 'in-network', 'out-of-network', 'unknown', or 'not-applicable'." }, "messages": { "type": "array", "items": { "type": "string" }, "description": "Payer free-text notes attached to the benefit line." }, "raw_segment": { "type": ["string", "null"], "description": "The raw X12 EB segment, retained for reference." } }, "required": [ "line_number", "benefit_type", "benefit_type_code", "coverage_level", "service_type_codes", "insurance_type", "time_period", "amount", "percent", "network_indicator", "messages", "raw_segment" ] }, "example": [ { "line_number": 1, "benefit_type": "Co-Payment", "benefit_type_code": "B", "coverage_level": "IND", "service_type_codes": ["98"], "insurance_type": "PPO", "time_period": "Visit", "amount": 25, "percent": null, "network_indicator": "in-network", "messages": ["Office visit copayment"], "raw_segment": "EB*B*IND*98*PPO**27*25" } ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 25 }, "total_records": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 } }, "required": [ "page", "page_size", "total_records", "total_pages" ] } }, "required": ["success", "benefits", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/encounters": { "post": { "operationId": "createEncounter", "summary": "Create an encounter", "description": "Queues an encounter (episode visit with form documentation) for creation in the connected EMR.", "tags": ["Encounters"], "x-supported-emrs": ["Credible"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "patient_mrn", "episode_id", "encounter_type", "form_id", "answers" ], "properties": { "patient_mrn": { "type": "string", "x-supported-emrs": ["Credible"], "description": "Medical Record Number (Credible client id) of the patient.", "example": "15539", "x-required-for-emrs": ["Credible"] }, "episode_id": { "type": "string", "x-supported-emrs": ["Credible"], "description": "Episode (FHIR EpisodeOfCare) the encounter is created under. Pull the exact id from the patient episode payload and pass it here — the encounter attaches to this episode with no fallback. Assign the patient to a team first (a separate step) to open the episode.", "example": "32340", "x-required-for-emrs": ["Credible"] }, "encounter_type": { "type": "string", "x-supported-emrs": ["Credible"], "description": "Encounter type to add, by name or numeric visit-type id (e.g. \"GAD-7\").", "example": "GAD-7", "x-required-for-emrs": ["Credible"] }, "form_id": { "type": "string", "x-supported-emrs": ["Credible"], "description": "EMR form id whose answers are provided (from GET /v1/forms). Required when the encounter type documents a form.", "example": "392", "x-required-for-emrs": ["Credible"] }, "answers": { "type": "object", "additionalProperties": {}, "x-supported-emrs": ["Credible"], "description": "Form answers keyed by EMR question id (from GET /v1/forms). Value by question format: single choice (radio, push button) and dropdown take the answer value or answer id; check box (multi-select) takes a list of answer values or ids; text box takes a string; date takes YYYY-MM-DD. An open-text narrative question takes the text as a string. To add notes to a choice (e.g. \"Other\"), send { \"value\": \"Other\", \"notes\": \"...\" }. For a scored questionnaire (e.g. GAD-7) provide the numeric score for each scored question; totals and risk bands are derived automatically. A conditional question (shown only after a trigger answer) is accepted only when its trigger answer is also supplied. An answer that does not match the form fails the request.", "example": { "427919": { "value": "Other", "notes": "School visit" }, "427920": "Narrative text for the contact.", "467752": "2026-09-24", "467761": "Therapy", "467762": "Reason for the referral.", "467767": ["Mornings", "Afternoons"] }, "x-required-for-emrs": ["Credible"] }, "encounter_date": { "type": "string", "x-supported-emrs": ["Credible"], "description": "Encounter (service) date (YYYY-MM-DD), in the practice's local time. Defaults to today. Cannot be in the future.", "example": "2026-08-26" }, "start_time": { "type": "string", "format": "date-time", "x-supported-emrs": ["Credible"], "description": "Service start as an ISO 8601 date-time (e.g. \"2026-10-05T14:00:00-04:00\"). A value without an offset is read in the practice's local time. Sets the service date; when encounter_date is also given it must be the same date. Defaults to the current time.", "example": "2026-10-05T14:00:00-04:00" }, "end_time": { "type": "string", "format": "date-time", "x-supported-emrs": ["Credible"], "description": "Service end as an ISO 8601 date-time, on the same day as start_time and after it. Defaults to one hour after start_time. Requires start_time.", "example": "2026-10-05T15:00:00-04:00" }, "location": { "type": "string", "x-supported-emrs": ["Credible"], "description": "Service location, by EMR location id or exact name, from the Location list on the EMR's service form (e.g. \"Broadway Office\"). Defaults to the EMR's default location for the service. An unknown location fails the request.", "example": "Broadway Office" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["Credible"], "description": "URLs to receive the completion webhook for this encounter, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["Credible"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Encounter queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Encounter queued for processing" }, "encounter_id": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "job_id": { "type": "integer", "example": 12345 } }, "required": ["success", "message", "encounter_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/encounters/{id}": { "patch": { "operationId": "updateEncounter", "summary": "Update an encounter", "description": "Queues an update (approval) of an existing encounter in the connected EMR.", "tags": ["Encounters"], "x-supported-emrs": ["Credible"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt encounter ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["approved"], "properties": { "approved": { "type": "boolean", "enum": [true], "x-supported-emrs": ["Credible"], "description": "Set to true to approve the encounter in the EMR. An encounter that is already approved is left as is.", "example": true, "x-required-for-emrs": ["Credible"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["Credible"], "description": "URLs to receive the completion webhook for this update, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["Credible"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Encounter update queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Encounter update queued for processing" }, "encounter_id": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "job_id": { "type": "integer", "example": 12345 } }, "required": ["success", "message", "encounter_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/fee-schedules": { "get": { "operationId": "getFeeSchedules", "summary": "List fee schedules", "description": "Returns the fee-schedule headers Cobalt has synced for the account.", "tags": ["Fee Schedules"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "page", "in": "query", "description": "Page number. Every fee schedule is returned on one page. Accepted, but no EMR uses it, so it has no effect.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": [] }, { "name": "page_size", "in": "query", "description": "Results per page. Every fee schedule is returned on one page. Accepted, but no EMR uses it, so it has no effect.", "schema": { "type": "integer", "minimum": 1, "example": 100 }, "required": false, "x-supported-emrs": [] } ], "responses": { "200": { "description": "Fee-schedule headers for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "fee_schedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt fee-schedule ID (dashless UUID)." }, "emr_id": { "type": "string", "description": "EMR fee-schedule ID." }, "name": { "type": ["string", "null"], "description": "Fee-schedule name." }, "description": { "type": ["string", "null"], "description": "Fee-schedule description from the EMR." }, "sub_name": { "type": ["string", "null"], "description": "Secondary label from the EMR." }, "is_master": { "type": "boolean", "description": "Whether this is the master fee schedule." }, "taxable": { "type": "boolean", "description": "Whether the schedule is marked taxable." }, "effective_from": { "type": ["string", "null"], "format": "date", "description": "Start of the schedule effective date range (nullable)." }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "End of the schedule effective date range (nullable)." }, "item_count": { "type": "integer", "description": "Number of priced codes." } }, "required": [ "id", "emr_id", "name", "description", "sub_name", "is_master", "taxable", "effective_from", "effective_to", "item_count" ] }, "example": [ { "id": "f47ac10b58cc4372a5670e02b2c3d479", "emr_id": "fee-schedule-123", "name": "Standard office fees", "description": "Office visit fee schedule", "sub_name": "2026", "is_master": true, "taxable": false, "effective_from": "2026-01-01", "effective_to": "2026-12-31", "item_count": 1 } ] } }, "required": ["success", "fee_schedules"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/fee-schedules/{feeScheduleId}/items": { "get": { "operationId": "getFeeScheduleItems", "summary": "List fee-schedule items", "description": "Returns a page of the per-code pricing for one fee schedule, with filtering.", "tags": ["Fee Schedules"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "feeScheduleId", "in": "path", "description": "Cobalt fee-schedule ID.", "schema": { "type": "string", "example": "fee-schedule-123" }, "required": true }, { "name": "search", "in": "query", "description": "Filter by CPT/HCPCS code or description.", "schema": { "type": "string", "example": "99213" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "validity", "in": "query", "description": "Filter by validity. One of: \"valid\", \"invalid\".", "schema": { "type": "string", "example": "valid" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page_size", "in": "query", "description": "Items per page (max 500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "example": 100 }, "required": false, "x-supported-emrs": ["eClinicalWorks"] } ], "responses": { "200": { "description": "A page of fee-schedule items", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string", "description": "EMR item identifier, stable per code within the schedule." }, "code": { "type": ["string", "null"], "description": "CPT/HCPCS code." }, "name": { "type": ["string", "null"], "description": "Code description." }, "fee": { "type": ["number", "null"], "description": "Billed/charge amount." }, "allowed_fee": { "type": ["number", "null"], "description": "Contracted allowed amount." }, "cost": { "type": ["number", "null"], "description": "Cost amount." }, "patient_portion": { "type": ["number", "null"], "description": "Patient-portion amount." }, "bill_to_patient": { "type": "boolean", "description": "Whether the code is billed to the patient." }, "modifiers": { "type": "array", "items": { "type": "string" }, "description": "Procedure modifiers (only non-empty slots are returned)." }, "pos": { "type": ["string", "null"], "description": "Place of service (nullable)." }, "tos": { "type": ["string", "null"], "description": "Type of service (nullable)." }, "ndc": { "type": "object", "properties": { "code": { "type": ["string", "null"] }, "units": { "type": ["string", "null"] }, "uom": { "type": ["string", "null"] }, "unit_price": { "type": ["string", "null"] } }, "required": ["code", "units", "uom", "unit_price"], "description": "National Drug Code details." }, "exclude_cpt": { "type": "boolean", "description": "Whether the code is excluded from CPT billing." }, "validity": { "type": "string", "description": "Code validity: 'valid' or 'invalid'." } }, "required": [ "item_id", "code", "name", "fee", "allowed_fee", "cost", "patient_portion", "bill_to_patient", "modifiers", "pos", "tos", "ndc", "exclude_cpt", "validity" ] }, "example": [ { "item_id": "fee-item-123", "code": "99213", "name": "Established patient office visit", "fee": 150, "allowed_fee": 120, "cost": 75, "patient_portion": 25, "bill_to_patient": true, "modifiers": ["25"], "pos": "11", "tos": "1", "ndc": { "code": null, "units": null, "uom": null, "unit_price": null }, "exclude_cpt": false, "validity": "valid" } ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 25 }, "total_records": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 } }, "required": [ "page", "page_size", "total_records", "total_pages" ] } }, "required": ["success", "items", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/forms/fetch": { "post": { "operationId": "fetchForms", "summary": "Sync forms", "description": "Queues a sync of the connected EMR’s form definitions into the Cobalt cache.", "tags": ["Forms"], "x-supported-emrs": ["Credible"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["Credible"], "description": "URLs to receive the forms.synced webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["Credible"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Forms sync queued; results delivered by webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "queued" }, "message": { "type": "string", "example": "Forms sync queued" }, "job_execution_id": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } }, "required": [ "success", "status", "message", "job_execution_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "A forms sync is already in progress for this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "status": { "type": "string", "example": "in_progress" }, "message": { "type": "string", "example": "A forms sync is already in progress" }, "job_execution_id": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } }, "required": [ "success", "status", "message", "job_execution_id" ] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/forms": { "get": { "operationId": "getForms", "summary": "List forms", "description": "Returns cached form metadata (id, name, type, version, status) for the account.", "tags": ["Forms"], "x-supported-emrs": ["Credible"], "responses": { "200": { "description": "Cached form metadata for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "forms": { "type": "array", "items": { "$ref": "#/components/schemas/FormMetadata" }, "example": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "emr_form_id": "form-123", "emr_fvid": "form-version-1", "name": "Patient intake", "type": "intake", "version": "1", "status": "active", "build_date": "2026-01-01", "synced_at": "2026-06-15T21:30:00Z", "created_at": "2026-06-15T21:30:00Z", "updated_at": "2026-06-15T21:30:00Z" } ] } }, "required": ["success", "forms"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/forms/{id}": { "get": { "operationId": "getFormById", "summary": "Get a form", "description": "Returns one cached form with its full definition (categories, questions, answers) by its Cobalt ID.", "tags": ["Forms"], "x-supported-emrs": ["Credible"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt form ID (UUID).", "schema": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "required": true } ], "responses": { "200": { "description": "The cached form with its full definition", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "form": { "$ref": "#/components/schemas/Form" } }, "required": ["success", "form"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/insurance-providers": { "get": { "operationId": "getInsuranceProviders", "summary": "List insurance providers", "description": "Returns the insurance providers Cobalt has synced for the account, with filtering and pagination.", "tags": ["Insurance Providers"], "x-supported-emrs": [ "eClinicalWorks", "Experity", "ModmedEMA", "ModmedGastro" ], "parameters": [ { "name": "name", "in": "query", "description": "Filter by insurance provider name (case-insensitive partial match).", "schema": { "type": "string", "example": "Blue Cross Anthem" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Experity", "ModmedEMA", "ModmedGastro" ] }, { "name": "ehr_id", "in": "query", "description": "Filter by the provider’s EHR ID.", "schema": { "type": "string", "example": "51638" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Experity", "ModmedEMA", "ModmedGastro" ] }, { "name": "active", "in": "query", "description": "Filter by active status.", "schema": { "type": "string", "enum": ["true", "false"], "example": "true" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Experity", "ModmedEMA", "ModmedGastro" ] }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Experity", "ModmedEMA", "ModmedGastro" ] }, { "name": "page_size", "in": "query", "description": "Items per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "example": 100 }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Experity", "ModmedEMA", "ModmedGastro" ] } ], "responses": { "200": { "description": "Insurance providers for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "insurance_providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt insurance provider ID (use this in POST /v1/patients/{patient_mrn}/insurances)." }, "name": { "type": "string", "description": "Insurance provider name as it appears in the EMR." }, "ehr_id": { "type": ["string", "null"], "description": "The EMR's internal identifier for the provider." }, "payer_id": { "type": ["string", "null"], "description": "Insurance payer ID." }, "class_code": { "type": ["string", "null"], "description": "EMR insurance class code." }, "type_code": { "type": ["string", "null"], "description": "EMR insurance type code." }, "address": { "type": ["string", "null"], "description": "Insurance provider street address." }, "city": { "type": ["string", "null"], "description": "City." }, "state": { "type": ["string", "null"], "description": "State." }, "zip": { "type": ["string", "null"], "description": "ZIP code." }, "active": { "type": ["string", "null"], "description": "Whether the provider is currently active, returned as the string \"true\" or \"false\"." } }, "required": [ "id", "name", "ehr_id", "payer_id", "class_code", "type_code", "address", "city", "state", "zip", "active" ] }, "example": [ { "id": "insurance-provider-123", "name": "Blue Cross Anthem", "ehr_id": "51638", "payer_id": "98999", "class_code": "Commercial", "type_code": "PPO", "address": "123 Main Street", "city": "Los Angeles", "state": "CA", "zip": "90001", "active": "true" } ] }, "pagination": { "type": "object", "properties": { "current_page": { "type": "number", "example": 1 }, "total_pages": { "type": "number", "example": 1 }, "total_count": { "type": "number", "example": 1 }, "page_size": { "type": "number", "example": 25 } }, "required": [ "current_page", "total_pages", "total_count", "page_size" ] } }, "required": ["success", "insurance_providers", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/link/token/create": { "post": { "operationId": "createLinkToken", "summary": "Create a Link token", "description": "Mints a public token for an account, creating the org on first use. Authenticated with client_id + client_secret headers.", "tags": ["Link"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["user_id", "org_id"], "properties": { "user_id": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "Your user ID for the account being linked.", "example": "user-123", "x-required-for-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, "org_id": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "Your organization ID for the account being linked.", "example": "org-123", "x-required-for-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, "access_token": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "Existing access token, when re-linking an account.", "example": "access-token-example" }, "emr_name": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "EMR to link. Required when creating a new org (org_id not seen before).", "example": "eClinicalWorks" }, "emr_instance_domain": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "The EMR instance domain. Required when creating a new org.", "example": "ehr.example.com" }, "timezone": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "IANA timezone for the account (e.g. America/New_York).", "example": "America/Los_Angeles" }, "use_custom_domain": { "type": "boolean", "x-supported-emrs": ["eClinicalWorks"], "description": "Whether emr_instance_domain is a custom domain.", "example": false }, "domain_name": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "Domain name to record for an existing org that lacks one.", "example": "ehr.example.com" } } } } } }, "responses": { "200": { "description": "Link token created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "token": { "type": "string", "example": "link-token-example" } }, "required": ["success", "token"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/link/token/exchange": { "get": { "operationId": "exchangeLinkToken", "summary": "Exchange a public token", "description": "Exchanges a public token for the account access token. Authenticated with client_id + client_secret headers.", "tags": ["Link"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "parameters": [ { "name": "public_token", "in": "query", "description": "The public token to exchange for an access token.", "schema": { "type": "string", "example": "link-token-example" }, "required": true, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] } ], "responses": { "200": { "description": "Access token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "token": { "type": "string", "example": "access-token-example" } }, "required": ["success", "token"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/locations": { "get": { "operationId": "getLocations", "summary": "List locations", "description": "Returns the locations Cobalt has synced for the account.", "tags": ["Locations"], "x-supported-emrs": ["eClinicalWorks", "ModmedEMA"], "parameters": [ { "name": "page", "in": "query", "description": "Page number. Every location is returned on one page. Accepted, but no EMR uses it, so it has no effect.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": [] }, { "name": "page_size", "in": "query", "description": "Results per page. Every location is returned on one page. Accepted, but no EMR uses it, so it has no effect.", "schema": { "type": "integer", "minimum": 1, "example": 100 }, "required": false, "x-supported-emrs": [] } ], "responses": { "200": { "description": "Locations for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt location ID (dashless UUID)." }, "ehr_id": { "type": "string", "description": "EMR location ID." }, "name": { "type": "string", "description": "Location name." }, "address": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } }, "description": "Location address." }, "phone": { "type": "string", "description": "Phone number." }, "fax": { "type": "string", "description": "Fax number." }, "pos": { "type": ["string", "null"], "description": "Place-of-service code configured on the facility." }, "facility_groups": { "type": "array", "items": { "type": "string" }, "description": "Names of the facility groups it belongs to." }, "status": { "type": "string", "description": "Location status (active / inactive)." } } }, "example": [ { "id": "f47ac10b58cc4372a5670e02b2c3d479", "ehr_id": "location-1", "name": "Main Hospital", "address": { "address1": "123 Main Street", "address2": "Apt 4B", "city": "Los Angeles", "state": "CA", "zip": "90001" }, "phone": "555-123-4567", "fax": "555-123-4568", "pos": "11", "facility_groups": ["North Region"], "status": "active" } ] } }, "required": ["success", "locations"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/locations/{id}": { "patch": { "operationId": "updateLocation", "summary": "Update a location", "description": "Updates a location’s status by Cobalt ID.", "tags": ["Locations"], "x-supported-emrs": ["eClinicalWorks", "ModmedEMA"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt location ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "ModmedEMA"], "description": "Location status. One of: \"active\", \"inactive\".", "example": "active", "x-required-for-emrs": ["eClinicalWorks", "ModmedEMA"] } } } } } }, "responses": { "200": { "description": "Location updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Location updated" }, "location_id": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" } }, "required": ["success", "message", "location_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/messages": { "post": { "operationId": "createMessage", "summary": "Create a message", "description": "Queues a message for creation in the connected EMR.", "tags": ["Messages"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["provider", "subject", "message"], "properties": { "provider": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR provider ID to send the message to. A string of digits only (e.g. \"12345\").", "example": "12345", "x-required-for-emrs": ["eClinicalWorks"] }, "subject": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Message subject.", "example": "Lab results", "x-required-for-emrs": ["eClinicalWorks"] }, "message": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Message body text.", "example": "Your recent lab results are ready to view.", "x-required-for-emrs": ["eClinicalWorks"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this message, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Message queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Message queued for creation" }, "message_id": { "type": "string", "example": "f47ac10b58cc4372a5670e02b2c3d479" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "message_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/notes": { "post": { "operationId": "createNote", "summary": "Create a note", "description": "Queues a clinical note for upload to the connected EMR for an appointment or, in eClinicalWorks, a telephone encounter. One note per appointment or telephone encounter: once a note is accepted, later requests for the same one are rejected with 400 \"Appointment already processed.\" (or \"Telephone encounter already processed.\") unless `force` is \"true\". A retry after a timeout is safe; that 400 means the earlier request was accepted.", "tags": ["Notes"], "x-supported-emrs": [ "OncoEMR", "Athena", "Modmed", "eClinicalWorks", "PracticeFusion" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["note"], "properties": { "note": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ], "x-supported-emrs": [ "OncoEMR", "Athena", "Modmed", "eClinicalWorks", "PracticeFusion" ], "description": "Clinical note content. A plain string for scribe/dictation, or a structured object for RPA upload.", "example": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.", "x-required-for-emrs": [ "OncoEMR", "Athena", "Modmed", "eClinicalWorks", "PracticeFusion" ] }, "icd_10_codes": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "code": { "type": "string" }, "add_to_problem_list": { "type": "string" } }, "required": ["code"] } ] } }, { "type": "object", "additionalProperties": {} } ], "x-supported-emrs": [ "OncoEMR", "Athena", "eClinicalWorks", "PracticeFusion" ], "description": "ICD-10 diagnosis codes. An array of codes, or an object shaped { codes: [...] } / { selected_codes: { codes: [...] } }. Each entry may be a plain code string, or { code, add_to_problem_list: \"true\" } to also add that diagnosis to the patient Problem List (eClinicalWorks only).", "example": ["R51", "M54.5"] }, "cpt_codes": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["Athena", "eClinicalWorks"], "description": "CPT procedure codes.", "example": ["99213"] }, "mrn": { "type": "string", "x-supported-emrs": [ "OncoEMR", "Athena", "Modmed", "eClinicalWorks", "PracticeFusion" ], "description": "Patient Medical Record Number. Provide mrn + appointment_date, or appointment_id, to identify the appointment.", "example": "12345" }, "appointment_date": { "type": "string", "x-supported-emrs": [ "OncoEMR", "Athena", "Modmed", "eClinicalWorks", "PracticeFusion" ], "description": "Appointment date (ISO 8601, YYYY-MM-DD). Used with mrn to identify the appointment.", "example": "2026-06-15" }, "appointment_id": { "type": "string", "x-supported-emrs": [ "OncoEMR", "Athena", "Modmed", "eClinicalWorks", "PracticeFusion" ], "description": "Cobalt appointment ID (UUID, with or without dashes). Alternative to mrn + appointment_date.", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "telephone_encounter_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Cobalt telephone encounter ID (from GET /v1/telephone-encounters). Writes the note to the telephone encounter's progress note instead of an appointment.", "example": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5" }, "force": { "type": "string", "x-supported-emrs": [ "OncoEMR", "Athena", "Modmed", "eClinicalWorks", "PracticeFusion" ], "description": "When \"true\", upload the note even if the appointment is already processed. One of: \"true\", \"false\".", "example": "false" }, "append": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": ["true", "false"] } ], "x-supported-emrs": ["PracticeFusion"], "description": "When true, add each note section after the text already in that section of the encounter instead of replacing it. Fails if the encounter is signed. Defaults to false (replace).", "example": true }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": [ "OncoEMR", "Athena", "eClinicalWorks", "PracticeFusion" ], "description": "URLs to receive the completion webhook for this note, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "OncoEMR", "Athena", "Modmed", "eClinicalWorks", "PracticeFusion" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Note queued for upload", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Note queued for upload" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders": { "get": { "operationId": "getOrders", "summary": "List orders", "description": "Returns the orders Cobalt has synced for the account within a date range.", "tags": ["Orders"], "x-supported-emrs": ["eClinicalWorks", "Athena"], "parameters": [ { "name": "start_date", "in": "query", "description": "Start of the date range (ISO 8601, YYYY-MM-DD). Matches order_date or schedule_date.", "schema": { "type": "string", "example": "2026-03-15" }, "required": true, "x-supported-emrs": ["eClinicalWorks", "Athena"] }, { "name": "end_date", "in": "query", "description": "End of the date range (ISO 8601, YYYY-MM-DD). Matches order_date or schedule_date, so a future range returns future orders.", "schema": { "type": "string", "example": "2026-03-20" }, "required": true, "x-supported-emrs": ["eClinicalWorks", "Athena"] }, { "name": "patient_mrn", "in": "query", "description": "Filter by patient Medical Record Number.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "Athena"] } ], "responses": { "200": { "description": "Orders for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt order ID (dashless UUID)." }, "order_id": { "type": "string", "description": "EMR order ID (emr_order_id)." }, "appointment_id": { "type": ["string", "null"], "description": "EMR appointment ID (emr_appointment_id)." }, "patient_name": { "type": ["string", "null"], "description": "EMR patient identifier (emr_patient_id)." }, "patient_mrn": { "type": ["string", "null"], "description": "Patient Medical Record Number." }, "order_date": { "type": ["string", "null"], "description": "Order date (ISO 8601 date)." }, "order_name": { "type": ["string", "null"], "description": "Order name." }, "provider_id": { "type": ["string", "null"], "description": "EMR provider ID." }, "patient_dob": { "type": ["string", "null"], "description": "Patient date of birth (ISO 8601 date)." }, "lab_results": { "description": "Lab results payload (EMR-specific JSON), when available." }, "priority": { "type": ["string", "null"], "description": "Order priority." }, "assigned_to_name": { "type": ["string", "null"], "description": "Name of the staff member the order is assigned to." }, "emr_assigned_to_id": { "type": ["string", "null"], "description": "EMR ID of the staff member the order is assigned to." }, "performed_date": { "type": ["string", "null"], "description": "Performed date (ISO 8601, YYYY-MM-DD). Diagnostic imaging." }, "type": { "type": ["string", "null"], "description": "Order type. eClinicalWorks: `lab`, `imaging` (diagnostic imaging), or `procedure`." }, "status": { "type": ["string", "null"], "description": "Order status as reported by the EMR." }, "facility_id": { "type": ["string", "null"], "description": "EMR id of the ordering facility/location." }, "collected_date": { "type": ["string", "null"], "description": "Specimen collection date (ISO 8601 date)." }, "collection_time": { "type": ["string", "null"], "description": "Specimen collection time, e.g. \"12:58 PM\"." }, "result_date": { "type": ["string", "null"], "description": "Result date (ISO 8601 date)." }, "schedule_date": { "type": ["string", "null"], "description": "Date the order is scheduled for (ISO 8601 date), e.g. for future orders." } }, "required": [ "id", "order_id", "appointment_id", "patient_name", "patient_mrn", "order_date", "order_name", "provider_id", "patient_dob", "priority", "assigned_to_name", "emr_assigned_to_id", "performed_date", "type", "status", "facility_id", "collected_date", "collection_time", "result_date", "schedule_date" ], "example": { "id": "b2c3d4e5f6a1478899aabbccddeeff00", "order_id": "order-emr-123", "appointment_id": "appt-emr-789", "patient_name": "patient-emr-123", "patient_mrn": "12345", "order_date": "2026-06-15", "order_name": "Complete blood count", "provider_id": "provider-123", "patient_dob": "1980-01-15", "lab_results": { "hemoglobin": { "value": 13.5, "unit": "g/dL" } }, "priority": "routine", "assigned_to_name": "Jane Doe", "emr_assigned_to_id": "STAFF-123", "performed_date": "2026-06-15", "type": "lab", "status": "completed", "facility_id": "FAC-123", "collected_date": "2026-06-15", "collection_time": "9:30 AM", "result_date": "2026-06-15", "schedule_date": "2026-06-15" } }, "example": [ { "id": "b2c3d4e5f6a1478899aabbccddeeff00", "order_id": "order-emr-123", "appointment_id": "appt-emr-789", "patient_name": "patient-emr-123", "patient_mrn": "12345", "order_date": "2026-06-15", "order_name": "Complete blood count", "provider_id": "provider-123", "patient_dob": "1980-01-15", "lab_results": { "hemoglobin": { "value": 13.5, "unit": "g/dL" } }, "priority": "routine", "assigned_to_name": "Jane Doe", "emr_assigned_to_id": "STAFF-123", "performed_date": "2026-06-15", "type": "lab", "status": "completed", "facility_id": "FAC-123", "collected_date": "2026-06-15", "collection_time": "9:30 AM", "result_date": "2026-06-15", "schedule_date": "2026-06-15" } ] } }, "required": ["success", "orders"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createOrder", "summary": "Create an order", "description": "Queues a lab/imaging/procedure order for creation in the connected EMR.", "tags": ["Orders"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "patient_mrn", "provider_id", "facility_id" ], "properties": { "type": { "type": "string", "enum": ["lab", "imaging", "procedure"], "x-supported-emrs": ["eClinicalWorks"], "description": "Order type.", "example": "lab", "x-required-for-emrs": ["eClinicalWorks"] }, "patient_mrn": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Medical Record Number of the patient the order is for.", "example": "12345", "x-required-for-emrs": ["eClinicalWorks"] }, "item_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR catalog id of the test/procedure to order. Provide item_id OR name (enforced in the controller); item_id wins when both are given. Discover ids via POST /v1/orders/catalog/fetch.", "example": "lab-cbc-123" }, "name": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Catalog name of the test/procedure to order, resolved against the catalog when item_id is omitted.", "example": "Complete blood count" }, "provider_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR id of the ordering provider.", "example": "provider-123", "x-required-for-emrs": ["eClinicalWorks"] }, "facility_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR id of the ordering facility/location.", "example": "FAC-123", "x-required-for-emrs": ["eClinicalWorks"] }, "assigned_to_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR staff id the order is assigned to (an `ehr_id` from GET /v1/staff).", "example": "STAFF-123" }, "order_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Order date (ISO 8601, YYYY-MM-DD).", "example": "2026-03-15" }, "collected_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Specimen collection date (ISO 8601, YYYY-MM-DD). Labs.", "example": "2026-03-15" }, "collection_time": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Specimen collection time, e.g. \"12:58 PM\".", "example": "9:30 AM" }, "performed_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Performed date (ISO 8601, YYYY-MM-DD). Diagnostic imaging.", "example": "2026-03-15" }, "high_priority": { "type": "boolean", "x-supported-emrs": ["eClinicalWorks"], "description": "Flag the order high priority.", "example": false }, "notes": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Order notes.", "example": "Collect specimen at the next visit." }, "clinical_info": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Clinical information for the order.", "example": "Evaluate fatigue and screen for anemia." }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the order.created webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Order record created/updated and queued for the EMR", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Order queued for delivery to the EMR" }, "order_id": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "order_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get an order", "description": "Returns a synced order and its result components (columns) so callers know which values POST /v1/orders/{id}/results accepts.", "tags": ["Orders"], "x-supported-emrs": ["eClinicalWorks", "Athena"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt order ID.", "schema": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "required": true } ], "responses": { "200": { "description": "The order and its result components", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "order": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt order ID (dashless UUID)." }, "order_id": { "type": "string", "description": "EMR order ID (emr_order_id)." }, "appointment_id": { "type": ["string", "null"], "description": "EMR appointment ID (emr_appointment_id)." }, "patient_name": { "type": ["string", "null"], "description": "EMR patient identifier (emr_patient_id)." }, "patient_mrn": { "type": ["string", "null"], "description": "Patient Medical Record Number." }, "order_date": { "type": ["string", "null"], "description": "Order date (ISO 8601 date)." }, "order_name": { "type": ["string", "null"], "description": "Order name." }, "provider_id": { "type": ["string", "null"], "description": "EMR provider ID." }, "patient_dob": { "type": ["string", "null"], "description": "Patient date of birth (ISO 8601 date)." }, "lab_results": { "description": "Lab results payload (EMR-specific JSON), when available." }, "priority": { "type": ["string", "null"], "description": "Order priority." }, "assigned_to_name": { "type": ["string", "null"], "description": "Name of the staff member the order is assigned to." }, "emr_assigned_to_id": { "type": ["string", "null"], "description": "EMR ID of the staff member the order is assigned to." }, "performed_date": { "type": ["string", "null"], "description": "Performed date (ISO 8601, YYYY-MM-DD). Diagnostic imaging." }, "type": { "type": ["string", "null"], "description": "Order type. eClinicalWorks: `lab`, `imaging` (diagnostic imaging), or `procedure`." }, "status": { "type": ["string", "null"], "description": "Order status as reported by the EMR." }, "facility_id": { "type": ["string", "null"], "description": "EMR id of the ordering facility/location." }, "collected_date": { "type": ["string", "null"], "description": "Specimen collection date (ISO 8601 date)." }, "collection_time": { "type": ["string", "null"], "description": "Specimen collection time, e.g. \"12:58 PM\"." }, "result_date": { "type": ["string", "null"], "description": "Result date (ISO 8601 date)." }, "schedule_date": { "type": ["string", "null"], "description": "Date the order is scheduled for (ISO 8601 date), e.g. for future orders." }, "result_components": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string", "description": "EMR component id; write target for results.", "example": "hemoglobin-123" }, "name": { "type": "string", "description": "Human column name, e.g. \"1hr Glucose (OB)\".", "example": "Hemoglobin" } }, "required": ["field_id", "name"] }, "description": "Writable result columns for this order.", "example": [ { "field_id": "hemoglobin-123", "name": "Hemoglobin" } ] } }, "required": [ "id", "order_id", "appointment_id", "patient_name", "patient_mrn", "order_date", "order_name", "provider_id", "patient_dob", "priority", "assigned_to_name", "emr_assigned_to_id", "performed_date", "type", "status", "facility_id", "collected_date", "collection_time", "result_date", "schedule_date", "result_components" ], "example": { "id": "b2c3d4e5f6a1478899aabbccddeeff00", "order_id": "order-emr-123", "appointment_id": "appt-emr-789", "patient_name": "patient-emr-123", "patient_mrn": "12345", "order_date": "2026-06-15", "order_name": "Complete blood count", "provider_id": "provider-123", "patient_dob": "1980-01-15", "lab_results": { "hemoglobin": { "value": 13.5, "unit": "g/dL" } }, "priority": "routine", "assigned_to_name": "Jane Doe", "emr_assigned_to_id": "STAFF-123", "performed_date": "2026-06-15", "type": "lab", "status": "completed", "facility_id": "FAC-123", "collected_date": "2026-06-15", "collection_time": "9:30 AM", "result_date": "2026-06-15", "schedule_date": "2026-06-15", "result_components": [ { "field_id": "hemoglobin-123", "name": "Hemoglobin" } ] } } }, "required": ["success", "order"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateOrder", "summary": "Update an order", "description": "Queues an update to an existing order (dates, assignee, priority).", "tags": ["Orders"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt order ID.", "schema": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "result_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Result date (ISO 8601, YYYY-MM-DD).", "example": "2026-03-15" }, "collected_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Specimen collection date (ISO 8601, YYYY-MM-DD).", "example": "2026-03-15" }, "collection_time": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Specimen collection time, e.g. \"12:58 PM\".", "example": "9:30 AM" }, "performed_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Performed date (ISO 8601, YYYY-MM-DD). Diagnostic imaging.", "example": "2026-03-15" }, "assigned_to_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR staff id to assign the order to (an `ehr_id` from GET /v1/staff).", "example": "STAFF-123" }, "high_priority": { "type": "boolean", "x-supported-emrs": ["eClinicalWorks"], "description": "Flag the order high priority.", "example": false }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the order.updated webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Order record created/updated and queued for the EMR", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Order queued for delivery to the EMR" }, "order_id": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "order_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/catalog/fetch": { "post": { "operationId": "searchOrderCatalog", "summary": "Search the orderable catalog", "description": "Queues a live search of the practice’s orderable lab/imaging/procedure catalog; results are delivered by webhook.", "tags": ["Orders"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["lab", "imaging", "procedure"], "x-supported-emrs": ["eClinicalWorks"], "description": "Which orderable catalog to search.", "example": "lab", "x-required-for-emrs": ["eClinicalWorks"] }, "query": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Name filter (prefix / substring). Omit to page the full catalog.", "example": "glucose" }, "page": { "type": "integer", "exclusiveMinimum": 0, "x-supported-emrs": ["eClinicalWorks"], "description": "Page number (1-based). Defaults to 1.", "example": 1 }, "page_size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "x-supported-emrs": ["eClinicalWorks"], "description": "Results per page (max 100). Defaults to 25.", "example": 25 }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the results webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Catalog search queued; results delivered via webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "queued" }, "message": { "type": "string", "example": "Order catalog search queued" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "status", "message", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{id}/results": { "post": { "operationId": "addOrderResults", "summary": "Add results to an order", "description": "Queues result values for an existing order.", "tags": ["Orders"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt order ID.", "schema": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["results"], "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "field_id": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": ["value"] }, "minItems": 1, "x-supported-emrs": ["eClinicalWorks"], "description": "Result values, one per component. Reference a component by `component` (its name, from GET /v1/orders/:id) or `field_id`.", "example": [ { "component": "Hemoglobin", "field_id": "hemoglobin-123", "value": 13.5 } ], "x-required-for-emrs": ["eClinicalWorks"] }, "result_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Result date (ISO 8601, YYYY-MM-DD). Defaults to today when omitted.", "example": "2026-03-15" }, "collected_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Specimen collection date (ISO 8601, YYYY-MM-DD).", "example": "2026-03-15" }, "collection_time": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Specimen collection time, e.g. \"12:58 PM\".", "example": "9:30 AM" }, "performed_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Performed date (ISO 8601, YYYY-MM-DD). For diagnostic imaging, the exam/performed date from the report.", "example": "2026-03-15" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the order.updated webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Lab result created and queued for the EMR", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Lab result queued for delivery to the EMR" }, "lab_result_id": { "type": "string", "example": "c3d4e5f6a1b2478899aabbccddeeff00" }, "order_id": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": [ "success", "message", "lab_result_id", "order_id", "job_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/org-settings/fetch": { "post": { "operationId": "fetchOrgSettings", "summary": "Sync org settings", "description": "Queues an org-settings sync (providers, locations, visit types, etc.) against the connected EMR.", "tags": ["Org Settings"], "x-supported-emrs": [ "Athena", "eClinicalWorks", "ModmedGastro", "ModmedEMA", "PracticeFusion", "EZDERM", "WebPt", "TheraNest", "Nextech", "NextechPM", "Credible" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": [ "Athena", "eClinicalWorks", "ModmedGastro", "ModmedEMA", "PracticeFusion", "EZDERM", "WebPt", "TheraNest", "Nextech", "NextechPM", "Credible" ], "description": "URLs to receive the org_settings.synced webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "Athena", "eClinicalWorks", "ModmedGastro", "ModmedEMA", "PracticeFusion", "EZDERM", "WebPt", "TheraNest", "Nextech", "NextechPM", "Credible" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Org settings sync queued; results delivered by webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "queued" }, "message": { "type": "string", "example": "Org settings sync queued" }, "job_execution_id": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } }, "required": [ "success", "status", "message", "job_execution_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "An org settings sync is already in progress for this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "status": { "type": "string", "example": "in_progress" }, "message": { "type": "string", "example": "An org settings sync is already in progress" }, "job_execution_id": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } }, "required": [ "success", "status", "message", "job_execution_id" ] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/patients/{patient_mrn}/insurances": { "post": { "operationId": "addPatientInsurance", "summary": "Add insurance to a patient", "description": "Queues an insurance record for creation on a patient in the connected EMR.", "tags": ["Patient Insurances"], "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "parameters": [ { "name": "patient_mrn", "in": "path", "description": "Patient MRN.", "schema": { "type": "string", "example": "12345" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["member_id"], "properties": { "member_id": { "type": "string", "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Insurance member / subscriber ID.", "example": "MEM123456789", "x-required-for-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ] }, "group_id": { "type": "string", "x-supported-emrs": [ "Experity", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Insurance group number.", "example": "GRP98999" }, "insurance_provider_id": { "type": "string", "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Cobalt insurance provider ID (one insurance identifier). Use GET /v1/insurance-providers to retrieve valid IDs.", "example": "insurance-provider-123" }, "insurance_payer_id": { "type": "string", "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Insurance payer ID, used to disambiguate insurance_name.", "example": "98999" }, "insurance_name": { "type": "string", "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Insurance provider name (one insurance identifier).", "example": "Blue Cross Anthem" }, "subscriber_demographics": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Subscriber's first name.", "example": "Jane" }, "last_name": { "type": "string", "description": "Subscriber's last name.", "example": "Doe" }, "street_line_1": { "type": "string", "description": "Subscriber's street address.", "example": "123 Main Street" }, "city": { "type": "string", "description": "Subscriber's city.", "example": "Los Angeles" }, "state": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "description": "Two-letter US state code.", "example": "CA" }, "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$", "description": "5- or 9-digit ZIP code.", "example": "90001" }, "sex": { "type": "string", "enum": ["M", "F"], "description": "Subscriber's sex.", "example": "F" }, "dob": { "type": "string", "format": "date", "description": "Subscriber's date of birth (YYYY-MM-DD).", "example": "1980-01-15" }, "phone": { "type": "string", "description": "Subscriber's phone number.", "example": "555-123-4567" } }, "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA" ], "description": "Policy holder demographics.", "x-required-for-emrs": ["Experity", "EZDERM"] }, "relationship_to_subscriber": { "type": "string", "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA" ], "description": "Patient relationship to the policy holder.", "example": "self", "x-required-for-emrs": ["Experity", "EZDERM", "ModmedEMA"] }, "insurance_policy_type": { "type": "string", "x-supported-emrs": ["EZDERM"], "description": "Insurance policy type / coverage category.", "example": "PPO", "x-required-for-emrs": ["EZDERM"] }, "insurance_sequence": { "type": "string", "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Coverage order (e.g. primary / secondary). Sent to the EMR by ModmedGastro and Credible; for every EMR, GET /v1/patients uses it to pick which active insurance to report.", "example": "primary" }, "plan_begin_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "x-supported-emrs": [ "Experity", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Plan begin date (YYYY-MM-DD).", "example": "2026-01-01", "x-required-for-emrs": ["eClinicalWorks"] }, "plan_end_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "x-supported-emrs": ["eClinicalWorks", "ModmedGastro"], "description": "Plan end date (YYYY-MM-DD). Omit for open-ended coverage.", "example": "2026-12-31" }, "copayment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "minimum": 0, "x-supported-emrs": [ "Experity", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Copayment amount.", "example": 25 }, "priority": { "type": "string", "enum": ["1", "2", "3"], "x-supported-emrs": [ "Experity", "eClinicalWorks", "ModmedEMA", "Credible" ], "description": "Insurance priority (1=primary, 2=secondary, 3=tertiary).", "example": "1" }, "update_patient_demographics": { "type": "boolean", "default": true, "x-supported-emrs": [], "description": "Reserved: whether to also update the patient demographics in the EMR. Defaults to true. Accepted, but no EMR uses it, so it has no effect.", "example": true }, "update_if_exists": { "type": "boolean", "x-supported-emrs": ["Experity", "EZDERM", "ModmedEMA"], "description": "Update the matching insurance if one already exists instead of adding a new record. Defaults to false. For ModmedEMA it only makes relationship_to_subscriber optional (the policy is filed as SELF).", "example": false }, "check_eligibility": { "type": "boolean", "x-supported-emrs": ["Experity"], "description": "Run an eligibility check after the insurance is added. Defaults to false.", "example": false }, "include_inactive_patients": { "type": "boolean", "x-supported-emrs": ["eClinicalWorks"], "description": "Also match a patient chart that is inactive in the EMR when looking up the patient. Defaults to false (active charts only).", "example": false }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "URLs to receive the completion webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "Experity", "EZDERM", "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Credible" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Operation queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Patient insurance queued for processing" }, "patient_insurance_id": { "type": "string", "example": "d4e5f6a1b2c3478899aabbccddeeff00" }, "job_id": { "type": "integer", "example": 12345 } }, "required": [ "success", "message", "patient_insurance_id", "job_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/patients/{patient_mrn}/insurances/{emr_insurance_id}": { "patch": { "operationId": "updatePatientInsurance", "summary": "Update a patient insurance record", "description": "Queues an update to an existing insurance record on a patient in the connected EMR.", "tags": ["Patient Insurances"], "x-supported-emrs": ["eClinicalWorks", "Credible", "Athena"], "parameters": [ { "name": "patient_mrn", "in": "path", "description": "Patient MRN.", "schema": { "type": "string", "example": "12345" }, "required": true }, { "name": "emr_insurance_id", "in": "path", "description": "EMR insurance record ID. Returned as emr_insurance_id in patient live fetch and create/update success webhooks.", "schema": { "type": "string", "example": "51638" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "member_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Insurance member / subscriber ID.", "example": "MEM123456789" }, "group_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Insurance group number.", "example": "GRP98999" }, "insurance_provider_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Cobalt insurance provider ID (one insurance identifier). Use GET /v1/insurance-providers to retrieve valid IDs.", "example": "insurance-provider-123" }, "insurance_payer_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Insurance payer ID, used to disambiguate insurance_name.", "example": "98999" }, "insurance_name": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Insurance provider name (one insurance identifier).", "example": "Blue Cross Anthem" }, "subscriber_demographics": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Subscriber's first name.", "example": "Jane" }, "last_name": { "type": "string", "description": "Subscriber's last name.", "example": "Doe" }, "street_line_1": { "type": "string", "description": "Subscriber's street address.", "example": "123 Main Street" }, "city": { "type": "string", "description": "Subscriber's city.", "example": "Los Angeles" }, "state": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "description": "Two-letter US state code.", "example": "CA" }, "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$", "description": "5- or 9-digit ZIP code.", "example": "90001" }, "sex": { "type": "string", "enum": ["M", "F"], "description": "Subscriber's sex.", "example": "F" }, "dob": { "type": "string", "format": "date", "description": "Subscriber's date of birth (YYYY-MM-DD).", "example": "1980-01-15" }, "phone": { "type": "string", "description": "Subscriber's phone number.", "example": "555-123-4567" } }, "x-supported-emrs": ["eClinicalWorks"], "description": "Policy holder demographics." }, "relationship_to_subscriber": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Patient relationship to the policy holder.", "example": "self" }, "insurance_policy_type": { "type": "string", "x-supported-emrs": [], "description": "Insurance policy type / coverage category. Accepted, but no EMR uses it, so it has no effect.", "example": "PPO" }, "insurance_sequence": { "type": "string", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Coverage order (e.g. primary / secondary). Sent to the EMR by Credible; for every EMR, GET /v1/patients uses it to pick which active insurance to report.", "example": "primary" }, "plan_begin_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Plan begin date (YYYY-MM-DD).", "example": "2026-01-01" }, "plan_end_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "x-supported-emrs": ["eClinicalWorks"], "description": "Plan end date (YYYY-MM-DD). Omit for open-ended coverage.", "example": "2026-12-31" }, "copayment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "minimum": 0, "x-supported-emrs": [ "eClinicalWorks", "Credible", "Athena" ], "description": "Copayment amount. For Athena this is the Office Visit copay. Athena requires copayment and/or telehealth_copayment.", "example": 25 }, "telehealth_copayment": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "minimum": 0, "x-supported-emrs": ["Athena"], "description": "Telehealth copayment amount (Athena). Athena requires copayment and/or telehealth_copayment.", "example": 10 }, "include_inactive_patients": { "type": "boolean", "x-supported-emrs": ["eClinicalWorks"], "description": "Also match a patient chart that is inactive in the EMR when looking up the patient. Defaults to false (active charts only).", "example": false }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": [ "eClinicalWorks", "Credible", "Athena" ], "description": "URLs to receive the completion webhook, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "Credible", "Athena" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Operation queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Patient insurance queued for processing" }, "patient_insurance_id": { "type": "string", "example": "d4e5f6a1b2c3478899aabbccddeeff00" }, "job_id": { "type": "integer", "example": 12345 } }, "required": [ "success", "message", "patient_insurance_id", "job_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/patient-notes": { "post": { "operationId": "createPatientNote", "summary": "Create a patient chart note", "description": "Queues a free-standing patient chart note for creation in the connected EMR.", "tags": ["Patient Notes"], "x-supported-emrs": ["ModmedGastro", "eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["note", "patient_mrn", "subject"], "properties": { "note": { "type": "string", "x-supported-emrs": ["ModmedGastro", "eClinicalWorks"], "description": "Chart note body text.", "example": "Patient called to report improved symptoms after starting the new medication.", "x-required-for-emrs": ["ModmedGastro", "eClinicalWorks"] }, "patient_mrn": { "type": "string", "x-supported-emrs": ["ModmedGastro", "eClinicalWorks"], "description": "Medical Record Number of the patient the note is for.", "example": "12345", "x-required-for-emrs": ["ModmedGastro", "eClinicalWorks"] }, "subject": { "type": "string", "x-supported-emrs": ["ModmedGastro", "eClinicalWorks"], "description": "Note subject / title.", "example": "Follow-up call", "x-required-for-emrs": ["ModmedGastro", "eClinicalWorks"] }, "location_id": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "EMR location ID the note belongs to. Validated against the account’s locations.", "example": "location-1", "x-required-for-emrs": ["ModmedGastro"] }, "tags": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "One or more note category names (eClinicalWorks \"Additional Notes\" tags). Matched case-insensitively against the practice’s configured categories (`patient_note_tags` on GET /v1/settings); an unmatched category fails the note.", "example": ["General Notes"], "x-required-for-emrs": ["eClinicalWorks"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["ModmedGastro", "eClinicalWorks"], "description": "URLs to receive the completion webhook for this note, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["ModmedGastro", "eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Patient note queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Patient note queued for creation" }, "patient_note_id": { "type": "string", "example": "e5f6a1b2c3d4478899aabbccddeeff00" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": [ "success", "message", "patient_note_id", "job_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/patients": { "post": { "operationId": "createPatient", "summary": "Create a patient", "description": "Queues a patient for creation in the connected EMR.", "tags": ["Patients"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "description": "Patient first name.", "example": "Jane" }, "last_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "description": "Patient last name.", "example": "Doe" }, "dob": { "type": ["string", "null"], "format": "date", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "description": "Date of birth (YYYY-MM-DD).", "example": "1980-01-15" }, "sex": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "description": "Patient sex: male, female, or unknown.", "example": "female" }, "ssn": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Social Security Number, 9 digits, no dashes.", "example": "123456789" }, "phone": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "GreenwayHealth", "Credible" ], "description": "Primary phone (222-333-4444).", "example": "555-123-4567" }, "email": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "description": "Patient email.", "example": "jane.doe@example.com" }, "referring_provider_first_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "ModmedGastro", "Credible" ], "description": "Referring provider first name (provide with last name, or use referring_provider_id).", "example": "Jane" }, "referring_provider_last_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "ModmedGastro", "Credible" ], "description": "Referring provider last name.", "example": "Doe" }, "referring_provider_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Cobalt referring-provider UUID (from GET /v1/referring-providers).", "example": "c3d4e5f6a1b2478899aabbccddeeff00" }, "referring_provider_npi": { "type": ["string", "null"], "x-supported-emrs": ["Credible"], "description": "Referring provider NPI.", "example": "1234567890" }, "pcp_first_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Primary care provider first name (provide with last name, or use pcp_id).", "example": "Jane" }, "pcp_last_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Primary care provider last name.", "example": "Doe" }, "pcp_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Cobalt UUID of the PCP (from GET /v1/referring-providers or GET /v1/providers).", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "insurance_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro" ], "description": "Primary insurance company name (or use insurance_provider_id). Must match the EMR settings exactly.", "example": "Blue Cross Anthem" }, "insurance_provider_id": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "description": "Cobalt insurance-provider UUID (from GET /v1/insurance-providers).", "example": "insurance-provider-123" }, "insurance_subscriber_number": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "GreenwayHealth" ], "description": "Primary insurance subscriber / member number. Required when insurance is provided.", "example": "INS123456789" }, "insurance_sequence": { "type": ["string", "null"], "x-supported-emrs": [], "description": "Insurance sequence: primary, secondary, or tertiary. Accepted, but no EMR uses it, so it has no effect.", "example": "primary" }, "insurance_policy_type": { "type": ["string", "null"], "x-supported-emrs": ["EZDERM", "GreenwayHealth"], "description": "Insurance policy type (e.g. PPO).", "example": "PPO" }, "plan_code": { "type": ["string", "null"], "x-supported-emrs": ["GreenwayHealth"], "description": "Insurance plan code. For Greenway, the payer identifier that signals insurance is being attached.", "example": "PLAN-001" }, "group_number": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "GreenwayHealth"], "description": "Insurance group number.", "example": "GRP98999" }, "secondary_insurance_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Secondary insurance company name (provide with its subscriber number). Must match the EMR settings exactly.", "example": "Blue Cross Anthem" }, "secondary_insurance_subscriber_number": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Secondary insurance subscriber / member number.", "example": "INS123456789" }, "emergency_contact_first_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Emergency contact first name (all four emergency_contact_* fields must be provided together).", "example": "Jane" }, "emergency_contact_last_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Emergency contact last name.", "example": "Doe" }, "emergency_contact_relation": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Emergency contact relationship to the patient.", "example": "spouse" }, "emergency_contact_phone": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Emergency contact phone (222-333-4444).", "example": "555-123-4567" }, "pharmacy_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "EMR pharmacy ID.", "example": "PHARM-123" }, "cell_phone": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "description": "Cell phone (222-333-4444).", "example": "555-987-6543" }, "middle_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "GreenwayHealth", "Credible" ], "description": "Patient middle name.", "example": "Anne" }, "mrn": { "type": ["string", "null"], "x-supported-emrs": [], "description": "Medical Record Number to assign the patient. Accepted, but no EMR uses it, so it has no effect.", "example": "12345" }, "document_url": { "type": ["string", "null"], "x-supported-emrs": [], "description": "URL of a document to attach to the patient. Accepted, but no EMR uses it, so it has no effect.", "example": "https://example.com/patient-doc.pdf" }, "referral_reason": { "type": ["string", "null"], "x-supported-emrs": [], "description": "Reason for the referral. Accepted, but no EMR uses it, so it has no effect.", "example": "Specialist consultation" }, "referral_type": { "type": ["string", "null"], "x-supported-emrs": [], "description": "Referral type. Accepted, but no EMR uses it, so it has no effect.", "example": "Internal" }, "referred_to_provider_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "ModmedGastro"], "description": "Referred-to provider EMR ID. Validated against the account's providers.", "example": "provider-123" }, "referred_to_location_id": { "type": ["string", "null"], "x-supported-emrs": [], "description": "Referred-to location EMR ID. Accepted, but no EMR uses it, so it has no effect.", "example": "location-1" }, "facility_id": { "type": ["string", "null"], "x-supported-emrs": [], "description": "EMR facility ID. Accepted, but no EMR uses it, so it has no effect.", "example": "FAC-123" }, "facility_name": { "type": ["string", "null"], "x-supported-emrs": [], "description": "EMR facility name. Accepted, but no EMR uses it, so it has no effect.", "example": "Main Hospital" }, "address_street": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "GreenwayHealth", "Credible" ], "description": "Street address line 1.", "example": "123 Main Street" }, "address_line2": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Street address line 2.", "example": "Apt 4B" }, "address_city": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "GreenwayHealth", "Credible" ], "description": "City.", "example": "Los Angeles" }, "address_county": { "type": ["string", "null"], "x-supported-emrs": ["ModmedGastro"], "description": "County.", "example": "Los Angeles County" }, "address_state": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "GreenwayHealth", "Credible" ], "description": "Two-letter U.S. state abbreviation.", "example": "CA" }, "address_zip": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedEMA", "GreenwayHealth", "Credible" ], "description": "5-digit U.S. ZIP code.", "example": "90001" }, "responsible_party": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "GreenwayHealth" ], "description": "Guarantor relationship to the patient. Allowed values vary by EMR (e.g. self, spouse, child, other).", "example": "self" }, "check_eligibility": { "type": ["string", "null"], "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Whether to run an eligibility check on creation.", "example": "false" }, "responsible_party_first_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "GreenwayHealth" ], "description": "Guarantor first name (required when responsible_party is not self).", "example": "Jane" }, "responsible_party_last_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "GreenwayHealth" ], "description": "Guarantor last name.", "example": "Doe" }, "responsible_party_sex": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "EZDERM"], "description": "Guarantor sex.", "example": "female" }, "responsible_party_dob": { "type": ["string", "null"], "format": "date", "x-supported-emrs": ["eClinicalWorks", "EZDERM"], "description": "Guarantor date of birth (YYYY-MM-DD).", "example": "1980-01-15" }, "responsible_party_phone": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "GreenwayHealth" ], "description": "Guarantor phone (222-333-4444).", "example": "555-123-4567" }, "responsible_party_email": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Guarantor email.", "example": "jane.doe@example.com" }, "responsible_party_address_line1": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Guarantor street address line 1.", "example": "123 Main Street" }, "responsible_party_address_line2": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Guarantor street address line 2.", "example": "Apt 4B" }, "responsible_party_address_city": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Guarantor city.", "example": "Los Angeles" }, "responsible_party_address_state": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Guarantor two-letter U.S. state abbreviation.", "example": "CA" }, "responsible_party_address_zip": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Guarantor 5-digit U.S. ZIP code.", "example": "90001" }, "location": { "type": ["string", "null"], "x-supported-emrs": [], "description": "EMR location ID. Validated against the account's locations. Accepted, but no EMR uses it, so it has no effect.", "example": "location-1" }, "nationality": { "type": ["string", "null"], "x-supported-emrs": ["ModmedGastro"], "description": "Patient nationality.", "example": "American" }, "marital_status": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "ModmedGastro", "Credible" ], "description": "Marital status.", "example": "Married" }, "billing_group": { "type": ["string", "null"], "x-supported-emrs": ["ModmedGastro"], "description": "Billing group.", "example": "Group A" }, "no_email_reason": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Reason the patient has no email, accepted in place of email.", "example": "Patient declined" }, "no_ssn_reason": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Reason the patient has no SSN, accepted in place of ssn.", "example": "Patient declined" }, "language": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Preferred language.", "example": "English" }, "race": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Patient race.", "example": "White" }, "ethnicity": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Patient ethnicity.", "example": "Not Hispanic or Latino" }, "release_of_info": { "type": ["string", "null"], "enum": ["true", "false", "Y", "M", "N", "I"], "x-supported-emrs": ["eClinicalWorks"], "description": "Release-of-information consent. Accepts true/false (true maps to Y, false to N) or an eClinicalWorks code: Y (release allowed), M (modified/restricted), N (no release), I (ANSI 5010 informed consent).", "example": "true" }, "rx_history_consent": { "type": ["string", "null"], "enum": ["true", "false", "Y", "N", "U"], "x-supported-emrs": ["eClinicalWorks"], "description": "Prescription-history consent. Accepts true/false (true maps to Y, false to N) or an eClinicalWorks code: Y (signed), N (denied), U (unasked).", "example": "true" }, "self_pay": { "type": ["string", "null"], "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks", "GreenwayHealth"], "description": "Whether the patient is self-pay. eClinicalWorks sends it to the EMR. For GreenwayHealth, 'true' waives the insurance fields the organization requires when plan_code is supplied.", "example": "false" }, "default_facility_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Default facility EMR ID for the patient.", "example": "FAC-123" }, "voice_enabled": { "type": ["string", "null"], "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Whether voice notifications are enabled.", "example": "true" }, "text_enabled": { "type": ["string", "null"], "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Whether text notifications are enabled.", "example": "true" }, "callback_urls": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth" ], "description": "URL(s) to receive the completion webhook for this patient, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "EZDERM", "ModmedGastro", "ModmedEMA", "PracticeFusion", "GreenwayHealth", "Credible" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Patient queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Patient queued for creation" }, "patient_id": { "type": "string", "example": "a1b2c3d4e5f6478899aabbccddeeff00" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "patient_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getPatients", "summary": "List patients", "description": "Returns the patients Cobalt has synced for the account, filtered by optional criteria and paginated.", "tags": ["Patients"], "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ], "parameters": [ { "name": "dob", "in": "query", "description": "Filter by date of birth (YYYY-MM-DD).", "schema": { "type": "string", "format": "date", "example": "1980-01-15" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "first_name", "in": "query", "description": "Filter by first name.", "schema": { "type": "string", "example": "Jane" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "last_name", "in": "query", "description": "Filter by last name.", "schema": { "type": "string", "example": "Doe" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "phone", "in": "query", "description": "Filter by phone.", "schema": { "type": "string", "example": "555-123-4567" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "cell_phone", "in": "query", "description": "Filter by cell phone.", "schema": { "type": "string", "example": "555-987-6543" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "mrn", "in": "query", "description": "Filter by Medical Record Number.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "ehr_id", "in": "query", "description": "Filter by EMR patient ID.", "schema": { "type": "string", "example": "patient-emr-123" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "address_state", "in": "query", "description": "Filter by two-letter U.S. state abbreviation.", "schema": { "type": "string", "example": "CA" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "status", "in": "query", "description": "Filter by status: active, inactive, or all (default active).", "schema": { "type": "string", "example": "active" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "include_inactive", "in": "query", "description": "Legacy toggle to include inactive patients. Prefer status. When true, inactive patients are returned alongside active ones.", "schema": { "type": "string", "enum": ["true", "false"], "example": "false" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "sort", "in": "query", "description": "Sort order by creation time: created_at (oldest first) or -created_at (newest first, default).", "schema": { "type": "string", "example": "-created_at" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "page", "in": "query", "description": "Page number (>= 1, default 1).", "schema": { "type": ["integer", "null"], "minimum": 1, "example": 1 }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] }, { "name": "page_size", "in": "query", "description": "Results per page (1–1000, default 100).", "schema": { "type": ["integer", "null"], "minimum": 1, "maximum": 1000, "example": 100 }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "Experity", "EZDERM", "GreenwayHealth", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "WebPt" ] } ], "responses": { "200": { "description": "Patients for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "patients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt patient ID (dashless UUID)." }, "ehr_id": { "type": ["string", "null"], "description": "Patient's EHR-native identifier. Null while the patient is pending creation or failed in the EHR; populated once the EHR record exists." }, "mrn": { "type": ["string", "null"], "description": "Medical Record Number." }, "first_name": { "type": ["string", "null"], "description": "Patient first name." }, "middle_name": { "type": ["string", "null"], "description": "Patient middle name." }, "last_name": { "type": ["string", "null"], "description": "Patient last name." }, "dob": { "type": ["string", "null"], "format": "date", "description": "Date of birth." }, "sex": { "type": "string", "description": "Patient sex: 'male', 'female', or 'unknown'." }, "language": { "type": ["string", "null"], "description": "Preferred language. Filled by a patient live fetch; see object_metadata.live_fetched_at." }, "race": { "type": ["string", "null"], "description": "Race. Filled by a patient live fetch; see object_metadata.live_fetched_at." }, "ethnicity": { "type": ["string", "null"], "description": "Ethnicity. Filled by a patient live fetch; see object_metadata.live_fetched_at." }, "deceased": { "type": ["boolean", "null"], "description": "Whether the patient is deceased. Filled by a patient live fetch; see object_metadata.live_fetched_at." }, "email": { "type": ["string", "null"], "description": "Patient email." }, "phone": { "type": ["string", "null"], "description": "Primary phone, standardized to (XXX) XXX-XXXX; null if unavailable or invalid." }, "cell_phone": { "type": ["string", "null"], "description": "Cell phone, standardized to (XXX) XXX-XXXX; null if unavailable or invalid." }, "phone_numbers": { "type": "object", "properties": { "primary": { "type": ["string", "null"] }, "cell": { "type": ["string", "null"] }, "home": { "type": ["string", "null"] }, "work": { "type": ["string", "null"] } }, "required": ["primary", "cell", "home", "work"], "description": "Standardized phone numbers. Each value is (XXX) XXX-XXXX or null." }, "insurance_name": { "type": ["string", "null"], "description": "Insurance payer name." }, "insurance_subscriber_number": { "type": ["string", "null"], "description": "Insurance subscriber number." }, "address_street": { "type": ["string", "null"], "description": "Address street." }, "address_city": { "type": ["string", "null"], "description": "Address city." }, "address_state": { "type": ["string", "null"], "description": "Address state." }, "address_zip": { "type": ["string", "null"], "description": "Address ZIP code." }, "pcp_first_name": { "type": ["string", "null"], "description": "Primary care provider first name." }, "pcp_last_name": { "type": ["string", "null"], "description": "Primary care provider last name." }, "status": { "type": ["string", "null"], "description": "Patient status." }, "rendering_provider_id": { "type": ["string", "null"], "description": "Cobalt rendering-provider ID associated with the patient." }, "inactivated_at": { "type": ["string", "null"], "format": "date-time", "description": "When the patient was inactivated, if applicable." }, "last_seen": { "type": ["string", "null"], "format": "date-time", "description": "Most recent patient activity timestamp, if available." }, "medications": { "description": "EMR-specific medication data, included when available." }, "problems": { "description": "EMR-specific problem-list data, included when available." }, "vitals": { "description": "EMR-specific vital-sign data, included when available." }, "insurances": { "type": "array", "items": { "$ref": "#/components/schemas/PatientInsurance" }, "description": "Synced EMR insurances, ordered by priority. Omitted when the sync has none. Currently Athena, and eClinicalWorks patients fetched with include=insurances." }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "Record creation timestamp." }, "object_metadata": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "cobalt_operation", "ehr_sync", "unknown" ], "description": "Provenance of the record." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created by Cobalt. Present only for cobalt_operation records." }, "live_fetched_at": { "type": ["string", "null"], "format": "date-time", "description": "When the patient was last live-fetched. Null if never. Fields marked \"Filled by a patient live fetch\" are null until then." } }, "required": ["source", "live_fetched_at"], "description": "Provenance metadata for the record." } }, "required": [ "id", "ehr_id", "mrn", "first_name", "middle_name", "last_name", "dob", "sex", "language", "race", "ethnicity", "deceased", "email", "phone", "cell_phone", "phone_numbers", "insurance_name", "insurance_subscriber_number", "address_street", "address_city", "address_state", "address_zip", "pcp_first_name", "pcp_last_name", "status", "rendering_provider_id", "inactivated_at", "last_seen", "created_at", "object_metadata" ] }, "example": [ { "id": "a1b2c3d4e5f6478899aabbccddeeff00", "ehr_id": "patient-emr-123", "mrn": "12345", "first_name": "Jane", "middle_name": "Anne", "last_name": "Doe", "dob": "1980-01-15", "sex": "female", "language": "English", "race": "White", "ethnicity": "Not Hispanic or Latino", "deceased": false, "email": "jane.doe@example.com", "phone": "(555) 123-4567", "cell_phone": "(555) 987-6543", "phone_numbers": { "primary": "(555) 123-4567", "cell": "(555) 987-6543", "home": null, "work": null }, "insurance_name": "Blue Cross Anthem", "insurance_subscriber_number": "INS123456789", "address_street": "123 Main Street", "address_city": "Los Angeles", "address_state": "CA", "address_zip": "90001", "pcp_first_name": "Jane", "pcp_last_name": "Doe", "status": "active", "rendering_provider_id": "b2c3d4e5f6a1478899aabbccddeeff00", "inactivated_at": null, "last_seen": "2026-06-15T21:30:00Z", "medications": [ { "name": "Lisinopril 10mg" } ], "problems": [ { "code": "I10", "description": "Essential hypertension" } ], "vitals": { "blood_pressure": "120/80" }, "insurances": [ { "emr_insurance_id": "51638", "priority": 1, "insurance_ehr_id": "insurance-provider-123", "insurance_name": "Blue Cross Anthem", "insurance_policy_type": "PPO", "insurance_subscriber_number": "INS123456789", "group_id": "GRP98999", "plan_begin_date": "2026-01-01", "plan_end_date": "2026-12-31", "copayment": "25", "relationship_to_subscriber": "self", "guarantor_id": "guarantor-123", "is_guarantor_patient": true, "active_status": "active", "eligibility_status": "eligible" } ], "created_at": "2026-06-15T21:00:00Z", "object_metadata": { "source": "cobalt_operation", "created_at": "2026-06-15T21:00:00Z", "live_fetched_at": "2026-06-15T21:30:00Z" } } ] }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 }, "total_count": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 100 } }, "required": [ "current_page", "total_pages", "total_count", "page_size" ] } }, "required": ["success", "patients", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/patients/{id}": { "patch": { "operationId": "updatePatient", "summary": "Update a patient", "description": "Updates a patient. For an already-created patient this queues an EMR update job; for a patient not yet created it edits the pending record in place.", "tags": ["Patients"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt patient ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "a1b2c3d4e5f6478899aabbccddeeff00" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Primary phone (222-333-4444).", "example": "555-123-4567" }, "cell_phone": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Cell phone (222-333-4444).", "example": "555-987-6543" }, "email": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Patient email.", "example": "jane.doe@example.com" }, "address_street": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Street address line 1.", "example": "123 Main Street" }, "address_line2": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Street address line 2.", "example": "Apt 4B" }, "address_city": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "City.", "example": "Los Angeles" }, "address_state": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Two-letter U.S. state abbreviation.", "example": "CA" }, "address_zip": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "5-digit U.S. ZIP code.", "example": "90001" }, "referring_provider_first_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Referring provider first name.", "example": "Jane" }, "referring_provider_last_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Referring provider last name.", "example": "Doe" }, "referring_provider_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Cobalt referring-provider UUID (from GET /v1/referring-providers).", "example": "c3d4e5f6a1b2478899aabbccddeeff00" }, "pcp_first_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Primary care provider first name.", "example": "Jane" }, "pcp_last_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Primary care provider last name.", "example": "Doe" }, "pcp_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Cobalt UUID of the PCP (from GET /v1/referring-providers or GET /v1/providers).", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "referred_to_provider_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Referred-to provider EMR ID.", "example": "provider-123" }, "language": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Preferred language.", "example": "English" }, "race": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Patient race.", "example": "White" }, "ethnicity": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Patient ethnicity.", "example": "Not Hispanic or Latino" }, "voice_enabled": { "type": ["string", "null"], "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Whether voice notifications are enabled.", "example": "true" }, "text_enabled": { "type": ["string", "null"], "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Whether text notifications are enabled.", "example": "true" }, "billing_notes": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Patient billing alert notes (free text).", "example": "Balance due at next visit." }, "pharmacy_id": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "EMR pharmacy ID (the ehr_id from GET /v1/pharmacies). Sets the patient's primary pharmacy, keeping any existing pharmacies and demoting the prior primary.", "example": "PHARM-123" }, "self_pay": { "type": ["string", "null"], "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Whether the patient is self-pay.", "example": "false" }, "first_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Patient first name.", "example": "Jane" }, "last_name": { "type": ["string", "null"], "x-supported-emrs": ["eClinicalWorks"], "description": "Patient last name.", "example": "Doe" }, "dob": { "type": ["string", "null"], "format": "date", "x-supported-emrs": ["eClinicalWorks"], "description": "Date of birth (YYYY-MM-DD).", "example": "1980-01-15" }, "team": { "type": ["string", "null"], "x-supported-emrs": ["Credible"], "description": "Team name (or numeric team id) to assign the client to. Assigning a team creates an episode for the client when one does not already exist.", "example": "TestClinic" }, "save_previous_address": { "type": ["string", "null"], "enum": ["true", "false"], "x-supported-emrs": ["eClinicalWorks"], "description": "Whether to keep the prior address on file when the address changes.", "example": "true" }, "callback_urls": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "URL(s) to receive the completion webhook for this update.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks", "Credible"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Patient update queued or applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Patient update queued" }, "patient_id": { "type": "string", "example": "a1b2c3d4e5f6478899aabbccddeeff00" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "patient_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An update is already in progress, or a failed create was resubmitted unchanged", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "message": { "type": "string", "example": "A patient update is already in progress" }, "patient_id": { "type": "null", "example": null } }, "required": ["success", "message"] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/patients/fetch": { "post": { "operationId": "liveFetchPatients", "summary": "Live-fetch patients", "description": "Queues an on-demand search for patients in the EMR. Results are delivered via webhook.", "tags": ["Patients"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "Sunwave", "EZDERM" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "search_by": { "type": ["string", "null"], "enum": ["name", "dob", "phone", "mrn"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "Sunwave", "EZDERM" ], "description": "Search mode: name, dob, phone, or mrn.", "example": "name", "x-allowed-values-for-emrs": { "Sunwave": ["mrn"], "EZDERM": ["name", "dob", "phone", "mrn"] } }, "first_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "EZDERM" ], "description": "Patient first name. At least one of first_name / last_name is required for name mode.", "example": "Jane" }, "last_name": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "EZDERM" ], "description": "Patient last name.", "example": "Doe" }, "dob": { "type": ["string", "null"], "format": "date", "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "EZDERM" ], "description": "Date of birth (YYYY-MM-DD). Required for dob mode.", "example": "1980-01-15" }, "phone": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "EZDERM" ], "description": "Phone (222-333-4444). Required for phone mode.", "example": "555-123-4567" }, "mrn": { "type": ["string", "null"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "Sunwave", "EZDERM" ], "description": "Medical Record Number. Required for mrn mode.", "example": "12345" }, "include": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "enum": [ "insurances", "tasks", "tasks.notes", "collections", "alerts", "support_persons", "problems", "medical_history", "labs", "labs.results", "sogi", "medications", "medications.full", "referrals", "rx_logs", "documents", "encounters", "encounters.details", "encounters.appointment_notes", "encounters.referral", "encounters.all", "episodes", "notes", "assessments", "care_plans", "clinical_notes", "medical", "treatment_plan", "point_of_care", "all_pages", "inactive_patients" ], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "Sunwave", "EZDERM" ], "description": "Additional chart sections to enrich, as a comma-separated string or an array of tokens. Accepted tokens depend on the EMR (see x-allowed-values-for-emrs).", "example": "insurances", "x-allowed-values-for-emrs": { "eClinicalWorks": [ "insurances", "tasks", "tasks.notes", "problems", "medical_history", "labs", "labs.results", "sogi", "medications", "medications.full", "referrals", "rx_logs", "encounters.details", "encounters.appointment_notes", "encounters.referral", "encounters.all", "all_pages", "inactive_patients" ], "Credible": [ "insurances", "documents", "encounters", "episodes", "notes", "assessments", "care_plans", "clinical_notes" ], "ModmedGastro": [ "insurances", "tasks", "tasks.notes", "collections", "alerts", "support_persons", "all_pages" ], "Sunwave": [ "notes", "assessments", "medical", "treatment_plan", "point_of_care" ], "EZDERM": ["insurances", "problems", "medical_history"] } }, "callback_urls": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "Sunwave", "EZDERM" ], "description": "URL(s) to receive the results webhook for this live fetch, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "eClinicalWorks", "Credible", "ModmedGastro", "Sunwave", "EZDERM" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "202": { "description": "Live-fetch request accepted; results delivered by webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Patient live fetch queued" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payments": { "post": { "operationId": "createPayment", "summary": "Create a payment", "description": "Queues a patient payment for posting to the connected EMR ledger.", "tags": ["Payments"], "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "patient_mrn", "payment_method", "reference_number", "location", "amount" ], "properties": { "patient_mrn": { "type": "string", "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Medical Record Number of the patient the payment is for.", "example": "12345", "x-required-for-emrs": ["ModmedEMA", "eClinicalWorks"] }, "payment_method": { "type": "string", "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Payment method (e.g. \"Card\", \"Cash\", \"Check\").", "example": "Card", "x-required-for-emrs": ["ModmedEMA", "eClinicalWorks"] }, "reference_number": { "type": "string", "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Payment reference number. Reusable — the controller does not de-duplicate.", "example": "#123456", "x-required-for-emrs": ["ModmedEMA", "eClinicalWorks"] }, "location": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "EMR location ID the payment is posted at.", "example": "1404", "x-required-for-emrs": ["ModmedEMA", "eClinicalWorks"] }, "amount": { "type": "number", "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Payment amount. Must be a positive number.", "example": 350, "x-required-for-emrs": ["ModmedEMA", "eClinicalWorks"] }, "notes": { "type": "string", "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Free-text notes for the payment.", "example": "Copay collected at the front desk." }, "deposit_date": { "type": "string", "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Deposit date (ISO 8601, YYYY-MM-DD). Defaults to today when omitted.", "example": "2026-06-15" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "URLs to receive the completion webhook for this payment, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Payment queued for posting", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Payment queued for posting" }, "payment_id": { "type": "string", "example": "f6a1b2c3d4e5478899aabbccddeeff00" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 12345 } }, "required": ["success", "message", "payment_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getPayments", "summary": "List payments", "description": "Returns the patient payments Cobalt has synced for the account, with the claims each payment is applied to.", "tags": ["Payments"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "start_date", "in": "query", "description": "Start of the payment date range (ISO 8601, YYYY-MM-DD), matched against deposit_date.", "schema": { "type": "string", "example": "2026-03-15" }, "required": true, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "end_date", "in": "query", "description": "End of the payment date range (ISO 8601, YYYY-MM-DD), matched against deposit_date.", "schema": { "type": "string", "example": "2026-03-20" }, "required": true, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "patient_mrn", "in": "query", "description": "Filter by patient Medical Record Number.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page_size", "in": "query", "description": "Items per page (max 1000).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 100 }, "required": false, "x-supported-emrs": ["eClinicalWorks"] } ], "responses": { "200": { "description": "Payments for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt payment ID." }, "emr_transaction_id": { "type": ["string", "null"], "description": "EMR payment ID." }, "status": { "type": "string", "description": "`created` for a payment posted through Cobalt, `synced` for a payment read from the EMR." }, "patient_mrn": { "type": ["string", "null"], "description": "Medical Record Number of the patient." }, "emr_patient_id": { "type": ["string", "null"], "description": "EMR patient ID of the payer." }, "payer_type": { "type": ["string", "null"], "description": "Who made the payment, e.g. `patient`." }, "payment_method": { "type": ["string", "null"], "description": "Payment type as recorded in the EMR, e.g. \"Credit Card (VISA)\", \"Cash\", \"Check\"." }, "amount": { "type": ["number", "null"], "description": "Payment amount." }, "unapplied_amount": { "type": ["number", "null"], "description": "Part of the amount not applied to a claim (amount minus the sum of allocations)." }, "reference_number": { "type": ["string", "null"], "description": "Check or reference number." }, "deposit_date": { "type": ["string", "null"], "description": "Date the payment was received (YYYY-MM-DD)." }, "batch_id": { "type": ["string", "null"], "description": "EMR payment batch ID." }, "location_id": { "type": ["string", "null"], "description": "EMR location (facility) ID." }, "location_name": { "type": ["string", "null"], "description": "EMR location (facility) name." }, "posted_by_emr_id": { "type": ["string", "null"], "description": "EMR user ID of the user who posted the payment." }, "posted_by_name": { "type": ["string", "null"], "description": "Name of the user who posted the payment." }, "epay_transaction_id": { "type": ["string", "null"], "description": "Card processor transaction ID for an electronic payment (eCW \"ePay trx Id\")." }, "notes": { "type": ["string", "null"], "description": "Payment memo." }, "voided": { "type": ["boolean", "null"], "description": "True when the payment is voided in the EMR." }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "claim_id": { "type": ["string", "null"], "description": "Cobalt claim ID, when Cobalt has synced the claim; otherwise null." }, "emr_claim_id": { "type": ["string", "null"], "description": "EMR claim number the payment is applied to." }, "emr_appointment_id": { "type": ["string", "null"], "description": "EMR appointment (encounter) ID of the claim." }, "emr_payment_detail_id": { "type": ["string", "null"], "description": "EMR ID of this application of the payment to the claim." }, "service_date": { "type": ["string", "null"], "description": "Claim service date (YYYY-MM-DD)." }, "amount": { "type": ["number", "null"], "description": "Amount of the payment applied to this claim." } }, "required": [ "claim_id", "emr_claim_id", "emr_appointment_id", "emr_payment_detail_id", "service_date", "amount" ], "example": { "claim_id": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_claim_id": "275001", "emr_appointment_id": "690012", "emr_payment_detail_id": "530120", "service_date": "2026-08-24", "amount": 75 } }, "description": "Claims the payment is applied to." }, "synced_at": { "type": ["string", "null"], "description": "When the payment was last read from the EMR." }, "created_at": { "type": "string", "description": "When the payment record was created." }, "updated_at": { "type": "string", "description": "When the payment record was updated." } }, "required": [ "id", "emr_transaction_id", "status", "patient_mrn", "emr_patient_id", "payer_type", "payment_method", "amount", "unapplied_amount", "reference_number", "deposit_date", "batch_id", "location_id", "location_name", "posted_by_emr_id", "posted_by_name", "epay_transaction_id", "notes", "voided", "allocations", "synced_at", "created_at", "updated_at" ], "example": { "id": "f6a1b2c3d4e5478899aabbccddeeff00", "emr_transaction_id": "200145", "status": "synced", "patient_mrn": "12345", "emr_patient_id": "48210", "payer_type": "patient", "payment_method": "Credit Card (VISA)", "amount": 75, "unapplied_amount": 0, "reference_number": null, "deposit_date": "2026-10-22", "batch_id": null, "location_id": "2", "location_name": "Main Office", "posted_by_emr_id": "51007", "posted_by_name": "Smith, Jane", "epay_transaction_id": "000000071234", "notes": null, "voided": false, "allocations": [ { "claim_id": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_claim_id": "275001", "emr_appointment_id": "690012", "emr_payment_detail_id": "530120", "service_date": "2026-08-24", "amount": 75 } ], "synced_at": "2026-10-23T09:00:00.000Z", "created_at": "2026-10-23T09:00:00.000Z", "updated_at": "2026-10-23T09:00:00.000Z" } }, "example": [ { "id": "f6a1b2c3d4e5478899aabbccddeeff00", "emr_transaction_id": "200145", "status": "synced", "patient_mrn": "12345", "emr_patient_id": "48210", "payer_type": "patient", "payment_method": "Credit Card (VISA)", "amount": 75, "unapplied_amount": 0, "reference_number": null, "deposit_date": "2026-10-22", "batch_id": null, "location_id": "2", "location_name": "Main Office", "posted_by_emr_id": "51007", "posted_by_name": "Smith, Jane", "epay_transaction_id": "000000071234", "notes": null, "voided": false, "allocations": [ { "claim_id": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_claim_id": "275001", "emr_appointment_id": "690012", "emr_payment_detail_id": "530120", "service_date": "2026-08-24", "amount": 75 } ], "synced_at": "2026-10-23T09:00:00.000Z", "created_at": "2026-10-23T09:00:00.000Z", "updated_at": "2026-10-23T09:00:00.000Z" } ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 100 }, "total_count": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 } }, "required": [ "page", "page_size", "total_count", "total_pages" ] } }, "required": ["success", "payments", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payments/{id}": { "get": { "operationId": "getPaymentById", "summary": "Get a payment", "description": "Returns a single payment by its Cobalt ID, with the claims it is applied to.", "tags": ["Payments"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt payment ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "f6a1b2c3d4e5478899aabbccddeeff00" }, "required": true } ], "responses": { "200": { "description": "The requested payment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "payment": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt payment ID." }, "emr_transaction_id": { "type": ["string", "null"], "description": "EMR payment ID." }, "status": { "type": "string", "description": "`created` for a payment posted through Cobalt, `synced` for a payment read from the EMR." }, "patient_mrn": { "type": ["string", "null"], "description": "Medical Record Number of the patient." }, "emr_patient_id": { "type": ["string", "null"], "description": "EMR patient ID of the payer." }, "payer_type": { "type": ["string", "null"], "description": "Who made the payment, e.g. `patient`." }, "payment_method": { "type": ["string", "null"], "description": "Payment type as recorded in the EMR, e.g. \"Credit Card (VISA)\", \"Cash\", \"Check\"." }, "amount": { "type": ["number", "null"], "description": "Payment amount." }, "unapplied_amount": { "type": ["number", "null"], "description": "Part of the amount not applied to a claim (amount minus the sum of allocations)." }, "reference_number": { "type": ["string", "null"], "description": "Check or reference number." }, "deposit_date": { "type": ["string", "null"], "description": "Date the payment was received (YYYY-MM-DD)." }, "batch_id": { "type": ["string", "null"], "description": "EMR payment batch ID." }, "location_id": { "type": ["string", "null"], "description": "EMR location (facility) ID." }, "location_name": { "type": ["string", "null"], "description": "EMR location (facility) name." }, "posted_by_emr_id": { "type": ["string", "null"], "description": "EMR user ID of the user who posted the payment." }, "posted_by_name": { "type": ["string", "null"], "description": "Name of the user who posted the payment." }, "epay_transaction_id": { "type": ["string", "null"], "description": "Card processor transaction ID for an electronic payment (eCW \"ePay trx Id\")." }, "notes": { "type": ["string", "null"], "description": "Payment memo." }, "voided": { "type": ["boolean", "null"], "description": "True when the payment is voided in the EMR." }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "claim_id": { "type": ["string", "null"], "description": "Cobalt claim ID, when Cobalt has synced the claim; otherwise null." }, "emr_claim_id": { "type": ["string", "null"], "description": "EMR claim number the payment is applied to." }, "emr_appointment_id": { "type": ["string", "null"], "description": "EMR appointment (encounter) ID of the claim." }, "emr_payment_detail_id": { "type": ["string", "null"], "description": "EMR ID of this application of the payment to the claim." }, "service_date": { "type": ["string", "null"], "description": "Claim service date (YYYY-MM-DD)." }, "amount": { "type": ["number", "null"], "description": "Amount of the payment applied to this claim." } }, "required": [ "claim_id", "emr_claim_id", "emr_appointment_id", "emr_payment_detail_id", "service_date", "amount" ], "example": { "claim_id": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_claim_id": "275001", "emr_appointment_id": "690012", "emr_payment_detail_id": "530120", "service_date": "2026-08-24", "amount": 75 } }, "description": "Claims the payment is applied to." }, "synced_at": { "type": ["string", "null"], "description": "When the payment was last read from the EMR." }, "created_at": { "type": "string", "description": "When the payment record was created." }, "updated_at": { "type": "string", "description": "When the payment record was updated." } }, "required": [ "id", "emr_transaction_id", "status", "patient_mrn", "emr_patient_id", "payer_type", "payment_method", "amount", "unapplied_amount", "reference_number", "deposit_date", "batch_id", "location_id", "location_name", "posted_by_emr_id", "posted_by_name", "epay_transaction_id", "notes", "voided", "allocations", "synced_at", "created_at", "updated_at" ], "example": { "id": "f6a1b2c3d4e5478899aabbccddeeff00", "emr_transaction_id": "200145", "status": "synced", "patient_mrn": "12345", "emr_patient_id": "48210", "payer_type": "patient", "payment_method": "Credit Card (VISA)", "amount": 75, "unapplied_amount": 0, "reference_number": null, "deposit_date": "2026-10-22", "batch_id": null, "location_id": "2", "location_name": "Main Office", "posted_by_emr_id": "51007", "posted_by_name": "Smith, Jane", "epay_transaction_id": "000000071234", "notes": null, "voided": false, "allocations": [ { "claim_id": "c1a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", "emr_claim_id": "275001", "emr_appointment_id": "690012", "emr_payment_detail_id": "530120", "service_date": "2026-08-24", "amount": 75 } ], "synced_at": "2026-10-23T09:00:00.000Z", "created_at": "2026-10-23T09:00:00.000Z", "updated_at": "2026-10-23T09:00:00.000Z" } } }, "required": ["success", "payment"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/pharmacies": { "get": { "operationId": "getPharmacies", "summary": "List pharmacies", "description": "Returns the pharmacy directory Cobalt has synced for the account.", "tags": ["Pharmacies"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "page", "in": "query", "description": "Page number. Every pharmacy is returned on one page. Accepted, but no EMR uses it, so it has no effect.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": [] }, { "name": "page_size", "in": "query", "description": "Results per page. Every pharmacy is returned on one page. Accepted, but no EMR uses it, so it has no effect.", "schema": { "type": "integer", "minimum": 1, "example": 100 }, "required": false, "x-supported-emrs": [] } ], "responses": { "200": { "description": "Pharmacies for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "pharmacies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt pharmacy ID (dashless UUID)." }, "ehr_id": { "type": "string", "description": "EMR pharmacy ID." }, "ncpdp_id": { "type": "string", "description": "NCPDP ID (standard pharmacy identifier)." }, "name": { "type": "string", "description": "Pharmacy name." }, "address": { "type": "object", "properties": { "address1": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } }, "description": "Pharmacy address." }, "phone": { "type": "string", "description": "Phone number." }, "email": { "type": "string", "description": "Email address." }, "status": { "type": "string", "description": "Pharmacy status (active / inactive)." } } }, "example": [ { "id": "a1b2c3d4e5f6478899aabbccddeeff00", "ehr_id": "PHARM-123", "ncpdp_id": "1234567", "name": "Main Street Pharmacy", "address": { "address1": "123 Main Street", "city": "Los Angeles", "state": "CA", "zip": "90001" }, "phone": "555-123-4567", "email": "pharmacy@example.com", "status": "active" } ] } }, "required": ["success", "pharmacies"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/providers": { "get": { "operationId": "getProviders", "summary": "List providers", "description": "Returns the providers Cobalt has synced for the account.", "tags": ["Providers"], "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "parameters": [ { "name": "ehr_id", "in": "query", "description": "Optional exact-match filter on the provider's EHR-native identifier; returns just that provider when supplied.", "schema": { "type": "string", "example": "provider-123" }, "required": false, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ] }, { "name": "page", "in": "query", "description": "Page number. Every provider is returned on one page. Accepted, but no EMR uses it, so it has no effect.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": [] }, { "name": "page_size", "in": "query", "description": "Results per page. Every provider is returned on one page. Accepted, but no EMR uses it, so it has no effect.", "schema": { "type": "integer", "minimum": 1, "example": 100 }, "required": false, "x-supported-emrs": [] } ], "responses": { "200": { "description": "Providers for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt provider ID (dashless UUID)." }, "ehr_id": { "type": "string", "description": "EMR provider ID." }, "timezone": { "type": "string", "description": "Account timezone." }, "npi": { "type": "string", "description": "National Provider Identifier." }, "specialty": { "type": "string", "description": "Provider specialty." }, "credentials": { "type": "string", "description": "Provider credentials." }, "name": { "type": "string", "description": "Provider name." }, "phone": { "type": ["string", "null"], "description": "Phone number." }, "fax": { "type": ["string", "null"], "description": "Fax number." }, "email": { "type": ["string", "null"], "description": "Email address." }, "address": { "type": "object", "properties": { "address1": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] }, "state": { "type": ["string", "null"] }, "zip": { "type": ["string", "null"] } }, "required": ["address1", "city", "state", "zip"], "description": "Provider address." }, "licenses": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["state_license", "dea"], "description": "License type." }, "number": { "type": "string", "description": "License number." }, "state": { "type": ["string", "null"], "description": "Issuing state." }, "effective_date": { "type": ["string", "null"], "format": "date" }, "expiration_date": { "type": ["string", "null"], "format": "date" }, "revoked": { "type": "boolean" } }, "required": [ "type", "number", "state", "effective_date", "expiration_date", "revoked" ] }, "description": "State licenses and DEA registrations." }, "taxonomy": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "description": { "type": ["string", "null"] } }, "required": ["code", "description"], "description": "Provider taxonomy code." }, "status": { "type": "string", "description": "Provider status (active / inactive)." }, "hide_in_availability": { "type": "boolean", "description": "Whether the provider is hidden from availability." }, "practice_locations": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "Practice locations." }, "hours": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "Working hours." }, "complaint_types": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "Complaint types, when present." } } }, "example": [ { "id": "b2c3d4e5f6a1478899aabbccddeeff00", "ehr_id": "provider-123", "timezone": "America/Los_Angeles", "npi": "1234567890", "specialty": "Cardiology", "credentials": "MD", "name": "Jane Doe", "phone": "555-123-4567", "fax": "555-123-4568", "email": "provider@example.com", "address": { "address1": "123 Main Street", "city": "Los Angeles", "state": "CA", "zip": "90001" }, "licenses": [ { "type": "state_license", "number": "A123456", "state": "CA", "effective_date": "2024-01-01", "expiration_date": "2027-12-31", "revoked": false }, { "type": "dea", "number": "AB1234563", "state": null, "effective_date": "2024-01-01", "expiration_date": "2027-12-31", "revoked": false } ], "taxonomy": { "code": "207Q00000X", "description": "Family Medicine" }, "status": "active", "hide_in_availability": false, "practice_locations": [ { "id": "location-1", "name": "Main Clinic" } ], "hours": [ { "day": "Monday", "shifts": [ { "start": "09:00", "end": "17:00" } ] } ], "complaint_types": [ { "id": "complaint-123", "name": "Annual checkup" } ] } ] } }, "required": ["success", "providers"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/providers/{id}": { "patch": { "operationId": "updateProvider", "summary": "Update a provider", "description": "Updates a provider’s status, hours, or availability by Cobalt ID.", "tags": ["Providers"], "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt provider ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "description": "Provider status. One of: \"active\", \"inactive\".", "example": "active" }, "hours": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "description": "Provider working hours (per-day shift definitions).", "example": [ { "day": "Monday", "shifts": [ { "start": "09:00", "end": "17:00" } ] } ] }, "hide_in_availability": { "type": "string", "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "description": "Whether to hide the provider from availability. One of: \"true\", \"false\".", "example": "false" } } } } } }, "responses": { "200": { "description": "Provider updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Provider updated" }, "provider_id": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" } }, "required": ["success", "message", "provider_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/providers/ehr/{ehr_id}": { "patch": { "operationId": "updateProviderByEhrId", "summary": "Update a provider by EMR ID", "description": "Updates a provider’s status, hours, or availability by EMR ID.", "tags": ["Providers"], "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "parameters": [ { "name": "ehr_id", "in": "path", "description": "EMR provider ID.", "schema": { "type": "string", "example": "provider-123" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "description": "Provider status. One of: \"active\", \"inactive\".", "example": "active" }, "hours": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "description": "Provider working hours (per-day shift definitions).", "example": [ { "day": "Monday", "shifts": [ { "start": "09:00", "end": "17:00" } ] } ] }, "hide_in_availability": { "type": "string", "x-supported-emrs": [ "Athena", "Credible", "eClinicalWorks", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "TheraNest", "WebPt" ], "description": "Whether to hide the provider from availability. One of: \"true\", \"false\".", "example": "false" } } } } } }, "responses": { "200": { "description": "Provider updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Provider updated" }, "provider_id": { "type": "string", "example": "b2c3d4e5f6a1478899aabbccddeeff00" } }, "required": ["success", "message", "provider_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/recalls": { "get": { "operationId": "listRecalls", "summary": "List recalls", "description": "Returns the recalls Cobalt has synced for the account, with optional filters.", "tags": ["Recalls"], "x-supported-emrs": ["ModmedGastro", "ModmedEMA"], "parameters": [ { "name": "status", "in": "query", "description": "Filter by recall status (e.g. OPEN, CLOSED).", "schema": { "type": "string", "example": "OPEN" }, "required": false, "x-supported-emrs": ["ModmedGastro", "ModmedEMA"] }, { "name": "patient_mrn", "in": "query", "description": "Filter to a single patient's recalls by MRN.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": ["ModmedGastro", "ModmedEMA"] }, { "name": "patient_name", "in": "query", "description": "Filter by patient name (case-insensitive partial match). A lookup helper when the MRN is not known.", "schema": { "type": "string", "example": "Jane Doe" }, "required": false, "x-supported-emrs": ["ModmedGastro", "ModmedEMA"] }, { "name": "start_date", "in": "query", "description": "Only recalls due on/after this date (YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-08-01" }, "required": false, "x-supported-emrs": ["ModmedGastro", "ModmedEMA"] }, { "name": "end_date", "in": "query", "description": "Only recalls due on/before this date (YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-09-01" }, "required": false, "x-supported-emrs": ["ModmedGastro", "ModmedEMA"] } ], "responses": { "200": { "description": "Recalls for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt recall ID." }, "emr_recall_id": { "type": "string", "description": "The EMR's recall ID." }, "emr_patient_id": { "type": "string", "description": "The EMR's patient ID." }, "patient_mrn": { "type": "string", "description": "Patient MRN." }, "patient_name": { "type": "string", "description": "Patient name." }, "provider_id": { "type": "string", "description": "The EMR's provider ID." }, "provider_name": { "type": "string", "description": "Provider name." }, "recall_type": { "type": "string", "description": "Recall type name." }, "recall_description": { "type": "string", "description": "Recall reason." }, "recall_date": { "type": "string", "description": "Target due date." }, "notes": { "type": "string", "description": "Recall notes." }, "status": { "type": "string", "description": "Recall status." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "example": { "id": "recall-abc-123", "emr_recall_id": "recall-emr-123", "emr_patient_id": "patient-123", "patient_mrn": "12345", "patient_name": "Jane Doe", "provider_id": "provider-123", "provider_name": "Dr. Alex Smith", "recall_type": "Inbound Referral 1 Week", "recall_description": "Specialist consultation", "recall_date": "2026-09-01", "notes": "Call patient to schedule follow-up.", "status": "OPEN", "created_at": "2026-08-25T09:00:00Z", "updated_at": "2026-08-25T09:00:00Z" } }, "example": [ { "id": "recall-abc-123", "emr_recall_id": "recall-emr-123", "emr_patient_id": "patient-123", "patient_mrn": "12345", "patient_name": "Jane Doe", "provider_id": "provider-123", "provider_name": "Dr. Alex Smith", "recall_type": "Inbound Referral 1 Week", "recall_description": "Specialist consultation", "recall_date": "2026-09-01", "notes": "Call patient to schedule follow-up.", "status": "OPEN", "created_at": "2026-08-25T09:00:00Z", "updated_at": "2026-08-25T09:00:00Z" } ] } }, "required": ["success", "data"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createRecall", "summary": "Create a recall", "description": "Queues a recall for creation in the connected EMR.", "tags": ["Recalls"], "x-supported-emrs": ["ModmedEMA"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["patient_mrn", "recall_type", "due_date"], "properties": { "patient_mrn": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "MRN of the patient the recall is for.", "example": "12345", "x-required-for-emrs": ["ModmedEMA"] }, "recall_type": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "Exact recall type name as configured in the EMR.", "example": "Inbound Referral 1 Week", "x-required-for-emrs": ["ModmedEMA"] }, "due_date": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "Target due date (YYYY-MM-DD).", "example": "2026-09-01", "x-required-for-emrs": ["ModmedEMA"] }, "provider_ehr_id": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "EMR provider id for the recall. Supply this or provider_name (id preferred).", "example": "provider-123" }, "provider_name": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "Provider name as synced. Used only when provider_ehr_id is absent.", "example": "Dr. Alex Smith" }, "reason": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "Free-text reason for the recall (ModMed EMA: max 100 characters).", "example": "Specialist consultation" }, "appt_notes": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "Initial note on the recall (ModMed EMA: max 255 characters).", "example": "Call patient to schedule follow-up." }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["ModmedEMA"], "description": "URLs to receive the completion webhook for this create.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["ModmedEMA"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Recall create queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "recall_id": { "type": "string", "example": "recall-abc-123" }, "job_id": { "type": "integer", "example": 1 } }, "required": ["success", "message", "recall_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/recalls/{id}": { "patch": { "operationId": "updateRecall", "summary": "Update a recall", "description": "Queues a status change and/or note for an existing recall in the connected EMR.", "tags": ["Recalls"], "x-supported-emrs": ["ModmedGastro"], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "example": "recall-abc-123" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "New recall status.", "example": "OPEN" }, "status_note": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "Optional note recorded alongside a status change.", "example": "Patient requested a follow-up call." }, "note": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "Note text to add to the recall.", "example": "Called patient to arrange follow-up." }, "note_type": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "Category for the added note.", "example": "General" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["ModmedGastro"], "description": "URLs to receive the completion webhook for this update.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["ModmedGastro"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Recall update queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "recall_id": { "type": "string", "example": "recall-abc-123" }, "job_id": { "type": "integer", "example": 1 } }, "required": ["success", "message", "recall_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/recalls/{id}/actions": { "post": { "operationId": "logRecallAction", "summary": "Add an action to a recall", "description": "Appends an action (and optional note) to an existing recall. A \"Closed - *\" action closes the recall.", "tags": ["Recalls"], "x-supported-emrs": ["ModmedEMA"], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "example": "recall-abc-123" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["action_taken"], "properties": { "action_taken": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "Exact activity type label to log (e.g. \"Phone Call\", \"Closed - Other\"). A \"Closed - *\" type closes the recall.", "example": "Phone Call", "x-required-for-emrs": ["ModmedEMA"] }, "note": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "Optional activity note (max 255 characters).", "example": "Called patient to arrange follow-up." }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["ModmedEMA"], "description": "URLs to receive the completion webhook for this action.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["ModmedEMA"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Recall action queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "recall_id": { "type": "string", "example": "recall-abc-123" }, "job_id": { "type": "integer", "example": 1 } }, "required": ["success", "message", "recall_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/referrals": { "post": { "operationId": "createReferral", "summary": "Create a referral", "description": "Queues a referral for creation in the connected EMR.", "tags": ["Referrals"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "patient_mrn", "referring_to_provider_ehr_id", "referring_from_provider_ehr_id", "priority", "reason", "direction" ], "properties": { "patient_mrn": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Medical Record Number of the patient the referral is for.", "example": "12345", "x-required-for-emrs": ["eClinicalWorks"] }, "referring_to_provider_ehr_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EHR ID of the provider being referred to. Validated against the provider directory for the referral direction; \"0\" means no provider on that side.", "example": "provider-123", "x-required-for-emrs": ["eClinicalWorks"] }, "referring_from_provider_ehr_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EHR ID of the provider making the referral. Validated against the provider directory for the referral direction; \"0\" means no provider on that side.", "example": "provider-456", "x-required-for-emrs": ["eClinicalWorks"] }, "priority": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referral priority. One of: routine, urgent, stat.", "example": "routine", "x-required-for-emrs": ["eClinicalWorks"] }, "reason": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Reason for the referral.", "example": "Specialist consultation", "x-required-for-emrs": ["eClinicalWorks"] }, "direction": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referral direction. One of: incoming, outgoing.", "example": "outgoing", "x-required-for-emrs": ["eClinicalWorks"] }, "diagnosis_codes": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "ICD-10 diagnosis codes associated with the referral.", "example": ["I10", "E11.9"] }, "prior_authorization_code": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Prior authorization code to write on the referral.", "example": "AUTH-12345" }, "specialty": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referral specialty name. Resolved against the EMR instance’s live specialty list by the worker.", "example": "Cardiology" }, "location_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR location ID of the facility being referred to. Validated against the account’s locations and written as the referral’s to-facility.", "example": "location-1" }, "start_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Date the referral becomes valid (ISO 8601, YYYY-MM-DD). Defaults to the referral creation date.", "example": "2026-09-01" }, "end_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Date the referral expires (ISO 8601, YYYY-MM-DD). Must be on or after start_date. Defaults to one year after start_date.", "example": "2027-09-14" }, "visits_allowed": { "type": "integer", "minimum": 0, "x-supported-emrs": ["eClinicalWorks"], "description": "Number of visits the referral allows.", "example": 14 }, "assigned_to_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR staff ID of the user the referral is assigned to. Validated against the account’s synced staff list; valid ids are the `ehr_id` values from GET /v1/staff.", "example": "STAFF-123" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content_base64": { "type": "string" } }, "required": ["filename", "content_base64"] }, "x-supported-emrs": ["eClinicalWorks"], "description": "Documents to attach to the referral, supplied inline. Each item is { filename, content_base64 }; filename must include a file extension.", "example": [ { "filename": "referral-letter.pdf", "content_base64": "JVBERi0xLjQKJcOkw7zDtsOfCg==" } ] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this referral, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Referral queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "referral_id": { "type": "string", "example": "c624cd97fc684b4587d98e258ab9ff10" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 1234 } }, "required": ["success", "message", "referral_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getReferrals", "summary": "List referrals", "description": "Returns the referrals Cobalt has synced for the account, with filtering and pagination.", "tags": ["Referrals"], "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"], "parameters": [ { "name": "start_date", "in": "query", "description": "Start of the referral date range (ISO 8601, YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-15" }, "required": true, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "end_date", "in": "query", "description": "End of the referral date range (ISO 8601, YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-20" }, "required": true, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "patient_mrn", "in": "query", "description": "Filter by patient Medical Record Number.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "status", "in": "query", "description": "Filter by referral status.", "schema": { "type": "string", "example": "Sent" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "priority", "in": "query", "description": "Filter by referral priority.", "schema": { "type": "string", "example": "routine" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "direction", "in": "query", "description": "Filter by referral direction (incoming, outgoing).", "schema": { "type": "string", "example": "outgoing" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "ehr_id", "in": "query", "description": "Filter by the referral’s EHR ID.", "schema": { "type": "string", "example": "referral-emr-123" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "receiving_line", "in": "query", "description": "Filter by the receiving line.", "schema": { "type": "string", "example": "555-123-4568" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "page_size", "in": "query", "description": "Items per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "example": 100 }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] }, { "name": "sort", "in": "query", "description": "Sort order. \"created_at\" sorts oldest-first; the default is newest-first.", "schema": { "type": "string", "enum": ["created_at"], "example": "created_at" }, "required": false, "x-supported-emrs": ["eClinicalWorks", "ModmedEMA", "Sunwave"] } ], "responses": { "200": { "description": "Referrals for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "referrals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt referral ID (dashless UUID)." }, "ehr_id": { "type": "string", "description": "EMR referral ID." }, "patient_ehr_id": { "type": "string", "description": "EMR patient ID." }, "patient_mrn": { "type": "string", "description": "Patient Medical Record Number." }, "patient_first_name": { "type": "string", "description": "Patient first name." }, "patient_last_name": { "type": "string", "description": "Patient last name." }, "patient_dob": { "type": "string", "format": "date", "description": "Patient date of birth." }, "from_provider_ehr_id": { "type": "string", "description": "Referring-from provider EHR ID." }, "from_provider_name": { "type": "string", "description": "Referring-from provider name." }, "to_provider_ehr_id": { "type": "string", "description": "Referring-to provider EHR ID." }, "to_provider_name": { "type": "string", "description": "Referring-to provider name." }, "priority": { "type": "string", "description": "Referral priority." }, "urgency": { "type": "string", "description": "Referral urgency." }, "reason": { "type": "string", "description": "Referral reason." }, "prior_authorization_code": { "type": "string", "description": "Prior authorization code." }, "specialty": { "type": "string", "description": "Referral specialty." }, "to_facility_name": { "type": "string", "description": "Name of the facility being referred to." }, "visits_used": { "type": ["integer", "null"], "description": "Visits used against the referral." }, "unit_type": { "type": ["string", "null"], "description": "Unit the referral counts in (e.g. visits)." }, "diagnosis_codes": { "type": "array", "items": { "type": "string" }, "description": "ICD-10 diagnosis codes." }, "document_ids": { "type": "array", "items": { "type": "string" }, "description": "Cobalt document IDs (dashless)." }, "direction": { "type": "string", "description": "Referral direction (incoming, outgoing)." }, "receiving_line": { "type": "string", "description": "Receiving line." }, "referral_source": { "type": "string", "description": "Referral source (e.g. referring organization)." }, "patient_email": { "type": "string", "description": "Patient email address." }, "patient_phone": { "type": "string", "description": "Patient phone number." }, "insurance_name": { "type": "string", "description": "Primary insurance payer name." }, "insurance_member_id": { "type": "string", "description": "Primary insurance member/subscriber ID." }, "insurance_group_number": { "type": "string", "description": "Primary insurance group number." }, "insurance_policy_status": { "type": "string", "description": "Primary insurance policy status." }, "insurance_effective_date": { "type": "string", "description": "Primary insurance policy effective date." }, "target_admission_date": { "type": "string", "format": "date", "description": "Target admission date for the referral/opportunity." }, "status": { "type": "string", "description": "Referral status." }, "referral_date": { "type": "string", "description": "Referral date (ISO 8601)." }, "last_activity_at": { "type": "string", "description": "Last activity timestamp (ISO 8601)." }, "synced_at": { "type": "string", "description": "When Cobalt last synced the referral (ISO 8601)." } }, "example": { "id": "c624cd97fc684b4587d98e258ab9ff10", "ehr_id": "referral-emr-123", "patient_ehr_id": "patient-123", "patient_mrn": "12345", "patient_first_name": "Jane", "patient_last_name": "Doe", "patient_dob": "1980-01-15", "from_provider_ehr_id": "provider-456", "from_provider_name": "Dr. Alex Smith", "to_provider_ehr_id": "provider-123", "to_provider_name": "Dr. Jordan Lee", "priority": "routine", "urgency": "routine", "reason": "Specialist consultation", "prior_authorization_code": "AUTH-12345", "specialty": "Cardiology", "to_facility_name": "Main Hospital", "visits_used": 2, "unit_type": "V (VISIT)", "diagnosis_codes": ["I10", "E11.9"], "document_ids": ["9cd3314db75d4ce692a46882006e9621"], "direction": "outgoing", "receiving_line": "555-123-4568", "referral_source": "Main Hospital", "patient_email": "jane.doe@example.com", "patient_phone": "555-123-4567", "insurance_name": "Blue Cross Anthem", "insurance_member_id": "MEM123456789", "insurance_group_number": "GRP98999", "insurance_policy_status": "active", "insurance_effective_date": "2026-01-01", "target_admission_date": "2026-09-01", "status": "Sent", "referral_date": "2026-09-01T09:00:00Z", "last_activity_at": "2026-09-01T10:00:00Z", "synced_at": "2026-09-01T10:05:00Z" } }, "example": [ { "id": "c624cd97fc684b4587d98e258ab9ff10", "ehr_id": "referral-emr-123", "patient_ehr_id": "patient-123", "patient_mrn": "12345", "patient_first_name": "Jane", "patient_last_name": "Doe", "patient_dob": "1980-01-15", "from_provider_ehr_id": "provider-456", "from_provider_name": "Dr. Alex Smith", "to_provider_ehr_id": "provider-123", "to_provider_name": "Dr. Jordan Lee", "priority": "routine", "urgency": "routine", "reason": "Specialist consultation", "prior_authorization_code": "AUTH-12345", "specialty": "Cardiology", "to_facility_name": "Main Hospital", "visits_used": 2, "unit_type": "V (VISIT)", "diagnosis_codes": ["I10", "E11.9"], "document_ids": ["9cd3314db75d4ce692a46882006e9621"], "direction": "outgoing", "receiving_line": "555-123-4568", "referral_source": "Main Hospital", "patient_email": "jane.doe@example.com", "patient_phone": "555-123-4567", "insurance_name": "Blue Cross Anthem", "insurance_member_id": "MEM123456789", "insurance_group_number": "GRP98999", "insurance_policy_status": "active", "insurance_effective_date": "2026-01-01", "target_admission_date": "2026-09-01", "status": "Sent", "referral_date": "2026-09-01T09:00:00Z", "last_activity_at": "2026-09-01T10:00:00Z", "synced_at": "2026-09-01T10:05:00Z" } ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 1 }, "total_count": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 } }, "required": [ "page", "page_size", "total_count", "total_pages" ] } }, "required": ["success", "referrals", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/referrals/{id}": { "patch": { "operationId": "updateReferral", "summary": "Update a referral", "description": "Queues an update to an existing EMR referral.", "tags": ["Referrals"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "id", "in": "path", "description": "Cobalt referral ID (UUID, with or without dashes).", "schema": { "type": "string", "example": "c624cd97fc684b4587d98e258ab9ff10" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referral priority (case-insensitive). One of: routine, urgent, stat.", "example": "routine" }, "status": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referral status. Resolved against the EMR instance’s live status list by the worker.", "example": "Sent" }, "reason": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Reason for the referral.", "example": "Specialist consultation" }, "notes": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Free-text notes to write on the referral.", "example": "Please schedule the patient within two weeks." }, "prior_authorization_code": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Prior authorization code to write on the referral.", "example": "AUTH-12345" }, "specialty": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referral specialty name. Resolved against the EMR instance’s live specialty list by the worker.", "example": "Cardiology" }, "location_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR location ID of the facility being referred to. Validated against the account’s locations and written as the referral’s to-facility.", "example": "location-1" }, "start_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Date the referral becomes valid (ISO 8601, YYYY-MM-DD).", "example": "2026-09-01" }, "end_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Date the referral expires (ISO 8601, YYYY-MM-DD). Must be on or after start_date.", "example": "2027-09-14" }, "visits_allowed": { "type": "integer", "minimum": 0, "x-supported-emrs": ["eClinicalWorks"], "description": "Number of visits the referral allows.", "example": 14 }, "assigned_to_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR staff ID of the user the referral is assigned to. Validated against the account’s synced staff list; valid ids are the `ehr_id` values from GET /v1/staff.", "example": "STAFF-123" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this update, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Referral update queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "referral_id": { "type": "string", "example": "c624cd97fc684b4587d98e258ab9ff10" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 1234 } }, "required": ["success", "message", "referral_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An update is already in progress for this referral", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false], "example": false }, "message": { "type": "string", "example": "An update is already in progress for this referral." } }, "required": ["success", "message"] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/referring-providers": { "post": { "operationId": "createReferringProvider", "summary": "Create a referring provider", "description": "Queues a referring provider for creation in the connected EMR.", "tags": ["Referring Providers"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["first_name", "last_name", "npi"], "properties": { "first_name": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referring provider first name.", "example": "Jane", "x-required-for-emrs": ["eClinicalWorks"] }, "last_name": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referring provider last name.", "example": "Doe", "x-required-for-emrs": ["eClinicalWorks"] }, "npi": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referring provider National Provider Identifier.", "example": "1234567890", "x-required-for-emrs": ["eClinicalWorks"] }, "middle_initial": { "type": "string", "x-supported-emrs": [], "description": "Referring provider middle initial. Not sent to the EMR. Accepted, but no EMR uses it, so it has no effect.", "example": "A" }, "speciality": { "type": "string", "x-supported-emrs": [], "description": "Referring provider speciality. Not sent to the EMR. Accepted, but no EMR uses it, so it has no effect.", "example": "Cardiology" }, "phone": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Phone number in XXX-XXX-XXXX format.", "example": "555-123-4567" }, "fax": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Fax number in XXX-XXX-XXXX format.", "example": "555-123-4568" }, "email": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Referring provider email address.", "example": "referrals@example-clinic.com" }, "address": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Street address.", "example": "123 Main Street" }, "city": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "City.", "example": "Los Angeles" }, "state": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "State code.", "example": "CA" }, "zip_code": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "ZIP code.", "example": "90001" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this referring provider, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Referring provider queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "referring_provider_id": { "type": "string", "example": "980a7e9525a34ca39bf39ba318448ace" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 1234 } }, "required": [ "success", "message", "referring_provider_id", "job_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getReferringProviders", "summary": "List referring providers", "description": "Returns the referring providers Cobalt has synced for the account, with filtering.", "tags": ["Referring Providers"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "first_name", "in": "query", "description": "Filter by first name.", "schema": { "type": "string", "example": "Jane" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "last_name", "in": "query", "description": "Filter by last name.", "schema": { "type": "string", "example": "Doe" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "phone", "in": "query", "description": "Filter by phone number.", "schema": { "type": "string", "example": "555-123-4567" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "fax", "in": "query", "description": "Filter by fax number.", "schema": { "type": "string", "example": "555-123-4568" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "npi", "in": "query", "description": "Filter by National Provider Identifier.", "schema": { "type": "string", "example": "1234567890" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "emr_referring_provider_id", "in": "query", "description": "Filter by the referring provider's EMR ID. Use this to resolve a referring provider's Cobalt id (for pcp_id) from the EMR ID you already hold.", "schema": { "type": "string", "example": "provider-123" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] } ], "responses": { "200": { "description": "Referring providers for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "referring_providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt referring-provider ID (dashless UUID)." }, "ehr_id": { "type": "string", "description": "EMR referring-provider ID." }, "name": { "type": "string", "description": "Full name." }, "first_name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "middle_initial": { "type": "string", "description": "Middle initial." }, "speciality": { "type": "string", "description": "Speciality." }, "phone": { "type": "string", "description": "Phone (XXX-XXX-XXXX), or null when unavailable." }, "fax": { "type": "string", "description": "Fax (XXX-XXX-XXXX), or null when unavailable." }, "email": { "type": "string", "description": "Email address." }, "npi": { "type": "string", "description": "National Provider Identifier." }, "address_street": { "type": "string", "description": "Street address." }, "address_city": { "type": "string", "description": "City." }, "address_state": { "type": "string", "description": "State code." }, "address_zip": { "type": "string", "description": "ZIP code." }, "object_metadata": { "type": "object", "properties": {}, "description": "Provenance metadata for the record." } }, "example": { "id": "980a7e9525a34ca39bf39ba318448ace", "ehr_id": "provider-123", "name": "Jane Doe", "first_name": "Jane", "last_name": "Doe", "middle_initial": "A", "speciality": "Cardiology", "phone": "555-123-4567", "fax": "555-123-4568", "email": "referrals@example-clinic.com", "npi": "1234567890", "address_street": "123 Main Street", "address_city": "Los Angeles", "address_state": "CA", "address_zip": "90001", "object_metadata": {} } }, "example": [ { "id": "980a7e9525a34ca39bf39ba318448ace", "ehr_id": "provider-123", "name": "Jane Doe", "first_name": "Jane", "last_name": "Doe", "middle_initial": "A", "speciality": "Cardiology", "phone": "555-123-4567", "fax": "555-123-4568", "email": "referrals@example-clinic.com", "npi": "1234567890", "address_street": "123 Main Street", "address_city": "Los Angeles", "address_state": "CA", "address_zip": "90001", "object_metadata": {} } ] } }, "required": ["success", "referring_providers"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/settings": { "get": { "operationId": "getSettings", "summary": "Get account settings", "description": "Returns the account settings along with synced visit types, visit statuses, and other reference data.", "tags": ["Settings"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Account settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "access_token_reference_id": { "type": "string", "example": "account-42" }, "visit_types": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "visit_statuses": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "required_patient_fields": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string", "example": "America/Los_Angeles" }, "staff_list": { "type": "array", "items": { "type": "object", "properties": { "ehr_id": { "type": "string", "description": "EMR staff id. Pass this wherever a request takes a staff id (e.g. assigned_to_id).", "example": "STAFF-123" }, "name": { "type": "string", "example": "Alex Smith" } }, "required": ["ehr_id", "name"] }, "description": "Synced staff roster. Same list as GET /v1/staff." }, "staff_groups": { "type": "array", "items": { "type": "object", "properties": { "ehr_id": { "type": "string", "description": "EMR staff id. Pass this wherever a request takes a staff id (e.g. assigned_to_id).", "example": "STAFF-123" }, "name": { "type": "string", "example": "Alex Smith" } }, "required": ["ehr_id", "name"] }, "description": "Synced staff groups that tasks can be assigned to (ModMed EMA) or notified (Nextech `notify_list`)." }, "phone_call_types": { "type": "array", "items": { "type": "object", "properties": { "ehr_id": { "type": "string", "description": "EMR staff id. Pass this wherever a request takes a staff id (e.g. assigned_to_id).", "example": "STAFF-123" }, "name": { "type": "string", "example": "Alex Smith" } }, "required": ["ehr_id", "name"] }, "description": "Synced task phone call types / categories. Pass an `ehr_id` as `phone_call_type_id` on POST /v1/tasks." }, "patient_note_tags": { "type": "array", "items": { "type": "object", "properties": { "ehr_id": { "type": "string", "description": "EMR staff id. Pass this wherever a request takes a staff id (e.g. assigned_to_id).", "example": "STAFF-123" }, "name": { "type": "string", "example": "Alex Smith" } }, "required": ["ehr_id", "name"] }, "description": "Synced patient note categories (eClinicalWorks). Pass a `name` in `tags` on POST /v1/patient-notes." }, "insurance_companies": {}, "policy_types": {}, "departments": {} }, "example": { "access_token_reference_id": "account-42", "visit_types": [ { "id": "NP", "name": "New Patient" } ], "visit_statuses": [ { "id": "scheduled", "name": "Scheduled" } ], "required_patient_fields": [ "first_name", "last_name", "dob" ], "timezone": "America/Los_Angeles", "staff_list": [ { "ehr_id": "STAFF-123", "name": "Alex Smith" } ], "staff_groups": [ { "ehr_id": "group-123", "name": "Clinical Team" } ], "phone_call_types": [ { "ehr_id": "13", "name": "Prescription Refill" } ], "patient_note_tags": [ { "ehr_id": "5", "name": "General Notes" } ], "insurance_companies": [ { "id": "insurance-provider-123", "name": "Blue Cross Anthem" } ], "policy_types": ["PPO"], "departments": [ { "id": "department-1", "name": "Primary Care" } ] } } }, "required": ["success", "data"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "updateSettings", "summary": "Update account settings", "description": "Updates the account's external reference id.", "tags": ["Settings"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["access_token_reference_id"], "properties": { "access_token_reference_id": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "Your external reference id for this account (echoed on webhook events).", "example": "account-42", "x-required-for-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] } } } } } }, "responses": { "200": { "description": "Updated account settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "access_token_reference_id": { "type": "string", "example": "account-42" } }, "required": ["access_token_reference_id"] } }, "required": ["success", "data"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/last-schedule-sync": { "get": { "operationId": "getLastScheduleSync", "summary": "Get last schedule sync", "description": "Returns the timestamp of the last completed appointment sync for the account.", "tags": ["Settings"], "x-supported-emrs": [ "Athena", "Credible", "DrChrono", "eClinicalWorks", "Experity", "EZDERM", "Modmed", "ModmedEMA", "ModmedGastro", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "WebPt" ], "responses": { "200": { "description": "Last completed appointment sync", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "last_sync": { "type": ["object", "null"], "properties": { "timestamp": { "type": "string" } }, "required": ["timestamp"], "description": "null when no sync has completed yet.", "example": { "timestamp": "2026-09-17T18:24:05.000Z" } }, "message": { "type": "string", "example": "Last completed appointment sync retrieved." } }, "required": ["success", "last_sync"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/visit-types": { "get": { "operationId": "getVisitTypes", "summary": "List visit types", "description": "Returns the visit types Cobalt has synced for the account.", "tags": ["Settings"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "WebPt", "TheraNest" ], "responses": { "200": { "description": "Visit types for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "example": [ { "id": "NP", "name": "New Patient" } ] } }, "required": ["success", "data"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/visit-statuses": { "get": { "operationId": "getVisitStatuses", "summary": "List visit statuses", "description": "Returns the visit statuses Cobalt has synced for the account, including statuses deactivated in the EMR (`active: false`). Only active statuses are accepted when updating an appointment.", "tags": ["Settings"], "x-supported-emrs": [ "eClinicalWorks", "Credible", "EZDERM", "ModmedEMA", "ModmedGastro", "PracticeFusion", "WebPt" ], "responses": { "200": { "description": "Visit statuses for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "EMR status code. Pass this as `status` when updating an appointment.", "example": "scheduled" }, "description": { "type": ["string", "null"], "example": "Scheduled" }, "active": { "type": "boolean", "description": "false when the status has been deactivated in the EMR. Inactive statuses are rejected on appointment updates.", "example": true } }, "required": ["code", "description", "active"] }, "example": [ { "code": "scheduled", "description": "Scheduled", "active": true } ] } }, "required": ["success", "data"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/staff": { "get": { "operationId": "getStaff", "summary": "List staff", "description": "Returns the staff Cobalt has synced for the account. Use an entry's `ehr_id` wherever a request takes a staff id (for example `assigned_to_id`). Same list as `staff_list` on GET /v1/settings.", "tags": ["Settings"], "x-supported-emrs": [ "eClinicalWorks", "ModmedEMA", "ModmedGastro", "Nextech" ], "responses": { "200": { "description": "Staff for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "ehr_id": { "type": "string", "description": "EMR staff id. Pass this wherever a request takes a staff id (e.g. assigned_to_id).", "example": "STAFF-123" }, "name": { "type": "string", "example": "Alex Smith" } }, "required": ["ehr_id", "name"] }, "example": [ { "ehr_id": "STAFF-123", "name": "Alex Smith" } ] } }, "required": ["success", "data"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/tasks": { "post": { "operationId": "createTask", "summary": "Create a task", "description": "Queues a task for creation in the connected EMR.", "tags": ["Tasks"], "x-supported-emrs": [ "EZDERM", "Nextech", "NextechPM", "ModmedGastro", "ModmedEMA", "eClinicalWorks" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["patient_mrn"], "properties": { "description": { "type": "string", "x-supported-emrs": [ "EZDERM", "Nextech", "NextechPM", "ModmedGastro", "ModmedEMA", "eClinicalWorks" ], "description": "Task description / body text. For ModMed EMA this is the task note. For eClinicalWorks this is the action Notes.", "example": "Call patient about lab results", "x-required-for-emrs": [ "EZDERM", "Nextech", "NextechPM", "ModmedGastro", "ModmedEMA" ] }, "patient_mrn": { "type": "string", "x-supported-emrs": [ "EZDERM", "Nextech", "NextechPM", "ModmedGastro", "ModmedEMA", "eClinicalWorks" ], "description": "Medical Record Number of the patient the task is about.", "example": "12345", "x-required-for-emrs": [ "EZDERM", "Nextech", "NextechPM", "ModmedGastro", "ModmedEMA", "eClinicalWorks" ] }, "subject": { "type": "string", "x-supported-emrs": [ "EZDERM", "ModmedGastro", "eClinicalWorks" ], "description": "Task subject / title. For eClinicalWorks this is the action Subject.", "example": "Lab results", "x-required-for-emrs": [ "EZDERM", "ModmedGastro", "eClinicalWorks" ] }, "assignee_user_id": { "type": "string", "x-supported-emrs": ["EZDERM"], "description": "EMR user ID to assign the task to.", "example": "STAFF-123", "x-required-for-emrs": ["EZDERM"] }, "phone_call_type_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["Nextech", "NextechPM"], "description": "Phone call type ID for the task (an `ehr_id` from `phone_call_types` on GET /v1/settings). For NextechPM, the to-do category ID.", "example": "1", "x-required-for-emrs": ["Nextech", "NextechPM"] }, "notify_list": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": [ "Nextech", "NextechPM", "ModmedGastro" ], "description": "Recipients to notify. For Nextech, group IDs (an `ehr_id` from `staff_groups` on GET /v1/settings); for ModMed Gastro, recipient tasking GUIDs.", "example": ["group-123"], "x-required-for-emrs": ["ModmedGastro"] }, "notify_staff_list": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["Nextech"], "description": "People to notify (an `ehr_id` from GET /v1/staff). Groups go in `notify_list`." }, "location_id": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "EMR location ID the task belongs to. Validated against the account’s locations.", "example": "location-1", "x-required-for-emrs": ["ModmedGastro"] }, "task_type": { "type": "string", "x-supported-emrs": [ "ModmedGastro", "ModmedEMA", "eClinicalWorks" ], "description": "Task type. For ModMed Gastro, a practice-specific label (defaults to \"General\"). For ModMed EMA, the task Type (e.g. \"Prescribe\", \"Communication\"), validated against the account. For eClinicalWorks, the action Type label (optional).", "example": "Communication", "x-required-for-emrs": ["ModmedEMA"] }, "details": { "type": "string", "x-supported-emrs": ["ModmedEMA"], "description": "ModMed EMA \"Details\" value (e.g. \"Medication\", \"Results\"), validated against the account.", "example": "Results", "x-required-for-emrs": ["ModmedEMA"] }, "assigned_to": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": [ "ModmedEMA", "eClinicalWorks", "NextechPM" ], "description": "Staff id to assign the task to. For ModMed EMA, a staff id (an `ehr_id` from GET /v1/staff) or staff-group id (from `staff_groups` on GET /v1/settings). For eClinicalWorks, the staff EHR id the action is assigned to (an `ehr_id` from GET /v1/staff). For NextechPM, one person (an `ehr_id` from GET /v1/staff).", "example": "STAFF-123", "x-required-for-emrs": ["ModmedEMA", "eClinicalWorks"] }, "facility_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Facility id the task is filed under. Optional; defaults to the account facility when the account has a single facility. Supported for ModMed EMA and eClinicalWorks.", "example": "FAC-123" }, "due_date": { "type": "string", "x-supported-emrs": ["ModmedEMA", "eClinicalWorks"], "description": "Task due date (ISO 8601, e.g. \"2026-11-25\"). Optional. Supported for ModMed EMA and eClinicalWorks.", "example": "2026-03-20" }, "start_date": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "eClinicalWorks action start date (ISO 8601, e.g. \"2026-11-25\"). Optional; defaults to the creation date.", "example": "2026-03-15" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "x-supported-emrs": ["eClinicalWorks", "NextechPM"], "description": "Task priority. Optional. For eClinicalWorks, one of \"Low\", \"Normal\", \"High\" (defaults to \"Normal\"). For NextechPM, the numeric to-do priority value, passed through as-is (defaults to 1).", "example": "Normal" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": [ "EZDERM", "Nextech", "NextechPM", "ModmedGastro", "ModmedEMA", "eClinicalWorks" ], "description": "URLs to receive the completion webhook for this task, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": [ "EZDERM", "Nextech", "NextechPM", "ModmedGastro", "ModmedEMA", "eClinicalWorks" ], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Task queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task queued for processing." }, "task_id": { "type": "string", "example": "task-123" }, "job_id": { "type": "integer", "example": 1 } }, "required": ["success", "message", "task_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/tasks/notes": { "post": { "operationId": "createTaskNote", "summary": "Append a note to a task", "description": "Appends a note to an existing EMR task.", "tags": ["Tasks"], "x-supported-emrs": ["ModmedGastro"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["emr_task_id", "note"], "properties": { "emr_task_id": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "EMR ID of the task to append the note to. Obtain it from the tasks[] array returned by POST /v1/patients/fetch with include: [\"tasks\"].", "example": "task-emr-123", "x-required-for-emrs": ["ModmedGastro"] }, "note": { "type": "string", "x-supported-emrs": ["ModmedGastro"], "description": "Note text to append to the task.", "example": "Called patient; left a message about their results.", "x-required-for-emrs": ["ModmedGastro"] }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["ModmedGastro"], "description": "URLs to receive the completion webhook for this task note.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["ModmedGastro"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Task note queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task queued for processing." }, "task_note_id": { "type": "string", "example": "task-note-123" }, "job_id": { "type": "integer", "example": 1 } }, "required": ["success", "message", "task_note_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/telephone-encounters/actions": { "post": { "operationId": "createTelephoneEncounterAction", "summary": "Add an action to a telephone encounter", "description": "Queues an action on an existing telephone encounter for creation in the connected EMR.", "tags": ["Telephone Encounter Actions"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["text"], "properties": { "appointment_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Cobalt appointment ID of the telephone encounter to act on (UUID, with or without dashes).", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "emr_appointment_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Legacy alias for appointment_id, still accepted for existing integrations.", "example": "appt-emr-789" }, "text": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Action text (the note/message to add to the encounter).", "example": "Called patient; left a message about their results.", "x-required-for-emrs": ["eClinicalWorks"] }, "is_high_priority": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Whether the action is high priority. One of: \"true\", \"false\".", "example": "false" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this action, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Telephone encounter action queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "action_id": { "type": "string", "example": "action-123" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 1234 } }, "required": ["success", "message", "action_id", "job_id"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/telephone-encounters": { "post": { "operationId": "createTelephoneEncounter", "summary": "Create a telephone encounter", "description": "Queues a telephone encounter for creation in the connected EMR.", "tags": ["Telephone Encounters"], "x-supported-emrs": ["eClinicalWorks"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "patient_mrn", "provider_id", "location_id", "assigned_to_id" ], "properties": { "patient_mrn": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Medical Record Number of the patient the encounter is for.", "example": "12345", "x-required-for-emrs": ["eClinicalWorks"] }, "provider_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR provider ID. Validated against the account’s providers.", "example": "provider-123", "x-required-for-emrs": ["eClinicalWorks"] }, "location_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR location ID. Validated against the account’s locations.", "example": "location-1", "x-required-for-emrs": ["eClinicalWorks"] }, "assigned_to_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR staff ID to assign the encounter to. Validated against the account’s staff; valid ids are the `ehr_id` values from GET /v1/staff.", "example": "staff-123", "x-required-for-emrs": ["eClinicalWorks"] }, "reason": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Reason for the encounter (max 50 characters).", "example": "Medication refill" }, "refill_medication_name": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Medication name for a refill request (2–50 characters).", "example": "Lisinopril 10mg" }, "pharmacy_ehr_id": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "EMR pharmacy ID for a refill request.", "example": "PHARM-123" }, "caller": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Who placed the call (max 100 characters).", "example": "Jane Doe (patient)" }, "message": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Free-text message for the encounter.", "example": "Patient requests a refill of their blood pressure medication." }, "is_high_priority": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Whether the encounter is high priority. One of: \"true\", \"false\". Defaults to \"false\".", "example": "false" }, "include_inactive_patients": { "type": "string", "x-supported-emrs": ["eClinicalWorks"], "description": "Also match a patient chart that is inactive in the EMR when looking up the patient. One of: \"true\", \"false\". Defaults to \"false\".", "example": "false" }, "callback_urls": { "type": "array", "items": { "type": "string" }, "x-supported-emrs": ["eClinicalWorks"], "description": "URLs to receive the completion webhook for this encounter, in addition to the account webhook.", "example": ["https://example.com/webhooks/cobalt"] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "x-supported-emrs": ["eClinicalWorks"], "description": "Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.", "example": "2027-06-15T14:30:00Z" } } } } } }, "responses": { "200": { "description": "Telephone encounter queued for creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "telephone_encounter_id": { "type": "string", "example": "encounter-123" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": 1234 } }, "required": [ "success", "message", "telephone_encounter_id", "job_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getTelephoneEncounters", "summary": "List telephone encounters", "description": "Lists telephone encounters stored from the EMR, newest first, with their status, assignee and actions.", "tags": ["Telephone Encounters"], "x-supported-emrs": ["eClinicalWorks"], "parameters": [ { "name": "start_date", "in": "query", "description": "Start of the date range (YYYY-MM-DD, inclusive), matched against the encounter date in the EHR.", "schema": { "type": "string", "example": "2026-03-15" }, "required": true, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "end_date", "in": "query", "description": "End of the date range (YYYY-MM-DD, inclusive).", "schema": { "type": "string", "example": "2026-03-20" }, "required": true, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "patient_mrn", "in": "query", "description": "Filter by patient Medical Record Number.", "schema": { "type": "string", "example": "12345" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "assigned_to_ehr_id", "in": "query", "description": "Filter by assignee: a staff `ehr_id` from GET /v1/staff.", "schema": { "type": "string", "example": "staff-123" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "assigned_to_name", "in": "query", "description": "Filter by assignee name as shown in the EHR (e.g. \"Smith, Jane\"), case- and space-insensitive.", "schema": { "type": "string", "example": "Smith, Alex" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "created_by", "in": "query", "description": "Filter by the user who created the encounter, as shown in the EHR (e.g. \"Smith, Jane\"), case- and space-insensitive.", "schema": { "type": "string", "example": "Smith, Alex" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "locked", "in": "query", "description": "\"true\" returns only addressed (locked) encounters; \"false\" only open ones.", "schema": { "type": "string", "enum": ["true", "false"], "example": "false" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "reason", "in": "query", "description": "Filter by a keyword in the reason, case-insensitive.", "schema": { "type": "string", "example": "refill" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page", "in": "query", "description": "Page number (default 1).", "schema": { "type": "string", "example": "1" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] }, { "name": "page_size", "in": "query", "description": "Results per page (1-100, default 100).", "schema": { "type": "string", "example": "100" }, "required": false, "x-supported-emrs": ["eClinicalWorks"] } ], "responses": { "200": { "description": "Telephone encounters for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "telephone_encounters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cobalt telephone encounter ID (dashless UUID). Use it to add an action with POST /v1/telephone-encounters/actions." }, "ehr_id": { "type": "string", "description": "Encounter ID in the EHR." }, "patient_mrn": { "type": ["string", "null"] }, "patient_ehr_id": { "type": ["string", "null"] }, "encounter_datetime": { "type": ["string", "null"], "description": "Encounter date and time in the EHR (ISO 8601)." }, "reason": { "type": ["string", "null"] }, "caller": { "type": ["string", "null"] }, "message": { "type": ["string", "null"] }, "notes": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["open", "addressed"], "description": "\"addressed\" once the encounter is locked in the EHR." }, "locked": { "type": "boolean" }, "locked_at": { "type": ["string", "null"], "description": "When the encounter was addressed (locked) in the EHR, from its audit log." }, "assigned_to_ehr_id": { "type": ["string", "null"], "description": "Assignee staff `ehr_id` (GET /v1/staff)." }, "assigned_to_name": { "type": ["string", "null"] }, "created_by": { "type": ["string", "null"], "description": "User who created the encounter in the EHR." }, "answered_by": { "type": ["string", "null"] }, "provider_ehr_id": { "type": ["string", "null"] }, "provider_name": { "type": ["string", "null"] }, "location_ehr_id": { "type": ["string", "null"] }, "location_name": { "type": ["string", "null"] }, "is_high_priority": { "type": "boolean" }, "has_attachment": { "type": "boolean" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "by": { "type": ["string", "null"] }, "at": { "type": ["string", "null"], "description": "ISO 8601." }, "text": { "type": "string" } }, "required": ["by", "at", "text"] }, "description": "Actions taken on the encounter, oldest first." }, "ehr_created_at": { "type": ["string", "null"] }, "ehr_updated_at": { "type": ["string", "null"] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "ehr_id", "patient_mrn", "patient_ehr_id", "encounter_datetime", "reason", "caller", "message", "notes", "status", "locked", "locked_at", "assigned_to_ehr_id", "assigned_to_name", "created_by", "answered_by", "provider_ehr_id", "provider_name", "location_ehr_id", "location_name", "is_high_priority", "has_attachment", "actions", "ehr_created_at", "ehr_updated_at", "created_at", "updated_at" ] }, "example": [ { "id": "encounter-123", "ehr_id": "85479379", "patient_mrn": "12345", "patient_ehr_id": "3912234", "encounter_datetime": "2026-06-15T21:30:00Z", "reason": "Medication refill", "caller": "Jane Doe (patient)", "message": "Patient requests a refill of their blood pressure medication.", "notes": null, "status": "addressed", "locked": true, "locked_at": "2026-06-15T21:30:00Z", "assigned_to_ehr_id": "staff-123", "assigned_to_name": "Smith, Alex", "created_by": "Doe, Jordan", "answered_by": "Doe, Jordan", "provider_ehr_id": "provider-123", "provider_name": "Lee, Sam", "location_ehr_id": "location-1", "location_name": "Main Clinic", "is_high_priority": false, "has_attachment": false, "actions": [ { "by": "Smith, Alex", "at": "2026-06-15T21:30:00Z", "text": "Called patient; left a message about their results." } ], "ehr_created_at": "2026-06-15T21:30:00Z", "ehr_updated_at": "2026-06-15T21:30:00Z", "created_at": "2026-06-15T21:30:00Z", "updated_at": "2026-06-15T21:30:00Z" } ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 25 }, "total_count": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 } }, "required": [ "page", "page_size", "total_count", "total_pages" ] } }, "required": ["success", "telephone_encounters", "pagination"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/webhook": { "get": { "operationId": "getWebhookConfig", "summary": "Get webhook configuration", "description": "Returns the configured webhook URLs and the signing secret for the account.", "tags": ["Webhooks"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Webhook configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "webhook_urls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": ["active", "inactive"], "description": "inactive: Cobalt stopped delivery to this URL because every delivery failed for 7 days." }, "deactivated_at": { "type": ["string", "null"], "description": "When the URL was made inactive." }, "deactivated_reason": { "type": ["string", "null"], "description": "Why the URL was made inactive." }, "warning": { "type": ["object", "null"], "properties": { "code": { "type": "string", "enum": ["delivery_failing"] }, "message": { "type": "string", "example": "Request processed." }, "failed_attempts": { "type": "integer", "example": 1 }, "last_error": { "type": ["string", "null"] }, "window_days": { "type": "integer", "example": 1 } }, "required": [ "code", "message", "failed_attempts", "last_error", "window_days" ], "description": "Set when every delivery to an active URL failed in the last window_days days (at least 20 attempts). Cobalt will mark the URL inactive. Fix the endpoint, or delete the URL if you no longer use it." } } }, "example": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "url": "https://example.com/hooks/cobalt", "status": "active", "deactivated_at": null, "deactivated_reason": null, "warning": { "code": "delivery_failing", "message": "Webhook deliveries have failed. Check your endpoint.", "failed_attempts": 20, "last_error": "HTTP 503 Service Unavailable", "window_days": 7 } } ] }, "webhook_secret_key": { "type": ["string", "null"], "example": "whsec_example_not_a_real_secret" } }, "required": ["success", "webhook_urls", "webhook_secret_key"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "addWebhookUrl", "summary": "Add a webhook URL", "description": "Registers an HTTPS URL to receive webhook events for the account.", "tags": ["Webhooks"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["webhook_url"], "properties": { "webhook_url": { "type": "string", "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "description": "HTTPS URL to receive webhook events.", "example": "https://example.com/hooks/cobalt", "x-required-for-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] } } } } } }, "responses": { "201": { "description": "Webhook URL added", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook URL added." }, "webhook_url": { "type": "string", "example": "https://example.com/hooks/cobalt" }, "webhook_id": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "webhook_secret_key": { "type": "string", "example": "whsec_example_not_a_real_secret" } }, "required": [ "success", "message", "webhook_url", "webhook_id", "webhook_secret_key" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/webhook/{id}": { "delete": { "operationId": "removeWebhookUrl", "summary": "Remove a webhook URL", "description": "Removes a registered webhook URL by its id.", "tags": ["Webhooks"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "parameters": [ { "name": "id", "in": "path", "description": "Webhook (or webhook event) ID.", "schema": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "required": true } ], "responses": { "200": { "description": "Webhook URL removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook URL removed." } }, "required": ["success", "message"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/webhook/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate the webhook secret", "description": "Rotates the webhook signing secret and returns the new value.", "tags": ["Webhooks"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Webhook secret rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook secret rotated." }, "webhook_secret_key": { "type": "string", "example": "whsec_example_not_a_real_secret" } }, "required": ["success", "message", "webhook_secret_key"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/webhook/test": { "post": { "operationId": "testWebhook", "summary": "Send a test webhook", "description": "Sends a test event to every configured webhook URL.", "tags": ["Webhooks"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "responses": { "200": { "description": "Test webhook sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request processed." }, "webhook_urls_count": { "type": "integer", "example": 1 }, "event": { "type": "object", "additionalProperties": {}, "example": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "object": "event", "type": "test", "created": "2026-09-17T18:24:05.000Z", "data": { "message": "Test webhook sent." } } } }, "required": [ "success", "message", "webhook_urls_count", "event" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/webhook-events": { "get": { "operationId": "getWebhookEvents", "summary": "List webhook events", "description": "Returns the webhook event history for the account, with filtering and pagination.", "tags": ["Webhooks"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "parameters": [ { "name": "event_type", "in": "query", "description": "Filter by event type.", "schema": { "type": "string", "example": "access_token.login_required" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, { "name": "status", "in": "query", "description": "Filter by delivery status.", "schema": { "type": "string", "example": "success" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, { "name": "start_date", "in": "query", "description": "Start of the created-at date range (ISO 8601, YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-15" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, { "name": "end_date", "in": "query", "description": "End of the created-at date range (ISO 8601, YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-03-20" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, { "name": "job_id", "in": "query", "description": "Filter by a single job id.", "schema": { "type": ["integer", "null"], "example": 1234 }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, { "name": "job_ids", "in": "query", "description": "Filter by multiple job ids, comma-separated (max 100). Returns an unpaginated list.", "schema": { "type": "string", "example": "1234,1235" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, { "name": "sort", "in": "query", "description": "Sort by created_at: \"created_at\" oldest first, \"-created_at\" newest first (default).", "schema": { "type": "string", "enum": ["created_at", "-created_at"], "example": "-created_at" }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] }, { "name": "page_size", "in": "query", "description": "Items per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "example": 100 }, "required": false, "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ] } ], "responses": { "200": { "description": "Webhook events for the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "webhook_events": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string", "description": "ID of the stored event. Matches the delivered event `id`.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "event_type": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventType" }, { "description": "Event type, e.g. `appointment.created`.", "example": "access_token.login_required" } ] }, "webhook_url": { "type": "string", "description": "URL the event was delivered to.", "example": "https://example.com/hooks/cobalt" }, "delivery_status": { "type": "string", "description": "Delivery outcome: `success`, `failed`, or `silent` (non-production).", "example": "success" }, "data": { "type": "object", "additionalProperties": {}, "description": "The delivered event's `data` object, verbatim. For an `access_token.*` event that includes `credential_id`.", "example": { "credential_id": "3f1c2a5e-9b7d-4c21-8f0a-6d5e4b3a2c10", "access_token_reference_id": "account-42", "emr_instance_domain": "https://example.ecwcloud.com", "message": "Invalid credentials detected - login required.", "error_type": "password_change_required" } }, "created_at": { "type": ["string", "null"], "example": "2026-09-17T18:24:05.000Z" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "integer", "example": 1 }, { "type": "null" } ], "description": "Job this event reports on, when it has one.", "example": 1234 }, "api_log_id": { "type": ["integer", "null"], "example": 1 }, "access_token_reference_id": { "type": ["string", "null"], "description": "Your own id for the account (`link_client_user_id`).", "example": "account-42" }, "access_token_id": { "type": ["string", "null"], "description": "Cobalt id of the account the event is for.", "example": "b7c4f1d2-8a3e-4b56-9c01-2d3e4f5a6b7c" } }, "required": [ "event_id", "event_type", "webhook_url", "delivery_status", "data", "created_at", "job_id", "api_log_id", "access_token_reference_id", "access_token_id" ] }, "example": [ { "event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "event_type": "access_token.login_required", "webhook_url": "https://example.com/hooks/cobalt", "delivery_status": "success", "data": { "credential_id": "3f1c2a5e-9b7d-4c21-8f0a-6d5e4b3a2c10", "access_token_reference_id": "account-42", "emr_instance_domain": "https://example.ecwcloud.com", "message": "Invalid credentials detected - login required.", "error_type": "password_change_required" }, "created_at": "2026-09-17T18:24:05.000Z", "job_id": 1234, "api_log_id": 1, "access_token_reference_id": "account-42", "access_token_id": "b7c4f1d2-8a3e-4b56-9c01-2d3e4f5a6b7c" } ] }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 }, "total_count": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 1 } }, "required": [ "current_page", "total_pages", "total_count", "page_size" ] } }, "required": ["success", "webhook_events"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/webhook-events/{id}": { "get": { "operationId": "getWebhookEventById", "summary": "Get a webhook event", "description": "Returns a single webhook event by its id.", "tags": ["Webhooks"], "x-supported-emrs": [ "eClinicalWorks", "Athena", "Credible", "DrChrono", "Experity", "EZDERM", "GreenwayHealth", "Modmed", "ModmedEMA", "ModmedGastro", "Nextech", "NextechPM", "OncoEMR", "PracticeFusion", "PTPracticePro", "Raintree", "Sunwave", "TheraNest", "WebPt" ], "parameters": [ { "name": "id", "in": "path", "description": "Webhook (or webhook event) ID.", "schema": { "type": "string", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "required": true } ], "responses": { "200": { "description": "The requested webhook event", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "webhook_event": { "type": "object", "properties": { "event_id": { "type": "string", "description": "ID of the stored event. Matches the delivered event `id`.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "event_type": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventType" }, { "description": "Event type, e.g. `appointment.created`.", "example": "access_token.login_required" } ] }, "webhook_url": { "type": "string", "description": "URL the event was delivered to.", "example": "https://example.com/hooks/cobalt" }, "delivery_status": { "type": "string", "description": "Delivery outcome: `success`, `failed`, or `silent` (non-production).", "example": "success" }, "data": { "type": "object", "additionalProperties": {}, "description": "The delivered event's `data` object, verbatim. For an `access_token.*` event that includes `credential_id`.", "example": { "credential_id": "3f1c2a5e-9b7d-4c21-8f0a-6d5e4b3a2c10", "access_token_reference_id": "account-42", "emr_instance_domain": "https://example.ecwcloud.com", "message": "Invalid credentials detected - login required.", "error_type": "password_change_required" } }, "created_at": { "type": ["string", "null"], "example": "2026-09-17T18:24:05.000Z" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "integer", "example": 1 }, { "type": "null" } ], "description": "Job this event reports on, when it has one.", "example": 1234 }, "api_log_id": { "type": ["integer", "null"], "example": 1 }, "access_token_reference_id": { "type": ["string", "null"], "description": "Your own id for the account (`link_client_user_id`).", "example": "account-42" }, "access_token_id": { "type": ["string", "null"], "description": "Cobalt id of the account the event is for.", "example": "b7c4f1d2-8a3e-4b56-9c01-2d3e4f5a6b7c" } }, "required": [ "event_id", "event_type", "webhook_url", "delivery_status", "data", "created_at", "job_id", "api_log_id", "access_token_reference_id", "access_token_id" ] } }, "required": ["success", "webhook_event"] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "webhooks": { "cobaltWebhookEvent": { "post": { "summary": "Webhook event delivery", "description": "Cobalt sends this request to each configured webhook URL when an event occurs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Webhook received." }, "204": { "description": "Webhook received with no response body." } } } } } }