Manage Session API
There are 4 API methods available to manage your sessions:
All sessions are scheduled in Universal Coordinated Time (UTC). Participant timezones are used by our system to convert the session time from UTC to the relevant timezone for the invitation and reminders. For Meet Now Sessions, the ScheduleTs will be the time that the session was created, and will have a non-zero seconds component, e.g., 2014-04-16T15:11:22. For Scheduled Sessions, the ScheduleTs will have a zero seconds component.
Get a List of Active Sessions
GET https://api.securevideo.com/session/5 (where 5 is the User ID)
Gets a list of active sessions for the user whose ID = 5.
GET https://api.securevideo.com/session
Gets a list of active sessions across your user base. Active sessions are those which are either scheduled for a future date, and happening today, or have happened in the last day. Previous sessions are deactivated nightly by a SecureVideo automated process.
GET https://api.securevideo.com/[email protected]
Gets a list of active sessions across your user base for which the e-mail address specified in the participantEmail query string parameter holds an active connect code.
GET https://api.securevideo.com/session/[email protected] (where 5 is the user ID)
Gets a list of active sessions for the user whose ID = 5 for which the e-mail address specified in the participantEmail query string parameter holds an active connect code.
GET https://api.securevideo.com/session/0?externalId=XXXXX (where XXXXX is the ExternalId of a User in your EHR/PM system)
Gets a list of active sessions for the user whose ID in your EHR/PM system is XXXXX.
For all of these methods, Session JSON is returned containing an array of active sessions. This array may be empty, if the user has no active sessions. For an example of how to interpret Session JSON, click here.
Create a New Session for a User
POST https://api.securevideo.com/session/5 (where 5 is the User ID); or,
POST https://api.securevideo.com/session/0?externalId=XXXXX (where XXXXX is the ExternalId of a User in your EHR/PM system)
{
"ScheduleTs": "2014-04-16T15:00:00",
"IsRecorded": false,
"ExternalSessionId": "EHR.SID.12345",
"Topic": "Some Session Topic",
"Participants":
[
{
"SecureVideoUserId": "12",
"PacketId": -1
},
{
"ParticipantFullName": "Trevor",
"ParticipantEmailAddress": "[email protected]",
"ParticipantSmsNumber": "13334446666",
"ParticipantDefaultResolution": "high",
"ParticipantTimeZoneWindowsId": "Eastern Standard Time",
"ParticipantExternalId": "EMR123456",
"ShouldAutoDeliverCode": "S",
"PacketId": 1215,
"SvcId": 1037,
"DepositRequired": 20.00
}
]
}
Creates a new user with the specified properties. Note that the above JSON you will POST to create a new session that is a strict subset of the JSON you will receive from GET /session.
To schedule a future session, ScheduleTs is required, and the seconds component should be null or will be adjusted thereto by the API endpoint. ScheduleTs is always in UTC time, using ISO time format without time zone (e.g., 2014-04-16T15:00:00). To schedule a session for right now, set ScheduleTs to null.
IsRecorded specifies whether the session will be recorded to the SecureVideo cloud. If true, and your account has been configured by SecureVideo to have recording privileges, then the session will be recorded. Otherwise, the session will not be recorded.
ExternalSessionId saves the Session ID from your EHR/PM system as part of the new session. With this Session ID saved in SecureVideo, you are able to reschedule or delete the session using the ExternalSessionId in the PUT or DELETE methods described below. Once an ExternalSessionId is set, it cannot be changed. This is an optional property which can be omitted, null, or an empty string.
Topic can be used to describe your session. The Topic will appear on the dashboard of the session host and any schedulers viewing that host's dashboard, and will also be returned by GET Session API calls. This is an optional property which can be omitted, null, or an empty string.
The Participants array must have at least one object. Do not add the session host (e.g., a clinician) to the participant array, only add session guests (e.g., patients).
You can include either of two types of Participants to the Session: SecureVideo users, or non-SecureVideo users. In the JSON example above, we are adding one of each: the SecureVideo user with the User ID of 12, and a non-SecureVideo user named Trevor.
When adding a SecureVideo user to the session, you should only include the SecureVideoUserId. (The SecureVideoUserId is the SystemUserId returned when creating a new user, or getting a list of users.)
When adding a non-SecureVideo user to the session, you should include the fields described above. Some guidelines for non-SecureVideo users include:
ParticipantFullName is required and must be at least 2 characters. If ShouldAutoDeliverCode is N, then the ParticipantEmailAddress and ParticipantSmsNumber may be blank, otherwise, one or the other is required.
- "E": If ParticipantEmailAddress exists, the SecureVideo system will send via e-mail a Session invite and Session reminders to this participant.
- "S": If ParticipantSmsNumber exists, the SecureVideo system will send via text message a Session invite and Session reminders to this participant.
- "N": No automatic delivery of the code will occur. The Session host, or your system, will be responsible for providing invites and reminders to the Participant.
ParticipantDefaultResolution is a legacy property used for backwards compatibility. Please set this property to "high".
If you specify ParticipantTimeZoneWindowsId, the participant will have Session times indicated in his/her specific time zone. If you do not specify ParticipantTimeZoneWindowsId, the participant will have Session times expressed in the time zone of the Session Host. The list of valid time zones can be seen here.
ParticipantExternalId is an identifier that you get and set in the API only; ParticipantExternalId is not currently exposed in the SecureVideo user interface. ParticipantExternalId can be used to maintain the unique provider and/or patient mappings between your EHR/EMR/PM system and SecureVideo.
If you have set up Packets for your e-Documents, you can use PacketId to specify which packet of e-Documents should be visible to the participant. To do this, set PacketId to the ID of the Packet in your e-Documents configuration. To show all documents to a participant (even any added to your customer account after you create this meeting), use 0. To show no documents to a participant, use -1. If you omit this field or use null, then no documents will be shown to the participant (equivalent to passing -1).
If you have set up Stripe payments in the UI (Features > Get Paid Online), you can specify a deposit that this participant must pay the DepositRequired amount (in US dollars) by credit card prior to entering the waiting room to receive a specified Service referenced by the SvcId that you would find as the Service ID on your "Account Services" screen. If you specify null for both SvcId and DepositRequired (the default), then the participant will be able to enter the waiting room without making a payment. SvcId and DepositRequired must both either be null, or both be not null.
On success, this request will return a 201 Status Code, indicating that a new record was created, along with content containing the newly created record.
Reschedule a Session
PUT https://api.securevideo.com/session/225 (where 225 is the Session ID); or,
PUT https://api.securevideo.com/session/0?externalSessionId=YYYYY (where YYYYY is the ExternalSessionId of a Session in your EHR/PM system)
{"ScheduleTs": "2014-02-04T22:00:00"}
Reschedules the session with the ID specified in the URI to the time indicated in the content of the request. Reschedule notifications are sent to all participants who have ShouldAutoDeliverCode = true.
ScheduleTs is always in UTC time, with zero seconds component, using ISO time format without time zone (e.g., 2014-04-16T15:00:00). To schedule a session for right now, set ScheduleTs to null.
On success, this request will return a 200 Status Code, along with content containing the newly updated record.
Cancel a Session
DELETE https://api.securevideo.com/session/225 (where 225 is the Session ID); or,
DELETE https://api.securevideo.com/session/0?externalSessionId=YYYYY (where YYYYY is the ExternalSessionId of a Session in your EHR/PM system)
Cancels the session with the ID specified in the URI. Cancellation notifications are sent to all participants who have ShouldAutoDeliverCode = true.
On success, this request will return a 204 Status Code, indicating No Content.
This article was last reviewed by our Support team on June 8, 2021.
