Create Session

Create session

curl --request POST \
  --url https://app.hipp.health/api/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "technicianId": "usr_tech123",
  "date": "2026-01-05",
  "startTime": "09:00",
  "endTime": "10:00",
  "timezone": "America/New_York",
  "locationId": "loc_1a2b3c",
  "clientId": "usr_client789",
  "clinicianId": "usr_clin456",
  "providerLocationId": "loc_9x8y7z",
  "services": "svc_1a2b3c",
  "nonBillableCodeId": "nbc_1a2b3c",
  "isTelehealth": false,
  "isSupervision": false,
  "isClientPresent": true,
  "title": "<string>",
  "status": "CONFIRMED"
}
'

import requests

url = "https://app.hipp.health/api/v1/sessions"

payload = {
    "technicianId": "usr_tech123",
    "date": "2026-01-05",
    "startTime": "09:00",
    "endTime": "10:00",
    "timezone": "America/New_York",
    "locationId": "loc_1a2b3c",
    "clientId": "usr_client789",
    "clinicianId": "usr_clin456",
    "providerLocationId": "loc_9x8y7z",
    "services": "svc_1a2b3c",
    "nonBillableCodeId": "nbc_1a2b3c",
    "isTelehealth": False,
    "isSupervision": False,
    "isClientPresent": True,
    "title": "<string>",
    "status": "CONFIRMED"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    technicianId: 'usr_tech123',
    date: '2026-01-05',
    startTime: '09:00',
    endTime: '10:00',
    timezone: 'America/New_York',
    locationId: 'loc_1a2b3c',
    clientId: 'usr_client789',
    clinicianId: 'usr_clin456',
    providerLocationId: 'loc_9x8y7z',
    services: 'svc_1a2b3c',
    nonBillableCodeId: 'nbc_1a2b3c',
    isTelehealth: false,
    isSupervision: false,
    isClientPresent: true,
    title: '<string>',
    status: 'CONFIRMED'
  })
};

fetch('https://app.hipp.health/api/v1/sessions', 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://app.hipp.health/api/v1/sessions",
  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([
    'technicianId' => 'usr_tech123',
    'date' => '2026-01-05',
    'startTime' => '09:00',
    'endTime' => '10:00',
    'timezone' => 'America/New_York',
    'locationId' => 'loc_1a2b3c',
    'clientId' => 'usr_client789',
    'clinicianId' => 'usr_clin456',
    'providerLocationId' => 'loc_9x8y7z',
    'services' => 'svc_1a2b3c',
    'nonBillableCodeId' => 'nbc_1a2b3c',
    'isTelehealth' => false,
    'isSupervision' => false,
    'isClientPresent' => true,
    'title' => '<string>',
    'status' => 'CONFIRMED'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://app.hipp.health/api/v1/sessions"

	payload := strings.NewReader("{\n  \"technicianId\": \"usr_tech123\",\n  \"date\": \"2026-01-05\",\n  \"startTime\": \"09:00\",\n  \"endTime\": \"10:00\",\n  \"timezone\": \"America/New_York\",\n  \"locationId\": \"loc_1a2b3c\",\n  \"clientId\": \"usr_client789\",\n  \"clinicianId\": \"usr_clin456\",\n  \"providerLocationId\": \"loc_9x8y7z\",\n  \"services\": \"svc_1a2b3c\",\n  \"nonBillableCodeId\": \"nbc_1a2b3c\",\n  \"isTelehealth\": false,\n  \"isSupervision\": false,\n  \"isClientPresent\": true,\n  \"title\": \"<string>\",\n  \"status\": \"CONFIRMED\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://app.hipp.health/api/v1/sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"technicianId\": \"usr_tech123\",\n  \"date\": \"2026-01-05\",\n  \"startTime\": \"09:00\",\n  \"endTime\": \"10:00\",\n  \"timezone\": \"America/New_York\",\n  \"locationId\": \"loc_1a2b3c\",\n  \"clientId\": \"usr_client789\",\n  \"clinicianId\": \"usr_clin456\",\n  \"providerLocationId\": \"loc_9x8y7z\",\n  \"services\": \"svc_1a2b3c\",\n  \"nonBillableCodeId\": \"nbc_1a2b3c\",\n  \"isTelehealth\": false,\n  \"isSupervision\": false,\n  \"isClientPresent\": true,\n  \"title\": \"<string>\",\n  \"status\": \"CONFIRMED\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.hipp.health/api/v1/sessions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"technicianId\": \"usr_tech123\",\n  \"date\": \"2026-01-05\",\n  \"startTime\": \"09:00\",\n  \"endTime\": \"10:00\",\n  \"timezone\": \"America/New_York\",\n  \"locationId\": \"loc_1a2b3c\",\n  \"clientId\": \"usr_client789\",\n  \"clinicianId\": \"usr_clin456\",\n  \"providerLocationId\": \"loc_9x8y7z\",\n  \"services\": \"svc_1a2b3c\",\n  \"nonBillableCodeId\": \"nbc_1a2b3c\",\n  \"isTelehealth\": false,\n  \"isSupervision\": false,\n  \"isClientPresent\": true,\n  \"title\": \"<string>\",\n  \"status\": \"CONFIRMED\"\n}"

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

{
  "publicId": "apt_1a2b3c4d5e",
  "title": "John Doe — Adaptive behavior treatment",
  "status": "CONFIRMED",
  "startTime": "2026-01-05T14:00:00.000Z",
  "endTime": "2026-01-05T15:00:00.000Z",
  "isSupervision": false,
  "isClientPresent": true,
  "placeOfService": "TELEHEALTH_PROVIDED_ELSEWHERE",
  "locationId": "loc_1a2b3c",
  "technicianId": "usr_tech123",
  "clientId": "usr_client789",
  "isBillable": true,
  "isTelehealth": false,
  "clinicianId": "usr_clin456",
  "providerLocationId": "loc_9f8e7d",
  "services": "svc_1a2b3c"
}

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": [
        "email"
      ]
    }
  ]
}

