> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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): EMR user ID of the staff member the encounter is assigned to. This can be any staff member in your organization (provider, nurse, front desk), not just providers. Valid IDs are the `ehr_id` values in the `staff_list` field returned by `GET /v1/settings`.

#### 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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
    "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

```json theme={null}
{
    "success": false,
    "message": "Missing required field: patient_mrn"
}
```

Possible missing fields: `patient_mrn`, `provider_id`, `location_id`, `assigned_to_id`

#### Reason Too Long

```json theme={null}
{
    "success": false,
    "message": "Reason exceeds maximum length of 50 characters"
}
```

#### Medication Name Invalid Length

```json theme={null}
{
    "success": false,
    "message": "refill_medication_name must be at least 2 characters"
}
```

```json theme={null}
{
    "success": false,
    "message": "refill_medication_name exceeds maximum length of 50 characters"
}
```

#### Provider Not Found

```json theme={null}
{
    "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

```json theme={null}
{
    "success": false,
    "message": "Staff member with ID '99999' not found."
}
```

This error occurs when `assigned_to_id` doesn't exist in the staff list. Valid staff IDs are the `ehr_id` values in the `staff_list` field returned by `GET /v1/settings`.

#### Location Not Found

```json theme={null}
{
    "success": false,
    "message": "Location with EMR ID '99999' not found."
}
```

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

#### Pharmacy Not Found

```json theme={null}
{
    "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

```json theme={null}
{
    "success": false,
    "message": "User not found."
}
```

This indicates an issue with your access token.

#### Unsupported EMR

```json theme={null}
{
    "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

```json theme={null}
{
    "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:

```json theme={null}
{
    "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

```json theme={null}
{
    "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:

```json theme={null}
{
    "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\"]"
    }
}
```


## OpenAPI

````yaml POST /telephone-encounters
openapi: 3.0.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
security:
  - ClientCredentials: []
    ClientSecret: []
    AccessToken: []
paths:
  /telephone-encounters:
    post:
      summary: Create Telephone Encounter
      description: >-
        Creates a telephone encounter record in the provider's EMR system. This
        is an asynchronous operation that returns immediately with a job_id, and
        sends webhook notification upon completion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - patient_mrn
                - provider_id
                - location_id
                - assigned_to_id
              properties:
                patient_mrn:
                  type: string
                  description: Patient's Medical Record Number
                provider_id:
                  type: string
                  description: Provider's EMR ID
                location_id:
                  type: string
                  description: Location's EMR ID
                assigned_to_id:
                  type: string
                  description: Staff member's EMR ID to assign the encounter to
                reason:
                  type: string
                  maxLength: 50
                  description: Reason for telephone encounter (optional, max 50 characters)
                refill_medication_name:
                  type: string
                  minLength: 2
                  maxLength: 50
                  description: >-
                    Medication name for refill request (optional, 2-50
                    characters)
                pharmacy_ehr_id:
                  type: string
                  description: Pharmacy's EMR ID (optional)
                caller:
                  type: string
                  maxLength: 100
                  description: Name of the person who called (optional, max 100 characters)
                message:
                  type: string
                  description: Message content from the caller (optional)
                is_high_priority:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
                  description: >-
                    Whether this encounter should be marked as high priority
                    (optional). Must be "true" or "false"
      responses:
        '200':
          description: Telephone encounter queued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: >-
                      Telephone encounter processing. A webhook event will be
                      sent upon completion.
                  telephone_encounter_id:
                    type: string
                    description: >-
                      Unique identifier for the created telephone encounter
                      record
                  job_id:
                    type: integer
                    description: Job execution identifier for tracking the async operation
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Provider with EMR ID '99999' not found.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Internal server error
components:
  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

````