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

> Queues an encounter (an episode visit with form documentation) for creation in the provider's EMR system.

An encounter is an episode visit written to the patient's chart together with its form documentation (for example a scored questionnaire such as GAD-7). Encounters are created using an asynchronous processing model, so creating one 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 encounter has been written to the EMR.

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

### How an encounter is created

Processing an encounter runs an ordered chain against the EMR:

1. **Episode** — the encounter is attached to the episode you give in `episode_id`. There is no fallback to another episode. Assign the patient to a team first, as a separate step, to open the episode.
2. **Encounter type** — the `encounter_type` is resolved against the client's live billing matrix. An encounter type that is not billable for the client fails the encounter (see [Failure](#failure)).
3. **Form documentation** — the `answers` you supply are validated against the synced form definition (`form_id`) and written on the encounter. For a scored questionnaire, per-question scores are entered and totals and risk bands are derived by the EMR.
4. **Read-back** — after signing, the encounter is re-read from the EMR to confirm it persisted before the success webhook is sent.

### Request Parameters

#### Required Fields

* **patient\_mrn** (string, required): The patient's medical record number. The patient must already be synced to Cobalt.
* **episode\_id** (string, required): The episode the encounter is created under. Use the exact id from the patient episode payload.
* **encounter\_type** (string, required): The encounter type to add, by name or numeric visit-type id (for example `"GAD-7"`). Must be billable for the client — that is, present in the client's billing matrix.
* **form\_id** (string, required): EMR form id whose answers you are providing — the `emr_form_id` of a form from [`GET /v1/forms`](/api-reference/forms/get). Required when the encounter type documents a form.
* **answers** (object, required): Form answers keyed by EMR question id (the `emrQuestionId` of each question in the form definition — see [`GET /v1/forms/{id}`](/api-reference/forms/get-by-id)). For a scored questionnaire, provide the numeric score for each scored question; totals and risk bands are derived automatically. Answers are validated against the synced form definition before the encounter is written.

#### Optional Fields

* **encounter\_date** (string, optional): Encounter date in `YYYY-MM-DD` format. Defaults to today. Cannot be in the future.
* **callback\_urls** (array of strings, optional): URLs to receive the completion webhook for this encounter, in addition to your account webhook.

### Example Request

```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/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": "1234567",
    "episode_id": "32340",
    "encounter_type": "GAD-7",
    "form_id": "392",
    "encounter_date": "2026-08-26",
    "answers": {
        "453149": "3",
        "453150": "2",
        "453156": "Very difficult"
    }
}'
```

### Example Response

```json theme={null}
{
    "success": true,
    "message": "Encounter processing. A webhook event will be sent upon completion.",
    "encounter_id": "123e4567e89b12d3a456426614174000",
    "job_id": 12345
}
```

The response includes:

* **encounter\_id**: Cobalt encounter ID (UUID without dashes). This is echoed back in the webhook payload so you can correlate the two.
* **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"
}
```

#### Answers Not An Object

```json theme={null}
{
    "success": false,
    "message": "answers must be an object keyed by EMR question id."
}
```

#### Invalid Encounter Date

```json theme={null}
{
    "success": false,
    "message": "encounter_date must be a valid date (YYYY-MM-DD)."
}
```

```json theme={null}
{
    "success": false,
    "message": "encounter_date cannot be in the future."
}
```

#### 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": "Creating encounters is not supported for [EMR Name]."
}
```

Your EMR system may not currently support encounter creation.

### Webhook Notifications

When the encounter has finished processing, we send a webhook to your registered endpoint.

#### Success

```json theme={null}
{
    "id": "<id-of-webhook-response>",
    "access_token_reference_id": "<access-token-reference-id>",
    "object": "event",
    "created": "2026-08-26T10:30:00.000Z",
    "type": "encounter.created",
    "data": {
        "encounter_id": "123e4567e89b12d3a456426614174000",
        "emr_encounter_id": "927341",
        "emr_episode_id": "88214",
        "patient_mrn": "1234567"
    }
}
```

The webhook data includes:

* **encounter\_id**: The Cobalt encounter ID you received in the response.
* **emr\_encounter\_id**: The encounter id in the EMR.
* **emr\_episode\_id**: The episode the encounter was written under.
* **patient\_mrn**: The patient's medical record number.

#### Failure