{
  "error": "API key required",
  "statusCode": 401
}

{
  "error": "Access denied",
  "statusCode": 403
}

{
  "error": "Method not allowed",
  "statusCode": 405
}

{
  "error": "An unexpected error occurred",
  "statusCode": 500
}

POST

sessions

Create session

curl --request POST \
  --url https://app.hipp.health/api/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "technicianId": "usr_tech123",
  "date": "2026-01-05",
  "startTime": "09:00",
  "endTime": "10:00",
  "timezone": "America/New_York",
  "locationId": "loc_1a2b3c",
  "clientId": "usr_client789",
  "clinicianId": "usr_clin456",
  "providerLocationId": "loc_9x8y7z",
  "services": "svc_1a2b3c",
  "nonBillableCodeId": "nbc_1a2b3c",
  "isTelehealth": false,
  "isSupervision": false,
  "isClientPresent": true,
  "title": "<string>",
  "status": "CONFIRMED"
}
'

import requests

url = "https://app.hipp.health/api/v1/sessions"

payload = {
    "technicianId": "usr_tech123",
    "date": "2026-01-05",
    "startTime": "09:00",
    "endTime": "10:00",
    "timezone": "America/New_York",
    "locationId": "loc_1a2b3c",
    "clientId": "usr_client789",
    "clinicianId": "usr_clin456",
    "providerLocationId": "loc_9x8y7z",
    "services": "svc_1a2b3c",
    "nonBillableCodeId": "nbc_1a2b3c",
    "isTelehealth": False,
    "isSupervision": False,
    "isClientPresent": True,
    "title": "<string>",
    "status": "CONFIRMED"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    technicianId: 'usr_tech123',
    date: '2026-01-05',
    startTime: '09:00',
    endTime: '10:00',
    timezone: 'America/New_York',
    locationId: 'loc_1a2b3c',
    clientId: 'usr_client789',
    clinicianId: 'usr_clin456',
    providerLocationId: 'loc_9x8y7z',
    services: 'svc_1a2b3c',
    nonBillableCodeId: 'nbc_1a2b3c',
    isTelehealth: false,
    isSupervision: false,
    isClientPresent: true,
    title: '<string>',
    status: 'CONFIRMED'
  })
};

