Twyll by SpectrumAi
API docs by Redocly

Twyll API (1.0.2)

Download OpenAPI specification:

E-mail: support@spectrumai.com URL: https://www.spectrumai.com/

Authentication

Authentication endpoints

Authenticate

Retrieve login credentials.

Request Body schema: application/json
required
username
required
string <email>
password
required
string

Responses

Request samples

Content type
application/json
{
  • "username": "user@example.com",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "token_type": "Bearer",
  • "expires_in": "3600"
}

Clients

Client endpoints

List Clients

Retrieve a list of clients in Twyll.

You can filter the list of clients by providing query parameters:

  • external_id_type and external_id: Filter clients by a specific external ID type and ID
  • mrn: Filter clients by Medical Record Number (MRN)
Authorizations:
bearerAuth
query Parameters
external_id_type
string
Example: external_id_type=CRID

Filter clients by external ID type

external_id
string
Example: external_id=APN83095

Filter clients by external ID

mrn
integer
Example: mrn=10000

Filter clients by MRN

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Client

Create a new client in Twyll.

Authorizations:
bearerAuth
Request Body schema: application/json
required
clinic
required
string <uuid>

The UUID of the site (clinic) in which a client is associated with. Ask your SpectrumAi representative for a list of valid UUIDs.

required
object (ClientName)

The client's name.

gender
required
string (GenderEnum)
Enum: "m" "fe" "nb"
  • m - Male
  • fe - Female
  • nb - Non-Binary
dob
required
string <date>

The client's birthday.

race
Array of strings (RaceEnum)
Default: "unknown"
Items Enum: "native" "asian" "black" "hawaiian" "white" "other" "asked" "unknown"
ethnicity
string (EthnicityEnum)
Default: "unknown"
Enum: "hispanic" "not_hispanic" "unknown"
  • hispanic - Hispanic or Latino
  • not_hispanic - Not Hispanic or Latino
  • unknown - Unknown
required
Array of objects (ClientAddress)

Addresses and associated places of service for a client.

comorbidities
Array of strings (ComorbiditiesEnum)
Items Enum: "adhd" "anxiety" "depressive" "epilepsy" "gi" "hearing" "id" "sleep" "sight"

Comorbidities associated with the client.

required
Array of objects (ClientLanguages)
block_video_capture
required
boolean

A flag indicating whether the client has consented to video recording during a session.

required
Array of objects (ClientInsurance)
Array of objects (ClientExternalIds)

External identifiers used by third party systems (i.e. a practice management system) used to identify a client.

is_active
boolean

A flag indicating whether the client is active in the system. Note that this flag is not used to determine whether a client is billable for invoicing.

date_of_referral
string or null <date>

The date in which a client was first referred to the practice.

Responses

Request samples

Content type
application/json
{
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "name": {
    },
  • "gender": "m",
  • "dob": "2019-08-24",
  • "race": "unknown",
  • "ethnicity": "hispanic",
  • "addresses": [
    ],
  • "comorbidities": [
    ],
  • "languages": [
    ],
  • "block_video_capture": false,
  • "insurance_cards": [
    ],
  • "external_mrns": [
    ],
  • "is_active": true,
  • "date_of_referral": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "mrn": 10000,
  • "name": {
    },
  • "gender": "m",
  • "dob": "2019-08-24",
  • "race": [
    ],
  • "ethnicity": "hispanic",
  • "addresses": [
    ],
  • "comorbidities": [
    ],
  • "languages": [
    ],
  • "block_video_capture": false,
  • "insurance_cards": [
    ],
  • "external_mrns": [
    ],
  • "is_active": true,
  • "date_of_referral": "2019-08-24"
}

Get Specific Client

Get information about a client in Twyll.

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "mrn": 10000,
  • "name": {
    },
  • "gender": "m",
  • "dob": "2019-08-24",
  • "race": [
    ],
  • "ethnicity": "hispanic",
  • "addresses": [
    ],
  • "comorbidities": [
    ],
  • "languages": [
    ],
  • "block_video_capture": false,
  • "insurance_cards": [
    ],
  • "external_mrns": [
    ],
  • "is_active": true,
  • "date_of_referral": "2019-08-24"
}

