Create Telephone Encounter

Creates a telephone encounter record in the provider’s EMR system.

Telephone encounters are created in the provider’s EMR using an asynchronous processing model. Creating telephone encounters this way is not instantaneous.

Instead of leaving your POST request hanging until completion, we immediately return a success response if the request is properly formed. We then notify you via a webhook when the telephone encounter processing has completed.

This gives you flexibility around your user experience. For example, when you first make the /telephone-encounters call you can display a Processing status to your user and when you get the webhook notification you can update that to Completed.

Request Parameters

Required Fields

• patient_mrn (string, required): Patient’s Medical Record Number
• provider_id (string, required): Provider’s EMR ID
• location_id (string, required): Location’s EMR ID
• assigned_to_id (string, required): Assigned provider’s EMR ID

Optional Fields

• reason (string, optional, max 50 characters): Reason for telephone encounter
• refill_medication_name (string, optional, 2-50 characters): Name of medication to refill. If provided, the system will search for a matching medication in the patient’s available refillable medications and add it to the encounter. The medication name is matched case-insensitively and supports partial matches.

Medication Refill Behavior

When refill_medication_name is provided:

1. Medication Search: The system searches the patient’s available medications for a match
2. Filtering: Only refillable medications that are available for the patient are considered
3. Matching: Medication names are matched case-insensitively with partial name support
4. Success: If found, the encounter is created and the medication refill is added to it
5. Failure: If the medication is not found, the encounter is NOT created and an error is returned with a list of available medications

Example Request

Basic Request

curl -X POST https://api.usecobalt.com/v1/telephone-encounters \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "patient_mrn": "MRN-123456",
    "provider_id": "12241",
    "location_id": "25",
    "assigned_to_id": "12220",
    "reason": "Follow up on test results"
}'

Request with Medication Refill

curl -X POST https://api.usecobalt.com/v1/telephone-encounters \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "patient_mrn": "MRN-123456",
    "provider_id": "12241",
    "location_id": "25",
    "assigned_to_id": "12220",
    "reason": "Prescription refill",
    "refill_medication_name": "Lisinopril"
}'

Example Response

{
    "success": true,
    "message": "Telephone encounter processing. A webhook event will be sent upon completion.",
    "telephone_encounter_id": "123e4567e89b12d3a456426614174000",
    "job_id": 12345
}

The response includes:

• telephone_encounter_id: Unique identifier for the created telephone encounter record
• job_id: Job execution identifier for tracking the async operation

Error Responses

Missing Required Field

{
    "success": false,
    "message": "Missing required field: patient_mrn"
}

Possible missing fields: patient_mrn, provider_id, location_id, assigned_to_id

Reason Too Long

{
    "success": false,
    "message": "Reason exceeds maximum length of 50 characters"
}

Medication Name Invalid Length

{
    "success": false,
    "message": "refill_medication_name must be at least 2 characters"
}

{
    "success": false,
    "message": "refill_medication_name exceeds maximum length of 50 characters"
}

Provider Not Found

{
    "success": false,
    "message": "Provider with EMR ID '99999' not found."
}

This error occurs when provider_id doesn’t exist in the providers table. Sync providers using GET /v1/providers.

Staff Member Not Found

{
    "success": false,
    "message": "Staff member with ID '99999' not found."
}

This error occurs when assigned_to_id doesn’t exist in the staff list.

Location Not Found

{
    "success": false,
    "message": "Location with EMR ID '99999' not found."
}

Sync locations using GET /v1/locations to resolve this error.

User Not Found

{
    "success": false,
    "message": "User not found."
}

This indicates an issue with your access token.

Unsupported EMR

{
    "success": false,
    "message": "Telephone encounters are only supported for [EMR Name] EMR."
}

Your EMR system may not currently support telephone encounter creation.

Webhook Notifications

When the telephone encounter processing is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like:

Success