fetch('https://app.hipp.health/api/v1/sessions', 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://app.hipp.health/api/v1/sessions",
  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([
    'technicianId' => 'usr_tech123',
    'date' => '2026-01-05',
    'startTime' => '09:00',
    'endTime' => '10:00',
    'timezone' => 'America/New_York',
    'locationId' => 'loc_1a2b3c',
    'clientId' => 'usr_client789',
    'clinicianId' => 'usr_clin456',
    'providerLocationId' => 'loc_9x8y7z',
    'services' => 'svc_1a2b3c',
    'nonBillableCodeId' => 'nbc_1a2b3c',
    'isTelehealth' => false,
    'isSupervision' => false,
    'isClientPresent' => true,
    'title' => '<string>',
    'status' => 'CONFIRMED'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://app.hipp.health/api/v1/sessions"

	payload := strings.NewReader("{\n  \"technicianId\": \"usr_tech123\",\n  \"date\": \"2026-01-05\",\n  \"startTime\": \"09:00\",\n  \"endTime\": \"10:00\",\n  \"timezone\": \"America/New_York\",\n  \"locationId\": \"loc_1a2b3c\",\n  \"clientId\": \"usr_client789\",\n  \"clinicianId\": \"usr_clin456\",\n  \"providerLocationId\": \"loc_9x8y7z\",\n  \"services\": \"svc_1a2b3c\",\n  \"nonBillableCodeId\": \"nbc_1a2b3c\",\n  \"isTelehealth\": false,\n  \"isSupervision\": false,\n  \"isClientPresent\": true,\n  \"title\": \"<string>\",\n  \"status\": \"CONFIRMED\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://app.hipp.health/api/v1/sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"technicianId\": \"usr_tech123\",\n  \"date\": \"2026-01-05\",\n  \"startTime\": \"09:00\",\n  \"endTime\": \"10:00\",\n  \"timezone\": \"America/New_York\",\n  \"locationId\": \"loc_1a2b3c\",\n  \"clientId\": \"usr_client789\",\n  \"clinicianId\": \"usr_clin456\",\n  \"providerLocationId\": \"loc_9x8y7z\",\n  \"services\": \"svc_1a2b3c\",\n  \"nonBillableCodeId\": \"nbc_1a2b3c\",\n  \"isTelehealth\": false,\n  \"isSupervision\": false,\n  \"isClientPresent\": true,\n  \"title\": \"<string>\",\n  \"status\": \"CONFIRMED\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.hipp.health/api/v1/sessions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"technicianId\": \"usr_tech123\",\n  \"date\": \"2026-01-05\",\n  \"startTime\": \"09:00\",\n  \"endTime\": \"10:00\",\n  \"timezone\": \"America/New_York\",\n  \"locationId\": \"loc_1a2b3c\",\n  \"clientId\": \"usr_client789\",\n  \"clinicianId\": \"usr_clin456\",\n  \"providerLocationId\": \"loc_9x8y7z\",\n  \"services\": \"svc_1a2b3c\",\n  \"nonBillableCodeId\": \"nbc_1a2b3c\",\n  \"isTelehealth\": false,\n  \"isSupervision\": false,\n  \"isClientPresent\": true,\n  \"title\": \"<string>\",\n  \"status\": \"CONFIRMED\"\n}"

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

{
  "publicId": "apt_1a2b3c4d5e",
  "title": "John Doe — Adaptive behavior treatment",
  "status": "CONFIRMED",
  "startTime": "2026-01-05T14:00:00.000Z",
  "endTime": "2026-01-05T15:00:00.000Z",
  "isSupervision": false,
  "isClientPresent": true,
  "placeOfService": "TELEHEALTH_PROVIDED_ELSEWHERE",
  "locationId": "loc_1a2b3c",
  "technicianId": "usr_tech123",
  "clientId": "usr_client789",
  "isBillable": true,
  "isTelehealth": false,
  "clinicianId": "usr_clin456",
  "providerLocationId": "loc_9f8e7d",
  "services": "svc_1a2b3c"
}

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": [
        "email"
      ]
    }
  ]
}

{
  "error": "API key required",
  "statusCode": 401
}

{
  "error": "Access denied",
  "statusCode": 403
}

{
  "error": "Method not allowed",
  "statusCode": 405
}

{
  "error": "An unexpected error occurred",
  "statusCode": 500
}

Create a single (non-recurring) session (appointment) in the organization that owns the API key. All referenced entities (staff, client, clinician, location, provider location, non-billable code, service lines) must belong to that organization.

Headers

Authorization: Bearer <your-api-key>
Content-Type: application/json

Billable vs non-billable

A session is either billable or non-billable — exactly one, never both and never neither:

Billable: provide services (a single service line public id). clientId and clinicianId are required.
Non-billable: provide nonBillableCodeId instead. When isSupervision is true, clinicianId is required; for a standard (non-supervision) non-billable session clinicianId must not be provided.