Overwrite Client Record

Overwrite Client's information and related records with provided info.

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>
Request Body schema: application/json
required
clinic
required
string <uuid>

The UUID of the site (clinic) in which a client is associated with. Ask your SpectrumAi representative for a list of valid UUIDs.

required
object (ClientName)

The client's name.

gender
required
string (GenderEnum)
Enum: "m" "fe" "nb"
  • m - Male
  • fe - Female
  • nb - Non-Binary
dob
required
string <date>

The client's birthday.

race
Array of strings (RaceEnum)
Default: "unknown"
Items Enum: "native" "asian" "black" "hawaiian" "white" "other" "asked" "unknown"
ethnicity
string (EthnicityEnum)
Default: "unknown"
Enum: "hispanic" "not_hispanic" "unknown"
  • hispanic - Hispanic or Latino
  • not_hispanic - Not Hispanic or Latino
  • unknown - Unknown
required
Array of objects (ClientAddress)

Addresses and associated places of service for a client.

comorbidities
Array of strings (ComorbiditiesEnum)
Items Enum: "adhd" "anxiety" "depressive" "epilepsy" "gi" "hearing" "id" "sleep" "sight"

Comorbidities associated with the client.

required
Array of objects (ClientLanguages)
block_video_capture
required
boolean

A flag indicating whether the client has consented to video recording during a session.

required
Array of objects (ClientInsurance)
Array of objects (ClientExternalIds)

External identifiers used by third party systems (i.e. a practice management system) used to identify a client.

is_active
boolean

A flag indicating whether the client is active in the system. Note that this flag is not used to determine whether a client is billable for invoicing.

date_of_referral
string or null <date>

The date in which a client was first referred to the practice.

Responses

Request samples

Content type
application/json
{
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "name": {
    },
  • "gender": "m",
  • "dob": "2019-08-24",
  • "race": "unknown",
  • "ethnicity": "hispanic",
  • "addresses": [
    ],
  • "comorbidities": [
    ],
  • "languages": [
    ],
  • "block_video_capture": false,
  • "insurance_cards": [
    ],
  • "external_mrns": [
    ],
  • "is_active": true,
  • "date_of_referral": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "mrn": 10000,
  • "name": {
    },
  • "gender": "m",
  • "dob": "2019-08-24",
  • "race": [
    ],
  • "ethnicity": "hispanic",
  • "addresses": [
    ],
  • "comorbidities": [
    ],
  • "languages": [
    ],
  • "block_video_capture": false,
  • "insurance_cards": [
    ],
  • "external_mrns": [
    ],
  • "is_active": true,
  • "date_of_referral": "2019-08-24"
}

Partially Update Client Record

PATCH Client's and related objects records

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>
Request Body schema: application/json
clinic
required
string <uuid>
mrn
integer [ -2147483648 .. 2147483647 ]
required
object (ClientName)

The client's name.

gender
required
string (GenderEnum)
Enum: "m" "fe" "nb"
  • m - Male
  • fe - Female
  • nb - Non-Binary
dob
required
string <date>

The client's date of Birth.

race
Array of strings (RaceEnum)
Default: "unknown"
Items Enum: "native" "asian" "black" "hawaiian" "white" "other" "asked" "unknown"
ethnicity
string (EthnicityEnum)
Default: "unknown"
Enum: "hispanic" "not_hispanic" "unknown"
  • hispanic - Hispanic or Latino
  • not_hispanic - Not Hispanic or Latino
  • unknown - Unknown
required
Array of objects (ClientAddress)
comorbidities
required
Array of strings (ComorbiditiesEnum)
Items Enum: "adhd" "anxiety" "depressive" "epilepsy" "gi" "hearing" "id" "sleep" "sight"
required
Array of objects (ClientLanguages)
block_video_capture
boolean
Array of objects (ClientInsurance)
Array of objects (ClientExternalIds)
is_active
boolean
date_of_referral
string or null <date>

