API - Participants

Support Center > API Integration

Published 02/12/2014 at 3:50pm UTC

Page viewed 3365 times

Details

How do I use the API to add and remove participants from my sessions?

Answer

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)

{
 "ParticipantFullName": "Trevor",
"ParticipantEmailAddress": "trevor@geemail.com",
"ParticipantSmsNumber": "13334446666",
"ParticipantDefaultResolution": "high",
"ParticipantTimeZoneWindowsId": "Eastern Standard Time",
"ShouldAutoDeliverCode": "S",
"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 must be one of the values "hd", "high", "default", or "low". This property value is case sensitive (i.e., "HD" or "High" are not valid values), where "hd" is 720p, "high" is 480p, "default" is 320p, and "low" is 240p.

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.

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)

{
 "SecureVideoUserId": "1122",
 "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.

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 Participation ID)

{
 "ParticipantEmailAddress": "trevor@geemail.com",
"ParticipantSmsNumber": "13334446666",
"ParticipantDefaultResolution": "high",
"ParticipantTimeZoneWindowsId": "Eastern Standard Time",
"ShouldAutoDeliverCode": "S",
 "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 Participant ID)

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 April 19, 2017.