Time fields

date, startTime, endTime and timezone are combined server-side into UTC instants:

date — YYYY-MM-DD. Must be a real calendar date; invalid days such as 2026-02-30 are rejected rather than shifted.
startTime / endTime — HH:mm or HH:mm:ss
timezone — IANA zone (for example America/New_York)

endTime must be after startTime, and the total duration must not exceed 8 hours (compared at second precision).

Field Requirements

Field	Required	Notes
`technicianId`	Always	Must be a staff member (technician, clinician, clinical admin or clinical superadmin). A technician can only be assigned to technician-only service lines.
`date`, `startTime`, `endTime`, `timezone`	Always	Combined into UTC instants.
`locationId`	Always	Session location.
`placeOfService`	Always	Must be allowed by the service line on the session.
`services`	Billable only	Single service line public id. Mutually exclusive with `nonBillableCodeId`.
`nonBillableCodeId`	Non-billable only	Mutually exclusive with `services`.
`clientId`	Billable	Must reference a patient.
`clinicianId`	Billable, or non-billable supervision	Must reference a clinician or clinical admin. Rejected on standard (non-supervision) non-billable sessions.
`providerLocationId`	Telehealth	Required when `isTelehealth` is `true`.
`isTelehealth`	Optional	Billable only. Defaults to `false`.
`isSupervision`	Optional	Defaults to `false`.
`isClientPresent`	Optional	Defaults to `true`.
`title`	Optional	Custom title.
`status`	Optional	Scheduling status of the new session. Defaults to `CONFIRMED`. See Session status.

Session status

status sets the scheduling status the session is created with.

Allowed values: CONFIRMED, UNCONFIRMED, DECLINED, PATIENT_NO_SHOW, REQUESTED_TO_CANCEL.
Omit it and the session is created CONFIRMED, so a session booked through the API behaves like one booked in the app. To create a session that still needs confirming, send "status": "UNCONFIRMED" explicitly.
Values are matched exactly (uppercase). Any other value returns a 400.

The created session response includes its current status.

Success Response (201)

The response shape depends on isBillable. A billable session exposes isTelehealth, clinicianId, providerLocationId and services (and never nonBillableCode):

{
  "publicId": "apt_1a2b3c4d5e",
  "title": "John Doe — Adaptive behavior treatment",
  "status": "CONFIRMED",
  "startTime": "2026-01-05T14:00:00.000Z",
  "endTime": "2026-01-05T15:00:00.000Z",
  "isSupervision": false,
  "isClientPresent": true,
  "placeOfService": "HOME",
  "locationId": "loc_1a2b3c",
  "technicianId": "usr_tech123",
  "clientId": "usr_client789",
  "isBillable": true,
  "isTelehealth": false,
  "clinicianId": "usr_clin456",
  "providerLocationId": "loc_9f8e7d",
  "services": "svc_1a2b3c"
}

A non-billable session exposes nonBillableCode instead (and omits isTelehealth, clinicianId and services):

{
  "publicId": "apt_9z8y7x",
  "title": "Travel",
  "status": "CONFIRMED",
  "startTime": "2026-01-05T12:00:00.000Z",
  "endTime": "2026-01-05T12:30:00.000Z",
  "isSupervision": false,
  "isClientPresent": false,
  "placeOfService": "OTHER",
  "locationId": "loc_1a2b3c",
  "technicianId": "usr_tech123",
  "clientId": null,
  "isBillable": false,
  "nonBillableCode": "nbc_1a2b3c"
}

Known limitation. A non-billable supervision session does store the clinicianId you send, but the non-billable response shape omits clinicianId entirely — so reading the session back shows no clinician even though one is set. This is a defect, not intended behaviour; do not rely on the absence of clinicianId to mean a session has no clinician.

Error Responses

400 - Bad Request

Returned for validation failures (missing required fields for the chosen mode, endTime not after startTime, total duration over 8 hours, an invalid calendar date, place of service not allowed by a service line, a technicianId whose role cannot deliver a session, a clientId that is not a patient, a clinicianId that is not a clinical role, or a technician assigned to a non-technician service line) and for references to entities that do not exist in the organization. Business-rule failures (the billable/non-billable, telehealth, time, place-of-service, staff-role and referenced-entity rules above) are returned as a plain error:

{
  "error": "clientId is required for billable sessions (with services).",
  "statusCode": 400
}