Responses

Request samples

Content type
application/json
{
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "mrn": -2147483648,
  • "name": {
    },
  • "gender": "m",
  • "dob": "2019-08-24",
  • "race": "unknown",
  • "ethnicity": "hispanic",
  • "addresses": [
    ],
  • "comorbidities": [
    ],
  • "languages": [
    ],
  • "block_video_capture": true,
  • "insurance_cards": [
    ],
  • "external_mrns": [
    ],
  • "is_active": true,
  • "date_of_referral": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "mrn": 10000,
  • "name": {
    },
  • "gender": "m",
  • "dob": "2019-08-24",
  • "race": [
    ],
  • "ethnicity": "hispanic",
  • "addresses": [
    ],
  • "comorbidities": [
    ],
  • "languages": [
    ],
  • "block_video_capture": false,
  • "insurance_cards": [
    ],
  • "external_mrns": [
    ],
  • "is_active": true,
  • "date_of_referral": "2019-08-24"
}

Care Teams

Care Team endpoints

List Care Team

List all care team members for a given client.

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string <uuid> ^[0-9a-f-]+$

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string"
}

Create Care Team Association

Assign new Care Team members with related data for provided client

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string^[0-9a-f-]+$
Request Body schema: application/json
required
id
string <uuid>
email
required
string <email> <= 254 characters
first_name
string or null <= 255 characters
last_name
string or null <= 255 characters
phone_number
string or null <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string"
}

Get Specific Care Team Member

Retrieve the Care Team Member linked with the provided client

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string <uuid> ^[0-9a-f-]+$
uuid
required
string <uuid> ^[0-9a-f-]+$

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string"
}

Overwrite Care Team Member

Overwrite the provided client's care team member information.

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string <uuid> ^[0-9a-f-]+$
uuid
required
string <uuid> ^[0-9a-f-]+$
Request Body schema: application/json
id
string <uuid>
email
required
string <email> <= 254 characters
first_name
string or null <= 255 characters
last_name
string or null <= 255 characters
phone_number
string or null <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string"
}

Update Care Team Member

Update the provided client's care team member information.

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string <uuid> ^[0-9a-f-]+$
uuid
required
string <uuid> ^[0-9a-f-]+$
Request Body schema: application/json
id
string <uuid>
email
string <email> <= 254 characters
first_name
string or null <= 255 characters
last_name
string or null <= 255 characters
phone_number
string or null <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone_number": "string"
}

Guardians

Guardian endpoints

Get Guardians

Retrieve a list of guardians for a client.

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Agency Guardians

Retrieve a list of all guardians associated with an agency.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Guardian

Create a new guardian.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object (GuardianName)
dob
required
string <date>
email
string or null <email> <= 255 characters
phone
string or null <= 255 characters
required
object (GuardianAddress)
language
required
string
note
string or null
Array of objects (Relationship)
Default: []

Responses

Request samples

Content type
application/json
{
  • "name": {
    },
  • "dob": "2019-08-24",
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "language": "string",
  • "note": "string",
  • "clients": [ ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Guardian

Retrieve information about a specific guardian.

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": {
    },
  • "dob": "2019-08-24",
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "language": "string",
  • "note": "string",
  • "clients": [ ]
}

Update Guardian

Update a specific guardian.

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>
Request Body schema: application/json
object (GuardianName)
dob
string <date>
email
string or null <email> <= 255 characters
phone
string or null <= 255 characters
object (GuardianAddress)
language
string
note
string or null
Array of objects (Relationship)
Default: []

Responses

Request samples

Content type
application/json
{
  • "name": {
    },
  • "dob": "2019-08-24",
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "language": "string",
  • "note": "string",
  • "clients": [ ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": {
    },
  • "dob": "2019-08-24",
  • "email": "user@example.com",
  • "phone": "string",
  • "address": {
    },
  • "language": "string",
  • "note": "string",
  • "clients": [ ]
}

Staff

Staff endpoints

List Staff

Get all staff associated with an agency.