```json theme={null}
{
    "id": "<id-of-webhook-response>",
    "access_token_reference_id": "<access-token-reference-id>",
    "object": "event",
    "created": "2026-08-26T10:35:00.000Z",
    "type": "encounter.failed",
    "data": {
        "encounter_id": "123e4567e89b12d3a456426614174000",
        "emr_encounter_id": null,
        "patient_mrn": "1234567",
        "failure_reason": "Encounter type 'GAD-7' not available for client 1234567 (not in billing matrix)"
    }
}
```

Transient problems are retried automatically and do not emit a webhook until they are resolved or the attempts are exhausted. A `encounter.failed` event is sent once, when the failure is permanent. Common `failure_reason` values:

* `Encounter type '<type>' not available for client <mrn> (not in billing matrix)` — the encounter type is not billable for the client.
* `Missing required answers: <question ids>` — one or more required form questions were not answered.


## OpenAPI

````yaml POST /encounters
openapi: 3.1.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
    description: Production
security:
  - ClientCredentials: []
    ClientSecret: []
    AccessToken: []
paths:
  /encounters:
    post:
      tags:
        - Encounters
      summary: Create an encounter
      description: >-
        Queues an encounter (episode visit with form documentation) for creation
        in the connected EMR.
      operationId: createEncounter
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - patient_mrn
                - episode_id
                - encounter_type
                - form_id
                - answers
              properties:
                patient_mrn:
                  type: string
                  x-supported-emrs:
                    - Credible
                  description: Medical Record Number (Credible client id) of the patient.
                  example: '15539'
                  x-required-for-emrs:
                    - Credible
                episode_id:
                  type: string
                  x-supported-emrs:
                    - Credible
                  description: >-
                    Episode (FHIR EpisodeOfCare) the encounter is created under.
                    Pull the exact id from the patient episode payload and pass
                    it here — the encounter attaches to this episode with no
                    fallback. Assign the patient to a team first (a separate
                    step) to open the episode.
                  example: '32340'
                  x-required-for-emrs:
                    - Credible
                encounter_type:
                  type: string
                  x-supported-emrs:
                    - Credible
                  description: >-
                    Encounter type to add, by name or numeric visit-type id
                    (e.g. "GAD-7").
                  example: GAD-7
                  x-required-for-emrs:
                    - Credible
                form_id:
                  type: string
                  x-supported-emrs:
                    - Credible
                  description: >-
                    EMR form id whose answers are provided (from GET /v1/forms).
                    Required when the encounter type documents a form.
                  example: '392'
                  x-required-for-emrs:
                    - Credible
                answers:
                  type: object
                  additionalProperties: {}
                  x-supported-emrs:
                    - Credible
                  description: >-
                    Form answers keyed by EMR question id (from GET /v1/forms).
                    Value by question format: single choice (radio, push button)
                    and dropdown take the answer value or answer id; check box
                    (multi-select) takes a list of answer values or ids; text
                    box takes a string; date takes YYYY-MM-DD. An open-text
                    narrative question takes the text as a string. To add notes
                    to a choice (e.g. "Other"), send { "value": "Other",
                    "notes": "..." }. For a scored questionnaire (e.g. GAD-7)
                    provide the numeric score for each scored question; totals
                    and risk bands are derived automatically. A conditional
                    question (shown only after a trigger answer) is accepted
                    only when its trigger answer is also supplied. An answer
                    that does not match the form fails the request.
                  example:
                    '427919':
                      value: Other
                      notes: School visit
                    '427920': Narrative text for the contact.
                    '467752': '2026-09-24'
                    '467761': Therapy
                    '467762': Reason for the referral.
                    '467767':
                      - Mornings
                      - Afternoons
                  x-required-for-emrs:
                    - Credible
                encounter_date:
                  type: string
                  x-supported-emrs:
                    - Credible
                  description: >-
                    Encounter date (YYYY-MM-DD). Defaults to today. Cannot be in
                    the future.
                  example: '2026-08-26'
                callback_urls:
                  type: array
                  items:
                    type: string
                  x-supported-emrs:
                    - Credible
                  description: >-
                    URLs to receive the completion webhook for this encounter,
                    in addition to the account webhook.
      responses:
        '200':
          description: Encounter queued for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  encounter_id:
                    type: string
                  job_id:
                    type: integer
                required:
                  - success
                  - message
                  - encounter_id
                  - job_id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
              message:
                type: string
            required:
              - success
              - message
    Unauthorized:
      description: Unauthorized — missing or invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
              message:
                type: string
            required:
              - success
              - message
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
              message:
                type: string
            required:
              - success
              - message
  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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.