Create Telephone Encounter
Telephone Encounters
Create Telephone Encounter
Creates a telephone encounter record in the provider’s EMR system.
POST
Create Telephone Encounter
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
The response includes:
Possible missing fields:
This error occurs when
This error occurs when
Sync locations using
This indicates an issue with your access token.
Your EMR system may not currently support telephone encounter creation.
Note:
Note: 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.
- caller (string, optional, max 100 characters): Name of the person who called
- message (string, optional, max 500 characters): Message content from the caller
Medication Refill Behavior
Whenrefill_medication_name is provided:
- Medication Search: The system searches the patient’s available medications for a match
- Filtering: Only refillable medications that are available for the patient are considered
- Matching: Medication names are matched case-insensitively with partial name support
- Success: If found, the encounter is created and the medication refill is added to it
- 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
Request with Medication Refill
Example Response
- 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
patient_mrn, provider_id, location_id, assigned_to_id
Reason Too Long
Medication Name Invalid Length
Provider Not Found
provider_id doesn’t exist in the providers table. Sync providers using GET /v1/providers.
Staff Member Not Found
assigned_to_id doesn’t exist in the staff list.
Location Not Found
GET /v1/locations to resolve this error.
User Not Found
Unsupported EMR
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
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: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
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:Authorizations
Body
application/json
Patient's Medical Record Number
Provider's EMR ID
Location's EMR ID
Staff member's EMR ID to assign the encounter to
Reason for telephone encounter (optional, max 50 characters)
Maximum string length:
50Medication name for refill request (optional, 2-50 characters)
Required string length:
2 - 50Name of the person who called (optional, max 100 characters)
Maximum string length:
100Message content from the caller (optional, max 500 characters)
Maximum string length:
500Response
Telephone encounter queued successfully