Authorizations:
bearerAuth
query Parameters
email
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Staff

Create a new user in Twyll.

Authorizations:
bearerAuth
Request Body schema: application/json
required
email
required
string <email>
status
required
string
Enum: "active" "inactive"

The user's status. This field is related to is_active and should match that field.

agency
string <uuid>

The UUID of the agency that a staff member is associated with. Ask your Twyll representative for a list of valid agency UUIDs.

clinic
required
string

The UUID of the clinic that a staff member is associated with. Ask your Twyll representative for a list of valid clinic UUIDs. Not required for Agency Admins.

required
Array of objects (UserRole)

A list of roles associated with a staff member. Agency Admin and other roles may not be combined.

required
object (UserName)
phone
required
string or null
gender
required
string (GenderEnum)
Enum: "m" "fe" "nb"
  • m - Male
  • fe - Female
  • nb - Non-Binary
required
object (StaffProfile)
required
Array of objects (StaffCredential)
required
Array of objects (StaffExternalId)
is_active
boolean

A flag indicating whether the staff member is active and should be allowed to log into Twyll.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "status": "active",
  • "agency": "146639f4-7373-4aed-9807-16621365dd97",
  • "clinic": "string",
  • "roles": [
    ],
  • "name": {
    },
  • "phone": "string",
  • "gender": "m",
  • "profile": {
    },
  • "credentials": [
    ],
  • "external_ids": [
    ],
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "user@example.com",
  • "agency": "146639f4-7373-4aed-9807-16621365dd97",
  • "clinic": "string",
  • "roles": [
    ],
  • "name": {
    },
  • "phone": "string",
  • "gender": "m",
  • "status": "active",
  • "profile": {
    },
  • "credentials": [
    ],
  • "external_ids": [
    ],
  • "is_active": true
}

Get Staff

Retrieve information about a user.

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "user@example.com",
  • "agency": "146639f4-7373-4aed-9807-16621365dd97",
  • "clinic": "string",
  • "roles": [
    ],
  • "name": {
    },
  • "phone": "string",
  • "gender": "m",
  • "status": "active",
  • "profile": {
    },
  • "credentials": [
    ],
  • "external_ids": [
    ],
  • "is_active": true
}

Staff Update

Overwrite User info and all related objects

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>
Request Body schema: application/json
required
email
required
string <email>
status
required
string
Enum: "active" "inactive"

The user's status. This field is related to is_active and should match that field.

agency
string <uuid>

The UUID of the agency that a staff member is associated with. Ask your Twyll representative for a list of valid agency UUIDs.

clinic
required
string

The UUID of the clinic that a staff member is associated with. Ask your Twyll representative for a list of valid clinic UUIDs. Not required for Agency Admins.

required
Array of objects (UserRole)

A list of roles associated with a staff member. Agency Admin and other roles may not be combined.

required
object (UserName)
phone
required
string or null
gender
required
string (GenderEnum)
Enum: "m" "fe" "nb"
  • m - Male
  • fe - Female
  • nb - Non-Binary
required
object (StaffProfile)
required
Array of objects (StaffCredential)
required
Array of objects (StaffExternalId)
is_active
boolean

A flag indicating whether the staff member is active and should be allowed to log into Twyll.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "status": "active",
  • "agency": "146639f4-7373-4aed-9807-16621365dd97",
  • "clinic": "string",
  • "roles": [
    ],
  • "name": {
    },
  • "phone": "string",
  • "gender": "m",
  • "profile": {
    },
  • "credentials": [
    ],
  • "external_ids": [
    ],
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "user@example.com",
  • "agency": "146639f4-7373-4aed-9807-16621365dd97",
  • "clinic": "string",
  • "roles": [
    ],
  • "name": {
    },
  • "phone": "string",
  • "gender": "m",
  • "status": "active",
  • "profile": {
    },
  • "credentials": [
    ],
  • "external_ids": [
    ],
  • "is_active": true
}

Update Staff

Update a user.

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>
Request Body schema: application/json
email
string <email>
status
string
agency
string <uuid>
Array of objects (UserRole)

