Skip to main content
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

​
Example 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"
}'

​
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"
}

​
Provider Not Found

{
    "success": false,
    "message": "Provider with EMR ID '99999' not found."
}
This error occurs when provider_id or assigned_to_id doesn’t exist in the providers table. Sync providers using GET /v1/providers.

​
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"
    }
}

​
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",
        "failure_reason": "Failed to create telephone encounter in EMR"
    }
}