Manage User API
There are 5 API methods available to manage your users:
Get a List of Users
GET https://api.securevideo.com/user
Gets a list of active (non-deleted) users for your company.
Get Single User
GET https://api.securevideo.com/user/5 (where 5 is the User ID); or,
GET https://api.securevideo.com/user/0?externalId=XXXXX (where XXXXX is the ExternalId of a User in your EHR/PM system)
Gets a single user for your company. The example above would get user with ID = 5. Most of the properties returned are explained in the Create New User section below, except for the following two read-only properties:
SystemUserId is the SecureVideo internal ID, which once assigned can never change.
VideoId is a SecureVideo identifier which maps 1-to-1 to SystemUserId, where the first digits in the VideoId are the SystemUserId zero-padded to 10 places and additional information is encoded. VideoId is generally not needed in new implementations; it is included for backwards compatibility with SecureVideo API implementations completed prior to January 1, 2015.
NewPassword is a property used to set a new temporary password for a user; it will be null when getting a user.
{
"SystemUserId": "23487",
"FullName": "I. A. Example",
"EmailAddress": "[email protected]",
"SmsNumber": "",
"DefaultResolution": "high",
"TimeZoneWindowsId": "Pacific Standard Time",
"HelpNumber": "111-334-8512",
"VideoId": "securevideo+sv000002348795507371",
"ExternalId": "",
"SystemRoles": "H,P",
"NewPassword": null
}
Create a New User
POST https://api.securevideo.com/user
{
"FullName": "A. MacGuffin",
"EmailAddress": "[email protected]",
"SmsNumber": "3121234567",
"DefaultResolution": "high",
"TimeZoneWindowsId": "Eastern Standard Time",
"HelpNumber": "212-555-5555",
"NewPassword":"Ch@ngeThis1!",
"ExternalId": "EMR123456",
"SystemRoles": "H,P"
}
Creates a new user with the specified properties. No welcome email is sent to the new user if created through the API.
E-Mail Address must be unique, or a 400 status code is returned.
SmsNumber should be either a US or Canadian smart phone number. If filled in, the user will receive text message notifications by default, rather than email notifications. (These can be modified within the user's "My Options" section of their SecureVideo account.)
DefaultResolution 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.
TimeZoneWindowsId is the Windows ID of the time zone, and must be a value from this list of valid time zones. Time Zone is required in our system because it is required by our system's core scheduling functionality. If you enter a single, default time zone for all of your users, the system will still be usable, however those users not in that time zone will see all scheduled sessions in that (incorrect) time zone, which may lead to some confusion.
HelpNumber is required and is very important, as it is displayed on the patient's screen as a number to call in the event there is a technical problem with the video session.
NewPassword will provide the user with a password in the event you would like them to login. They will be required to change this password immediately upon logging in for the first time.
ExternalId is an identifier that you get and set in the API only; ExternalId is not currently exposed in the SecureVideo user interface. ExternalId can be used to maintain the unique provider and/or patient mappings between your EHR/EMR/PM system and SecureVideo.
SystemRoles are a comma-separated list of single characters which specify roles that the user will have in the system. SystemRoles are optional, and when omitted the default roles are "H,P". For videoconferencing customers, the role explanations are:
- A = Admin: has full and unlimited account access. Admins have SystemRoles set to "A", and can have no other SystemRoles. For security purposes, Admins cannot be set via the API.
- H = Host: can schedule and host videoconferencing sessions.
- P = Participant: can participate in videoconferencing sessions, but cannot host or schedule sessions. Can request a session in a virtual clinic. All users with Host or Scheduler roles must also have this role set. Meant for a user who is a member of your organization, or who is acting as a telehealth provider.
- I = Public User: limited user role for patients (separate from organizational users), that are usually created through self-registration to make virtual clinic session requests.
- B = Billing Manager: has access to the account billing information, such as invoicing and usage reports.
- S = Scheduler: can schedule sessions for other users. Schedulers must also have Participant roles, and may or may not have Host roles.
- C = Clinical Supervisor: if enabled on the account, has unrestricted access to all clinical data, such as recordings, session notes, and e-Documents.
Examples of valid SystemRoles to include in your POST /user command:
- H,P: Host and Participant. This is the default role set for any user where you don't specify the roles. You should use these roles for most users.
- B,H,P: Billing Manager, Host, and Participant. This user is a host who can also access invoices and usage history.
- P: Participant only. This role makes sense for patients, or other users who you will authenticate in order to connect to a session, but who should not have the ability to schedule a session.
Examples of invalid SystemRoles to include in your POST /user command:
- A: You cannot set the Admin role via the API. This must be set via the user interface.
- S: Schedulers must also have the participant role, so this would need to be "S,P" (or "P,S").
Generally, prior to calling the Create API command, you will want to first check if the record exists. It is also recommended to schedule a task to update your user records periodically (perhaps a nightly or weekly cron/scheduled task), in the event that the e-mail address or help number has changed.
If the specified record already exists, and you try to create it anyway, then the e-mail address will probably be a duplicate, and you can expect a 400 Status Code returned.
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.
Update an Existing User
PUT https://api.securevideo.com/user/5 (where 5 is the User ID); or,
PUT https://api.securevideo.com/user/0?externalId=XXXXX (where XXXXX is the ExternalId of a User in your EHR/PM system)
{
"FullName": "A. MacGuffin",
"EmailAddress": "[email protected]",
"SmsNumber": "3121234567",
"DefaultResolution": "high",
"TimeZoneWindowsId": "Eastern Standard Time",
"HelpNumber": "212-555-5555",
"ExternalId": "EMR123456",
"SystemRoles": "H,P"
}
Updates the user with the ID specified in the URI with the properties specified in the content of the request. No update email is sent to the user.
See "Create a New User" above for remarks on each property.
If the user is not found, a 404 Status Code will result.
On success, this request will return a 200 Status Code, along with content containing the newly updated record.
Delete an Existing User
DELETE https://api.securevideo.com/user/5 (where 5 is the User ID); or,
DELETE https://api.securevideo.com/user/0?externalId=XXXXX (where XXXXX is the ExternalId of a User in your EHR/PM system)
Deletes the user with the ID specified in the URI.
Users with Admin privileges cannot be deleted.
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.