Malformed field input caught before the business rules (bad enum, empty string, wrong type, invalid date pattern) is returned as a validation list, where each path is an array of segments:

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_enum_value",
      "path": ["placeOfService"],
      "message": "Invalid enum value."
    }
  ]
}

401 - Unauthorized

{
  "error": "API key required",
  "statusCode": 401
}

403 - Forbidden

{
  "error": "Access denied",
  "statusCode": 403
}

Examples

Billable session (cURL)

curl -X POST "https://app.hipp.health/api/v1/sessions" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "technicianId": "usr_tech123",
    "clientId": "usr_client789",
    "clinicianId": "usr_clin456",
    "date": "2026-01-05",
    "startTime": "09:00",
    "endTime": "10:00",
    "timezone": "America/New_York",
    "locationId": "loc_1a2b3c",
    "services": "svc_1a2b3c",
    "placeOfService": "HOME"
  }'

Non-billable session (cURL)

curl -X POST "https://app.hipp.health/api/v1/sessions" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "technicianId": "usr_tech123",
    "date": "2026-01-05",
    "startTime": "12:00",
    "endTime": "12:30",
    "timezone": "America/New_York",
    "locationId": "loc_1a2b3c",
    "nonBillableCodeId": "nbc_1a2b3c",
    "placeOfService": "OTHER"
  }'

JavaScript Example

const createSession = async (payload) => {
  const response = await fetch("https://app.hipp.health/api/v1/sessions", {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || error.message || "Failed to create session");
  }

  return response.json();
};

// Usage
try {
  const session = await createSession({
    technicianId: "usr_tech123",
    clientId: "usr_client789",
    clinicianId: "usr_clin456",
    date: "2026-01-05",
    startTime: "09:00",
    endTime: "10:00",
    timezone: "America/New_York",
    locationId: "loc_1a2b3c",
    services: "svc_1a2b3c",
    placeOfService: "HOME",
  });
  console.log("Created session:", session);
} catch (error) {
  console.error("Error creating session:", error.message);
}

Authorizations

Authorization

string

header

required

API key authentication. Include your API key in the Authorization header as 'Bearer '

Body

application/json

Payload for creating a single (non-recurring) session. A session is either billable (provide services) or non-billable (provide nonBillableCodeId) — exactly one, never both.

technicianId

string

required

Public id of the staff member delivering the session. Must be a staff role (TECHNICIAN, CLINICIAN, CLINICAL_ADMIN or CLINICAL_SUPERADMIN); clients and other roles are rejected. A TECHNICIAN can only be assigned to technician-only service lines.

Minimum string length: 1

Example:

"usr_tech123"

date

string

required

Calendar date of the session (YYYY-MM-DD). Must be a real calendar date (e.g. 2026-02-30 is rejected). Combined with startTime/endTime in the given timezone to derive UTC instants.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-01-05"

startTime

string

required

Wall-clock start time (HH:mm or HH:mm:ss) in the given timezone.

Pattern: ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$

Example:

"09:00"

endTime

string

required

Wall-clock end time (HH:mm or HH:mm:ss) in the given timezone. Must be after startTime, and the total duration (compared at second precision) must not exceed 8 hours.

Pattern: ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$

Example:

"10:00"

timezone

string

required

IANA timezone used to interpret date/startTime/endTime.

Minimum string length: 1

Example:

"America/New_York"

locationId

string

required

Public id of the session location.

Minimum string length: 1

Example:

"loc_1a2b3c"

placeOfService

enum<string>

required

CMS place-of-service classification for the session

Available options:

TELEHEALTH_PROVIDED_ELSEWHERE,

TELEHEALTH_PROVIDED_IN_PATIENT_HOME,

OFFICE,

HOME,

SCHOOL,

OTHER,

TEMPORARY_LODGING,

PLACE_OF_EMPLOYMENT,

COMMUNITY_MENTAL_HEALTH_CENTER

clientId

string

Public id of the client. Must reference a patient. Required for billable sessions.

Minimum string length: 1

Example:

"usr_client789"

clinicianId

string

Public id of the clinician. Must reference a clinician or clinical admin. Required for billable sessions and for non-billable supervision sessions. Must NOT be provided for standard (non-supervision) non-billable sessions.

Minimum string length: 1

Example:

"usr_clin456"

providerLocationId

string

Public id of the location the provider delivers from. Required when isTelehealth is true.

