Create Telephone Encounter

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

POST /telephone-encounters

Create Telephone Encounter

cURL

curl --request POST \
  --url https://api.usecobalt.com/v1/telephone-encounters \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "patient_mrn": "<string>",
  "provider_id": "<string>",
  "location_id": "<string>",
  "assigned_to_id": "<string>",
  "reason": "<string>",
  "refill_medication_name": "<string>",
  "pharmacy_ehr_id": "<string>",
  "caller": "<string>",
  "message": "<string>"
}
'

200

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

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.
• pharmacy_ehr_id (string, optional): Pharmacy’s EMR ID. If provided, the pharmacy must exist in your organization’s pharmacy list (validate via GET /v1/pharmacies). When used with a medication refill, the pharmacy will be associated with the encounter. If the pharmacy is not already in the patient’s pharmacy list, it will be added automatically.
• caller (string, optional, max 100 characters): Name of the person who called
• message (string, optional): Message content from the caller
• is_high_priority (string, optional): Whether this encounter should be marked as high priority. Must be “true” or “false”.
• template_name (string, optional): The template name to use when filling out the document upload form.

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",
    "pharmacy_ehr_id": "1643"
}'

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.

Pharmacy Not Found

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

This error occurs when pharmacy_ehr_id is present but no corresponding pharmacy can be found. Call GET /v1/pharmacies to see what available pharmacies there are.

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 string length: 50

refill_medication_name · string

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

Required string length: 2 - 50

pharmacy_ehr_id · string

Pharmacy's EMR ID (optional)

caller · string

Name of the person who called (optional, max 100 characters)

Maximum string length: 100

message · string

Message content from the caller (optional)

is_high_priority · enum<string>

Whether this encounter should be marked as high priority (optional). Must be "true" or "false"

Available options: true, false

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 · integer

Job execution identifier for tracking the async operation