A list of roles associated with a staff member. Agency Admin and other roles may not be combined.

object (UserName)
phone
string or null
gender
string (GenderEnum)
Enum: "m" "fe" "nb"
  • m - Male
  • fe - Female
  • nb - Non-Binary
object (StaffProfile)
Array of objects (StaffCredential)
Array of objects (StaffExternalId)
is_active
boolean

A flag indicating whether the staff member is active and should be allowed to log into Twyll.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "status": "string",
  • "agency": "146639f4-7373-4aed-9807-16621365dd97",
  • "roles": [
    ],
  • "name": {
    },
  • "phone": "string",
  • "gender": "m",
  • "profile": {
    },
  • "credentials": [
    ],
  • "external_ids": [
    ],
  • "is_active": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "user@example.com",
  • "agency": "146639f4-7373-4aed-9807-16621365dd97",
  • "clinic": "string",
  • "roles": [
    ],
  • "name": {
    },
  • "phone": "string",
  • "gender": "m",
  • "status": "active",
  • "profile": {
    },
  • "credentials": [
    ],
  • "external_ids": [
    ],
  • "is_active": true
}

Sessions

Session endpoints

Get List of Client's Sessions

Custom GenericViewSet to support row-level access support

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string^[0-9a-f-]+$
status
string
Enum: "pending" "active" "completed" "cancelled" "signed"
  • pending - The session is scheduled but has not yet started.
  • active - The session is currently in progress.
  • completed - The session has been completed.
  • cancelled - The session has been cancelled.
  • signed - The session has been completed and its corresponding note has been signed.
scheduled_start_after
string <date>

Returns sessions that are scheduled to start on or after the provided date.

scheduled_end_before
string <date>

Returns sessions that are scheduled to end on or after the provided date.

start_after
string <date>

Returns sessions that have started on or after the provided date.

end_before
string <date>

Returns sessions that have ended on or before the provided date.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Client Session

Create new session(s) for provided client. When providing an array, if any of the session objects in the array list fail to create then the entire array will not post sucecssfully.

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string^[0-9a-f-]+$
Request Body schema: application/json
required

You may provide an array of session objects to create, or a singular object not in an array.

One of
uuid
string <uuid>
clinic
required
string <uuid>

The UUID of the clinic that a session is associated with. Ask your Twyll representative for a list of valid clinic UUIDs.

staff
required
string <uuid>

The Twyll UUID of the staff member associated with a session. Cannot be changed once a session has started.

required
SessionTypeEnum (string)
Default: "session"

The type of session. "Session" sessions utilize the Twyll in session experience for capturing observations. "Document" sessions allow for session notes to be captured and are primarily used for supervisor notes.

status
required
string
Enum: "active" "cancelled"

The session's status. PENDING has been deprecated.

pos
required
string (PosCodeEnum)
Enum: "02" "03" "10" "11" "12"
  • 02 - Telehealth (Other)
  • 03 - School
  • 10 - Telehealth in Home
  • 11 - Office
  • 12 - Home
object (SessionAddress)

The location associated with a session. If the address does not exist, it will be added to the client profile.

scheduled_start_at
required
string <date-time>

The time in which a session is expected to start (UTC). Cannot be changed once a session has started.

scheduled_end_at
required
string <date-time>

The time in which a session is expected to end (UTC). Cannot be changed once a session has started.

source
required
string

The sending system for a session.

funder
string <= 255 characters
Array of objects (SessionExternalIds)
Array of objects (SessionBillcodes)
CancelReasonEnum (string) or BlankEnum (any)
cancel_comment
string

Responses

Request samples

Content type
application/json
Example
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "staff": "8d657703-cb5b-4a28-99bb-c9684975d400",
  • "session_type": "session",
  • "status": "active",
  • "pos": "02",
  • "address": {
    },
  • "scheduled_start_at": "2024-10-23T13:30:00Z",
  • "scheduled_end_at": "2024-10-23T13:30:00Z",
  • "source": "External System Name",
  • "funder": "Blue Cross Blue Shield",
  • "references": [
    ],
  • "billcodes": [
    ],
  • "cancel_reason": "client_illness",
  • "cancel_comment": "string"
}

