API - Users

Support Center > API Integration

Published 02/04/2014 at 11:30pm UTC

Page viewed 3762 times

Details

How can I manage my company users via the API?

Answer

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)

Gets a list of active (non-deleted) users for your company.  The example above would get user with ID = 5.  All User IDs are the SecureVideo.com internal IDs.  We do not use external IDs (i.e., ones from your system) because for any SecureVideo account, users can be created non-programmatically using the UI by any non-developer, where the external ID would not be known at the time of creation, thus leading to possible duplication and data collisions.

 

 

Create a New User

POST https://api.securevideo.com/user

{
    "FullName": "A. MacGuffin",
    "EmailAddress": "real@mccoy.com",
    "SmsNumber": "3121234567",
    "DefaultResolution": "high",
    "TimeZoneWindowsId": "Eastern Standard Time",
    "HelpNumber": "212-555-5555",
"SystemRoles": "H,P" }

Creates a new user with the specified properties.

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 only receive text message notifications, rather than email notifications.

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.

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. All users with Host or Scheduler roles must also have this role set; 
  • 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)

{
    "FullName": "A. MacGuffin",
    "EmailAddress": "real@mccoy.com",
    "SmsNumber": "3121234567",
    "DefaultResolution": "high",
    "TimeZoneWindowsId": "Eastern Standard Time",
    "HelpNumber": "212-555-5555"
}

Updates the user with the ID specified in the URI with the properties specified in the content of the request.

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)

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