{
    "id": "<id-of-webhook-response>",
    "access_token_reference_id": "<access-token-reference-id>",
    "object": "event",
    "created": "2025-10-27T10:30:00Z",
    "type": "telephone_encounter.created",
    "job_id": "12345",
    "data": {
        "telephone_encounter_id": "123e4567e89b12d3a456426614174000",
        "emr_encounter_id": "ECW-98765",
        "patient_mrn": "MRN-123456",
        "provider_id": "12241",
        "location_id": "25",
        "assigned_to_id": "12220",
        "reason": "Follow up on test results",
        "refill_medication_name": "Lisinopril 10 MG"
    }
}

Note: refill_medication_name will be included in the webhook data if a medication refill was requested and successfully added.

Partial Success

When the encounter is created successfully but the medication refill fails to be added, a partial success webhook is sent:

{
    "id": "<id-of-webhook-response>",
    "access_token_reference_id": "<access-token-reference-id>",
    "object": "event",
    "created": "2025-10-27T10:35:00Z",
    "type": "telephone_encounter.created_partial",
    "job_id": "12345",
    "data": {
        "telephone_encounter_id": "123e4567e89b12d3a456426614174000",
        "emr_encounter_id": "ECW-98765",
        "patient_mrn": "MRN-123456",
        "provider_id": "12241",
        "location_id": "25",
        "assigned_to_id": "12220",
        "reason": "Prescription refill",
        "refill_medication_name": "Lisinopril",
        "refill_failure_reason": "Failed to add medication refill: Timeout error"
    }
}

Note: The telephone_encounter.created_partial event indicates that the encounter was successfully created in the EMR, but the requested medication refill could not be added. The encounter exists and is usable, but the refill will need to be added manually.

Failure

General Failure

{
    "id": "<id-of-webhook-response>",
    "access_token_reference_id": "<access-token-reference-id>",
    "object": "event",
    "created": "2025-10-27T10:35:00Z",
    "type": "telephone_encounter.failed",
    "job_id": "12345",
    "data": {
        "telephone_encounter_id": "123e4567e89b12d3a456426614174000",
        "patient_mrn": "MRN-123456",
        "refill_medication_name": null,
        "failure_reason": "Failed to create telephone encounter in EMR"
    }
}

Medication Not Found Failure

When a medication refill is requested but the medication cannot be found in the patient’s available medications, the encounter is NOT created and a failure webhook is sent with the list of available medications:

{
    "id": "<id-of-webhook-response>",
    "access_token_reference_id": "<access-token-reference-id>",
    "object": "event",
    "created": "2025-10-27T10:35:00Z",
    "type": "telephone_encounter.failed",
    "job_id": "12345",
    "data": {
        "telephone_encounter_id": "123e4567e89b12d3a456426614174000",
        "patient_mrn": "MRN-123456",
        "refill_medication_name": "Aspirin",
        "failure_reason": "Medication \"Aspirin\" not found in available refillable medications. Available medications: [\"Lisinopril 10 MG\",\"Metformin 500 MG\",\"Atorvastatin 20 MG\"]"
    }
}

Authorizations

client_id · string · header · required

client_secret · string · header · required

access_token · string · header · required

Body

application/json

patient_mrn · string · required

Patient's Medical Record Number

provider_id · string · required

Provider's EMR ID

location_id · string · required

Location's EMR ID

assigned_to_id · string · required

Staff member's EMR ID to assign the encounter to

reason · string

Reason for telephone encounter (optional, max 50 characters)

Maximum length: 50

refill_medication_name · string

Medication name for refill request (optional, 2-50 characters)

Required string length: 2 - 50

Response

200

application/json

Telephone encounter queued successfully

success · boolean

message · string

Example:

"Telephone encounter processing. A webhook event will be sent upon completion."

telephone_encounter_id · string

Unique identifier for the created telephone encounter record

job_id · string

Job execution identifier for tracking the async operation