Create Encounter

Create an encounter

curl --request POST \
  --url https://api.usecobalt.com/v1/encounters \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "patient_mrn": "15539",
  "episode_id": "32340",
  "encounter_type": "GAD-7",
  "form_id": "392",
  "answers": {
    "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"
    ]
  },
  "encounter_date": "2026-08-26",
  "start_time": "2026-10-05T14:00:00-04:00",
  "end_time": "2026-10-05T15:00:00-04:00",
  "location": "Broadway Office",
  "callback_urls": [
    "<string>"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/encounters"

payload = {
    "patient_mrn": "15539",
    "episode_id": "32340",
    "encounter_type": "GAD-7",
    "form_id": "392",
    "answers": {
        "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"]
    },
    "encounter_date": "2026-08-26",
    "start_time": "2026-10-05T14:00:00-04:00",
    "end_time": "2026-10-05T15:00:00-04:00",
    "location": "Broadway Office",
    "callback_urls": ["<string>"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_mrn: '15539',
    episode_id: '32340',
    encounter_type: 'GAD-7',
    form_id: '392',
    answers: {
      '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']
    },
    encounter_date: '2026-08-26',
    start_time: '2026-10-05T14:00:00-04:00',
    end_time: '2026-10-05T15:00:00-04:00',
    location: 'Broadway Office',
    callback_urls: ['<string>']
  })
};

fetch('https://api.usecobalt.com/v1/encounters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/encounters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'patient_mrn' => '15539',
    'episode_id' => '32340',
    'encounter_type' => 'GAD-7',
    'form_id' => '392',
    'answers' => [
        '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'
        ]
    ],
    'encounter_date' => '2026-08-26',
    'start_time' => '2026-10-05T14:00:00-04:00',
    'end_time' => '2026-10-05T15:00:00-04:00',
    'location' => 'Broadway Office',
    'callback_urls' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/encounters"

	payload := strings.NewReader("{\n  \"patient_mrn\": \"15539\",\n  \"episode_id\": \"32340\",\n  \"encounter_type\": \"GAD-7\",\n  \"form_id\": \"392\",\n  \"answers\": {\n    \"427919\": {\n      \"value\": \"Other\",\n      \"notes\": \"School visit\"\n    },\n    \"427920\": \"Narrative text for the contact.\",\n    \"467752\": \"2026-09-24\",\n    \"467761\": \"Therapy\",\n    \"467762\": \"Reason for the referral.\",\n    \"467767\": [\n      \"Mornings\",\n      \"Afternoons\"\n    ]\n  },\n  \"encounter_date\": \"2026-08-26\",\n  \"start_time\": \"2026-10-05T14:00:00-04:00\",\n  \"end_time\": \"2026-10-05T15:00:00-04:00\",\n  \"location\": \"Broadway Office\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/encounters")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"patient_mrn\": \"15539\",\n  \"episode_id\": \"32340\",\n  \"encounter_type\": \"GAD-7\",\n  \"form_id\": \"392\",\n  \"answers\": {\n    \"427919\": {\n      \"value\": \"Other\",\n      \"notes\": \"School visit\"\n    },\n    \"427920\": \"Narrative text for the contact.\",\n    \"467752\": \"2026-09-24\",\n    \"467761\": \"Therapy\",\n    \"467762\": \"Reason for the referral.\",\n    \"467767\": [\n      \"Mornings\",\n      \"Afternoons\"\n    ]\n  },\n  \"encounter_date\": \"2026-08-26\",\n  \"start_time\": \"2026-10-05T14:00:00-04:00\",\n  \"end_time\": \"2026-10-05T15:00:00-04:00\",\n  \"location\": \"Broadway Office\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/encounters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"patient_mrn\": \"15539\",\n  \"episode_id\": \"32340\",\n  \"encounter_type\": \"GAD-7\",\n  \"form_id\": \"392\",\n  \"answers\": {\n    \"427919\": {\n      \"value\": \"Other\",\n      \"notes\": \"School visit\"\n    },\n    \"427920\": \"Narrative text for the contact.\",\n    \"467752\": \"2026-09-24\",\n    \"467761\": \"Therapy\",\n    \"467762\": \"Reason for the referral.\",\n    \"467767\": [\n      \"Mornings\",\n      \"Afternoons\"\n    ]\n  },\n  \"encounter_date\": \"2026-08-26\",\n  \"start_time\": \"2026-10-05T14:00:00-04:00\",\n  \"end_time\": \"2026-10-05T15:00:00-04:00\",\n  \"location\": \"Broadway Office\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "encounter_id": "<string>",
  "job_id": 123
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

POST

encounters

Create an encounter