Response samples

Content type
application/json
Example
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "staff": "8d657703-cb5b-4a28-99bb-c9684975d400",
  • "session_type": "session",
  • "status": "active",
  • "note_state": "pending",
  • "pos": "02",
  • "address": {
    },
  • "scheduled_times": {
    },
  • "source": "External System Name",
  • "references": [
    ],
  • "billcodes": [
    ],
  • "mileage": 22,
  • "drive_times": [
    ],
  • "actual_times": [
    ],
  • "signatures": [
    ],
  • "cancel_reason": "client_illness",
  • "cancel_comment": "string"
}

Get Session

Retrieve a specific session for a client.

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string^[0-9a-f-]+$
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "staff": "8d657703-cb5b-4a28-99bb-c9684975d400",
  • "session_type": "session",
  • "status": "active",
  • "note_state": "pending",
  • "pos": "02",
  • "address": {
    },
  • "scheduled_times": {
    },
  • "source": "External System Name",
  • "references": [
    ],
  • "billcodes": [
    ],
  • "mileage": 22,
  • "drive_times": [
    ],
  • "actual_times": [
    ],
  • "signatures": [
    ],
  • "cancel_reason": "client_illness",
  • "cancel_comment": "string"
}

Overwrite Session Info

Overwrites session information

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string^[0-9a-f-]+$
uuid
required
string <uuid>
Request Body schema: application/json
required
staff
string <uuid>

The Twyll UUID of the staff member associated with a session. Cannot be changed once a session has started.

status
string
Enum: "pending" "cancelled"

The session's status

SessionTypeEnum (string)
Default: "session"

The type of session. "Session" sessions utilize the Twyll in session experience for capturing observations. "Document" sessions allow for session notes to be captured and are primarily used for supervisor notes.

object (SessionAddress)

The location associated with a session. If the address does not exist, it will be added to the client profile.

scheduled_start_at
string <date-time>

The time in which a session is expected to start (UTC). Cannot be changed once a session has started.

scheduled_end_at
string <date-time>

The time in which a session is expected to end (UTC). Cannot be changed once a session has started.

source
string

The sending system for a session.

funder
string <= 255 characters
Array of objects (SessionExternalIds)
Array of objects (SessionBillcodes)
CancelReasonEnum (string) or BlankEnum (any)
cancel_comment
string

Responses

Request samples

Content type
application/json
{
  • "staff": "8d657703-cb5b-4a28-99bb-c9684975d400",
  • "status": "pending",
  • "session_type": "session",
  • "address": {
    },
  • "scheduled_start_at": "2024-10-23T13:30:00Z",
  • "scheduled_end_at": "2024-10-23T13:30:00Z",
  • "source": "External System Name",
  • "funder": "Blue Cross Blue Shield",
  • "references": [
    ],
  • "billcodes": [
    ],
  • "cancel_reason": "client_illness",
  • "cancel_comment": "string"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "staff": "8d657703-cb5b-4a28-99bb-c9684975d400",
  • "session_type": "session",
  • "status": "active",
  • "note_state": "pending",
  • "pos": "02",
  • "address": {
    },
  • "scheduled_times": {
    },
  • "source": "External System Name",
  • "references": [
    ],
  • "billcodes": [
    ],
  • "mileage": 22,
  • "drive_times": [
    ],
  • "actual_times": [
    ],
  • "signatures": [
    ],
  • "cancel_reason": "client_illness",
  • "cancel_comment": "string"
}

Update Session

Update a session.

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string^[0-9a-f-]+$
uuid
required
string <uuid>
Request Body schema: application/json
staff
string <uuid>

The Twyll UUID of the staff member associated with a session. Cannot be changed once a session has started.

status
string
Enum: "pending" "cancelled"

The session's status

SessionTypeEnum (string)
Default: "session"