Minimum string length: 1

Example:

"loc_9x8y7z"

services

string

Public id of the billable service line. Provide for billable sessions; omit for non-billable sessions. The session location's place of service must be allowed by the service line.

Minimum string length: 1

Example:

"svc_1a2b3c"

nonBillableCodeId

string

Public id of the non-billable code. Provide for non-billable sessions instead of services.

Minimum string length: 1

Example:

"nbc_1a2b3c"

isTelehealth

boolean

default:false

Whether the session is delivered via telehealth. Only allowed on billable sessions and requires providerLocationId.

isSupervision

boolean

default:false

Whether the session is a supervision session. For non-billable supervision, clinicianId is required.

isClientPresent

boolean

default:true

Whether the client is present for the session.

title

string

Optional custom title. Defaults to the client name, the non-billable code name, or a placeholder.

Minimum string length: 1

status

enum<string>

default:CONFIRMED

Scheduling status the session is created with. Defaults to CONFIRMED, so a session booked through the API behaves like one booked in the app. Matched exactly (uppercase); any other value returns a 400.

Available options:

CONFIRMED,

UNCONFIRMED,

DECLINED,

PATIENT_NO_SHOW,

REQUESTED_TO_CANCEL

Response

Session created

Option 1
Option 2

A scheduled session (appointment). The shape depends on isBillable: billable sessions expose isTelehealth, clinicianId and services; non-billable sessions expose nonBillableCode instead.

publicId

string

required

Example:

"apt_1a2b3c4d5e"

title

string

required

Example:

"John Doe — Adaptive behavior treatment"

status

enum<string>

required

Scheduling status of the session. Matched exactly (uppercase); any other value returns a 400.

Available options:

CONFIRMED,

UNCONFIRMED,

DECLINED,

PATIENT_NO_SHOW,

REQUESTED_TO_CANCEL

startTime

string<date-time>

required

Session start instant in UTC (ISO-8601).

Example:

"2026-01-05T14:00:00.000Z"

endTime

string<date-time>

required

Session end instant in UTC (ISO-8601).

Example:

"2026-01-05T15:00:00.000Z"

isSupervision

boolean

required

Example:

false

isClientPresent

boolean

required

Example:

true

placeOfService

enum<string>

required

CMS place-of-service classification for the session

Available options:

TELEHEALTH_PROVIDED_ELSEWHERE,

TELEHEALTH_PROVIDED_IN_PATIENT_HOME,

OFFICE,

HOME,

SCHOOL,

OTHER,

TEMPORARY_LODGING,

PLACE_OF_EMPLOYMENT,

COMMUNITY_MENTAL_HEALTH_CENTER

locationId

string

required

Public id of the session location.

Example:

"loc_1a2b3c"

technicianId

string | null

required

Public id of the assigned technician, if any.

Example:

"usr_tech123"

clientId

string | null

required

Public id of the client, if any.

Example:

"usr_client789"

isBillable

enum<boolean>

required

Always true for billable sessions.

Available options:

true

isTelehealth

boolean

required

Example:

false

clinicianId

string | null

required

Public id of the assigned clinician, if any.

Example:

"usr_clin456"

providerLocationId

string | null

required

Public id of the provider location the care was delivered from, if any.

Example:

"loc_9f8e7d"

services

string

required

Public id of the billable service line rendered. A session bills exactly one service line.

Example:

"svc_1a2b3c"

API Documentation

Endpoints

Create Session

Create Session

Headers

Billable vs non-billable

Time fields

Field Requirements

Session status

Success Response (201)

Error Responses

400 - Bad Request

401 - Unauthorized

403 - Forbidden

Examples

Billable session (cURL)

Non-billable session (cURL)

JavaScript Example

Authorizations

Body

Response

​Create Session

​Headers

​Billable vs non-billable

​Time fields

​Field Requirements

​Session status

​Success Response (201)

​Error Responses

​400 - Bad Request

​401 - Unauthorized

​403 - Forbidden

​Examples

​Billable session (cURL)

​Non-billable session (cURL)

​JavaScript Example

Authorizations

Body

Response

Create Session

Headers

Billable vs non-billable

Time fields

Field Requirements

Session status

Success Response (201)

Error Responses

400 - Bad Request

401 - Unauthorized

403 - Forbidden

Examples

Billable session (cURL)

Non-billable session (cURL)

JavaScript Example