curl --request POST \
  --url https://api.usecobalt.com/v1/encounters \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "patient_mrn": "15539",
  "episode_id": "32340",
  "encounter_type": "GAD-7",
  "form_id": "392",
  "answers": {
    "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"
    ]
  },
  "encounter_date": "2026-08-26",
  "start_time": "2026-10-05T14:00:00-04:00",
  "end_time": "2026-10-05T15:00:00-04:00",
  "location": "Broadway Office",
  "callback_urls": [
    "<string>"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/encounters"

payload = {
    "patient_mrn": "15539",
    "episode_id": "32340",
    "encounter_type": "GAD-7",
    "form_id": "392",
    "answers": {
        "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"]
    },
    "encounter_date": "2026-08-26",
    "start_time": "2026-10-05T14:00:00-04:00",
    "end_time": "2026-10-05T15:00:00-04:00",
    "location": "Broadway Office",
    "callback_urls": ["<string>"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_mrn: '15539',
    episode_id: '32340',
    encounter_type: 'GAD-7',
    form_id: '392',
    answers: {
      '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']
    },
    encounter_date: '2026-08-26',
    start_time: '2026-10-05T14:00:00-04:00',
    end_time: '2026-10-05T15:00:00-04:00',
    location: 'Broadway Office',
    callback_urls: ['<string>']
  })
};

fetch('https://api.usecobalt.com/v1/encounters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/encounters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'patient_mrn' => '15539',
    'episode_id' => '32340',
    'encounter_type' => 'GAD-7',
    'form_id' => '392',
    'answers' => [
        '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'
        ]
    ],
    'encounter_date' => '2026-08-26',
    'start_time' => '2026-10-05T14:00:00-04:00',
    'end_time' => '2026-10-05T15:00:00-04:00',
    'location' => 'Broadway Office',
    'callback_urls' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/encounters"

	payload := strings.NewReader("{\n  \"patient_mrn\": \"15539\",\n  \"episode_id\": \"32340\",\n  \"encounter_type\": \"GAD-7\",\n  \"form_id\": \"392\",\n  \"answers\": {\n    \"427919\": {\n      \"value\": \"Other\",\n      \"notes\": \"School visit\"\n    },\n    \"427920\": \"Narrative text for the contact.\",\n    \"467752\": \"2026-09-24\",\n    \"467761\": \"Therapy\",\n    \"467762\": \"Reason for the referral.\",\n    \"467767\": [\n      \"Mornings\",\n      \"Afternoons\"\n    ]\n  },\n  \"encounter_date\": \"2026-08-26\",\n  \"start_time\": \"2026-10-05T14:00:00-04:00\",\n  \"end_time\": \"2026-10-05T15:00:00-04:00\",\n  \"location\": \"Broadway Office\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/encounters")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"patient_mrn\": \"15539\",\n  \"episode_id\": \"32340\",\n  \"encounter_type\": \"GAD-7\",\n  \"form_id\": \"392\",\n  \"answers\": {\n    \"427919\": {\n      \"value\": \"Other\",\n      \"notes\": \"School visit\"\n    },\n    \"427920\": \"Narrative text for the contact.\",\n    \"467752\": \"2026-09-24\",\n    \"467761\": \"Therapy\",\n    \"467762\": \"Reason for the referral.\",\n    \"467767\": [\n      \"Mornings\",\n      \"Afternoons\"\n    ]\n  },\n  \"encounter_date\": \"2026-08-26\",\n  \"start_time\": \"2026-10-05T14:00:00-04:00\",\n  \"end_time\": \"2026-10-05T15:00:00-04:00\",\n  \"location\": \"Broadway Office\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/encounters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"patient_mrn\": \"15539\",\n  \"episode_id\": \"32340\",\n  \"encounter_type\": \"GAD-7\",\n  \"form_id\": \"392\",\n  \"answers\": {\n    \"427919\": {\n      \"value\": \"Other\",\n      \"notes\": \"School visit\"\n    },\n    \"427920\": \"Narrative text for the contact.\",\n    \"467752\": \"2026-09-24\",\n    \"467761\": \"Therapy\",\n    \"467762\": \"Reason for the referral.\",\n    \"467767\": [\n      \"Mornings\",\n      \"Afternoons\"\n    ]\n  },\n  \"encounter_date\": \"2026-08-26\",\n  \"start_time\": \"2026-10-05T14:00:00-04:00\",\n  \"end_time\": \"2026-10-05T15:00:00-04:00\",\n  \"location\": \"Broadway Office\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "encounter_id": "<string>",
  "job_id": 123
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

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:

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.
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).
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.
Sign and submit — the encounter is signed with the service date (encounter_date), start and end times, and location you supplied.
Read-back — after signing, the encounter is re-read from the EMR to confirm it persisted and to read its status and approval state 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. 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}). 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 (service) date in YYYY-MM-DD format, in the practice’s local time. Defaults to today. Cannot be in the future.
start_time (string, optional): Service start as an ISO 8601 date-time (for example "2026-10-05T14:00:00-04:00"). A value without an offset is read in the practice’s local time. Sets the service date; if you also send encounter_date, it must be the same date. Cannot be in the future. Defaults to the current time.
end_time (string, optional): Service end as an ISO 8601 date-time, on the same day as start_time and after it. Defaults to one hour after start_time. Requires start_time.
location (string, optional): Service location, by EMR location id or exact name from the Location list on the EMR’s service form (for example "Broadway Office"). Defaults to the EMR’s default location for the service.
callback_urls (array of strings, optional): URLs to receive the completion webhook for this encounter, in addition to your account webhook.