The type of session. "Session" sessions utilize the Twyll in session experience for capturing observations. "Document" sessions allow for session notes to be captured and are primarily used for supervisor notes.

object (SessionAddress)

The location associated with a session. If the address does not exist, it will be added to the client profile.

scheduled_start_at
string <date-time>

The time in which a session is expected to start (UTC). Cannot be changed once a session has started.

scheduled_end_at
string <date-time>

The time in which a session is expected to end (UTC). Cannot be changed once a session has started.

source
string

The sending system for a session.

funder
string <= 255 characters
Array of objects (SessionExternalIds)
Array of objects (SessionBillcodes)
CancelReasonEnum (string) or BlankEnum (any)
cancel_comment
string

Responses

Request samples

Content type
application/json
{
  • "staff": "8d657703-cb5b-4a28-99bb-c9684975d400",
  • "status": "pending",
  • "session_type": "session",
  • "address": {
    },
  • "scheduled_start_at": "2024-10-23T13:30:00Z",
  • "scheduled_end_at": "2024-10-23T13:30:00Z",
  • "source": "External System Name",
  • "funder": "Blue Cross Blue Shield",
  • "references": [
    ],
  • "billcodes": [
    ],
  • "cancel_reason": "client_illness",
  • "cancel_comment": "string"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "staff": "8d657703-cb5b-4a28-99bb-c9684975d400",
  • "session_type": "session",
  • "status": "active",
  • "note_state": "pending",
  • "pos": "02",
  • "address": {
    },
  • "scheduled_times": {
    },
  • "source": "External System Name",
  • "references": [
    ],
  • "billcodes": [
    ],
  • "mileage": 22,
  • "drive_times": [
    ],
  • "actual_times": [
    ],
  • "signatures": [
    ],
  • "cancel_reason": "client_illness",
  • "cancel_comment": "string"
}

Delete a Session

Delete a session. Only pending sessions (sessions which have not been started or canceled) may be deleted.

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string^[0-9a-f-]+$
uuid
required
string <uuid>

Responses

Get Session List

Get a list of sessions given one or more of the provided parameters.

Authorizations:
bearerAuth
query Parameters
end_before
string <date>
scheduled_end_before
string <date>
scheduled_start_after
string <date>
start_after
string <date>
status
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Session Notes

Session Note endpoints

Get Session Note

Retrieve a session note as a base64 encoded PDF.

Authorizations:
bearerAuth
path Parameters
client_uuid
required
string <uuid> ^[0-9a-f-]+$
session_uuid
required
string <uuid> ^[0-9a-f-]+$

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
  • "staff_id": "4dfd334e-64d8-4482-906d-5dadd5efac56",
  • "soap_note": "string"
}

Notifications

Notification endpoints

NewSend Bulk Notifications

Send notifications to all users associated with a clinic if provided, or all users in the agency.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object (Notification)

The notification details.

clinic
string <uuid>

The UUID of the clinic to send notifications to. If not provided, notifications will be sent to all users in the agency.

autoclose
integer

The number of milliseconds to automatically close the notification. If not provided, the notification will not automatically close.

Responses

Request samples

Content type
application/json
{
  • "notification": {
    },
  • "clinic": "f88966de-1f8f-43e3-80b5-5d9ae2fdae64",
  • "autoclose": 0
}

Response samples

Content type
application/json
{
  • "message": "Notifications created successfully for specified users."
}

NewCreate User Notification

Creates a new notification for the specified user.

Authorizations:
bearerAuth
path Parameters
user_uuid
required
string <uuid>
Request Body schema: application/json
required
notification_type
required
string
Enum: "default" "default_with_icons"

The type of notification to send. If not provided, default will be used.

category
required
string
Default: "info"
Enum: "info" "success" "warning" "error"

The category of notification to send. If not provided, will be used.

object
title
required
string <= 255 characters

The title of the notification.

description
string <= 255 characters

The body of the notification.

Responses

Request samples

Content type
application/json
{
  • "notification_type": "default",
  • "category": "info",
  • "action_link": {
    },
  • "title": "string",
  • "description": "string"
}