Manage Participant API
There are 4 API methods available to manage your session participants:
You can add either a non-SecureVideo user, who will connect to the session using a 9 digit access code, or a SecureVideo user, who will connect to the session by logging on to their dashboard and clicking the "Connect" button. The JSON to be posted differs for the two types of participants to add.
Add Participant to an Existing Session (non-SecureVideo user)
POST https://api.securevideo.com/participant/225 (where 225 is the Session ID); or,
POST https://api.securevideo.com/participant/0?externalSessionId=YYYYY (where YYYYY is the ExternalSessionId of a Session in your EHR/PM system)
{
"ParticipantFullName": "Trevor",
"ParticipantEmailAddress": "[email protected]",
"ParticipantSmsNumber": "13334446666",
"ParticipantDefaultResolution": "high",
"ParticipantTimeZoneWindowsId": "Eastern Standard Time",
"ParticipantExternalId": "EMR123456",
"ShouldAutoDeliverCode": "S",
"PacketId": 1215,
"SvcId": 1037,
"DepositRequired": 20.00
}
Adds the specified participant to the Session, whose ID is specified in the URI. Note that the above JSON is the same as the Participant object used to create a new session via the API.
The participant to be added should not be the Session host, or have the same name as a participant already part of the Session, otherwise a 400 error will be thrown. Any participant with a new name will create a new participant in the SecureVideo user database.
ParticipantFullName is required and must be at least 2 characters.
ParticipantEmailAddress is required if ShouldAutoDeliverCode == "E".
ParticipantSmsNumber is required if ShouldAutoDeliverCode is "S". If ShouldAutoDeliverCode is "E" or "S", the SecureVideo system will send session invites and reminders to the participant, who can use them to RSVP to the session. If ShouldAutoDeliverCode is "N" for any participant, the SecureVideo system will have no role in inviting or reminding that participant about the session.
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. 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 all documents will be shown to the participant.
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 200 Status Code, along with the updated Session object, the format for which can be seen here.
Add Participant to an Existing Session (SecureVideo user)
POST https://api.securevideo.com/participant/225 (where 225 is the Session ID); or,
POST https://api.securevideo.com/participant/0?externalSessionId=YYYYY (where YYYYY is the ExternalSessionId of a Session in your EHR/PM system)
{
"SecureVideoUserId": "1122",
"PacketId": -1,
"SvcId": null,
"DepositRequired": null
}
Adds the specified SecureVideo user as a participant to the Session, whose ID is specified in the URI. Note that the above JSON is the same as the Participant object used to create a new session via the API.
The participant to be added should not be the Session host, or have the same SecureVideoUserId as a participant already part of the Session, otherwise a 400 error will be thrown.
If updating a User (as opposed to a non-User) you would include only Session-specific properties (e.g., PacketId, SvcId, and DepositeRequired), not User-specified properties (e.g., Email Address, SMS Number, ExternalId, etc.) which should be maintained using the User API.
On success, this request will return a 200 Status Code, along with the updated Session object, the format for which can be seen here.
Update Participant (non-SecureVideo user)
PUT https://api.securevideo.com/participant/12345 (where 12345 is the ParticipationId)
PUT https://api.securevideo.com/participant/0?externalSessionId=YYYYY&externalId=XXXXX (where, in your EHR/PM system, XXXXX is the ID of a User and YYYYY is the ID of a Session)
{
"ParticipantFullName": "Trevor",
"ParticipantEmailAddress": "[email protected]",
"ParticipantSmsNumber": "13334446666",
"ParticipantDefaultResolution": "high",
"ParticipantTimeZoneWindowsId": "Eastern Standard Time",
"ParticipantExternalId": "EMR123456",
"ShouldAutoDeliverCode": "S",
"PacketId": 1215,
"SvcId": 1037,
"DepositRequired": 20.00
}
Updates the e-mail address, SMS number, default video resolution, time zone, or delivery method for the participant, who must be a non-SecureVideo user.
You cannot change the ParticipantFullName (for non-SecureVideo users) or SecureVideoUserId (for SecureVideo users), as this would change the identity of the participant. To make these changes, it is necessary to delete the participant and create a new one.
You cannot change any properties of a SecureVideo user using this method. For this, you should use the User API.
For an explanation of the valid properties, please see the discussion above on Add a Participant to an Existing Session (non-SecureVideo user).
On success, this request will return a 200 Status Code, along with the updated Session object, the format for which can be seen here.
Remove Participant from an Existing Session
DELETE https://api.securevideo.com/participant/12345 (where 12345 is the ParticipationId)
DELETE https://api.securevideo.com/participant/0?externalSessionId=YYYYY&externalId=XXXXX (where, in your EHR/PM system, XXXXX is the ID of a User and YYYYY is the ID of a Session)
Removes the participant with the ParticipationId specified in the URI.
On success, this request will return a 204 (No Content) Status Code. The system will also send a cancellation notice to the participant, if s/he had already received an invite.
This article was last reviewed by our Support team on August 20, 2021.