Example Request

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",
    "start_time": "2026-08-26T14:00:00-04:00",
    "end_time": "2026-08-26T15:00:00-04:00",
    "location": "Broadway Office",
    "answers": {
        "453149": "3",
        "453150": "2",
        "453156": "Very difficult"
    }
}'

Example Response

{
    "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

{
    "success": false,
    "message": "Missing required field: patient_mrn"
}

Answers Not An Object

{
    "success": false,
    "message": "answers must be an object keyed by EMR question id."
}

Invalid Encounter Date

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

{
    "success": false,
    "message": "encounter_date cannot be in the future."
}

Invalid Service Times

{
    "success": false,
    "message": "end_time must be after start_time."
}

Other messages: start_time must be an ISO 8601 date-time (e.g. 2026-10-05T14:00:00-04:00). (and the same for end_time), end_time requires start_time., end_time must be on the same day as start_time., encounter_date must match the date of start_time (<date>)., and start_time cannot be in the future.

User Not Found

{
    "success": false,
    "message": "User not found."
}

This indicates an issue with your access token.

Unsupported EMR

{
    "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

{
    "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",
        "emr_status": "COMPLETED",
        "approved": false,
        "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.
emr_status: The encounter status in the EMR after signing (for example COMPLETED). null if the status could not be read.
approved: Whether the EMR approved the encounter on signing. Some EMR configurations approve an encounter automatically and others leave it unapproved; false means it still needs approval: approve it with PATCH /v1/encounters/{id}. null if the approval state could not be read.
patient_mrn: The patient’s medical record number.

Failure

{
    "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.
Location '<location>' is not in the service Location list for client <mrn>. — the location does not match a location id or name in the EMR’s service Location list.

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Body

application/json

patient_mrn

string

required

Medical Record Number (Credible client id) of the patient.

Example:

"15539"

episode_id

string

required

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"

encounter_type

string

required

Encounter type to add, by name or numeric visit-type id (e.g. "GAD-7").

Example:

"GAD-7"

form_id

string

required

EMR form id whose answers are provided (from GET /v1/forms). Required when the encounter type documents a form.

Example:

"392"

answers

object

required

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.

Show child attributes

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

encounter_date

string

Encounter (service) date (YYYY-MM-DD), in the practice's local time. Defaults to today. Cannot be in the future.

Example:

"2026-08-26"

start_time

string<date-time>

Service start as an ISO 8601 date-time (e.g. "2026-10-05T14:00:00-04:00"). A value without an offset is read in the practice's local time. Sets the service date; when encounter_date is also given it must be the same date. Defaults to the current time.

Example:

"2026-10-05T14:00:00-04:00"

end_time

string<date-time>

Service end as an ISO 8601 date-time, on the same day as start_time and after it. Defaults to one hour after start_time. Requires start_time.

Example:

"2026-10-05T15:00:00-04:00"

location

string

Service location, by EMR location id or exact name, from the Location list on the EMR's service form (e.g. "Broadway Office"). Defaults to the EMR's default location for the service. An unknown location fails the request.

Example:

"Broadway Office"

callback_urls

string[]

URLs to receive the completion webhook for this encounter, in addition to the account webhook.

Response

Encounter queued for processing

success

boolean

required

message

string

required

encounter_id

string

required

job_id

integer

required

​How an encounter is created

​Request Parameters

​Required Fields

​Optional Fields

​Example Request

​Example Response

​Error Responses

​Missing Required Field

​Answers Not An Object

​Invalid Encounter Date

​Invalid Service Times

​User Not Found

​Unsupported EMR

​Webhook Notifications

​Success

​Failure

Authorizations

Body

Response

How an encounter is created

Request Parameters

Required Fields

Optional Fields

Example Request

Example Response

Error Responses

Missing Required Field

Answers Not An Object

Invalid Encounter Date

Invalid Service Times

User Not Found

Unsupported EMR

Webhook Notifications

Success

Failure