How do I use the API to manage our Contact records?

Manage Contact API

Contacts can be edited or deleted using only the SecureVideo Contact ID or External ID, but contacts must be associated with a SecureVideo Host ID in order to be created.

• Create Contact
• Edit Contact
  • Edit Contact using Host ID or External ID and Contact Name
  • Edit Contact using Contact IDs or External IDs
• Delete Contact
  • Delete Contact using Host ID or External ID and Contact Name
  • Delete Contact using Contact ID or External ID

Create Contact (requires SecureVideo Host ID)

POST https://api.securevideo.com/Contacts/7777

• (where 7777 is the SecureVideo Host ID); or,

POST https://api.securevideo.com/Contacts/0?hostExternalId=12345

• (where 12345 is the External ID of the host's user account in your EHR/PM system)

{
    "ParticipantFullName": "Terry Bollea",
    "ParticipantDisplayName": "Hulk Hogg",
    "ParticipantEmailAddress": "",
    "ParticipantSmsNumber": "13334446666",
    "ParticipantTimeZoneWindowsId": "Eastern Standard Time",
    "ParticipantContactNotes": "",
    "ParticipantExternalId": "987654",
    }

This will create a contact record under the specified SecureVideo host.

• A host's contacts must have unique names, but Display Names are not required to be unique. If you have participants with the same name, add a differentiating number or other identifier to their name, but keep the same Display Name.

ParticipantFullName is required and must be at least 2 characters.  

ParticipantDisplayName is not required. If a Display Name is given, and the Option "Use Display Names for Contacts" is set to "Yes" for the account, then the Display Name will be used in video session displays instead of the name.

ParticipantEmailAddress is the email address that will be added to the contact record, and used if the contact will be sent notifications by email.  

ParticipantSmsNumber is the mobile number that will be added to the contact record, and used if the contact will be sent notifications by SMS.

ParticipantTimeZoneWindowsId is the time zone that will be used for system notifications sent to or shown to the participant. The list of valid time zones can be seen here. If no time zone value is set, the host's time zone will be used as the participant's time zone.

ParticipantContactNotes are notes for the host and any other organization user with access to this contact record. (This note is not visible to the contact.)

ParticipantExternalId is an identifier that you can set for Contacts in the API only; ExternalId is not currently exposed in the SecureVideo user interface. It can be used to maintain the unique provider and/or patient mappings between your EHR/EMR/PM system and SecureVideo.

On success, this request will return a 200 Status Code.

Edit Contact

Edit Contact using Host ID or External ID and Contact Name

Using the SecureVideo Host ID and SecureVideo Contact Name:

PUT https://api.securevideo.com/Contacts/7777

• (where 7777 is the SecureVideo Host ID, and the Contact is identified according to the ParticipantFullName used in the JSON body); or,

Using the Host's External ID and SecureVideo Contact Name:

PUT https://api.securevideo.com/Contacts/0?hostExternalId=DL12345

• (where DL12345 is the External ID of the host's user account in your EHR/PM system, and the Contact is identified according to the ParticipantFullName used in the JSON body); or,

{
    "ParticipantFullName": "Terry Bollea",
    "ParticipantDisplayName": "Hulk Hogg",
    "ParticipantEmailAddress": "",
    "ParticipantSmsNumber": "13334446666",
    "ParticipantTimeZoneWindowsId": "Eastern Standard Time",
    "ParticipantContactNotes": "",
    "ParticipantExternalId": "987654",
    }

This will update a contact record under the specified SecureVideo host with the newly sent information.

• The Contact's Name can only be updated using the Contact SecureVideo ID or External ID (below).

On success, this request will return a 200 Status Code.

Edit Contact using Contact IDs or External IDs

Using the SecureVideo Contact ID:

PUT https://api.securevideo.com/Contacts/0?contactId=9999

• (where 9999 is the SecureVideo Contact ID); or,

Using the Contact's External ID:

PUT https://api.securevideo.com/Contacts/0?contactExternalId=987654

• (where 987654 is the External ID of the contact's patient record in your EHR/PM system);) 

{
    "ParticipantFullName": "Terry Bollea",
    "ParticipantDisplayName": "Hulk Hogg",
    "ParticipantEmailAddress": "[email protected]",
    "ParticipantSmsNumber": "13334446666",
    "ParticipantTimeZoneWindowsId": "Eastern Standard Time",
    "ParticipantContactNotes": "",
    "ParticipantExternalId": "987654",
    }

This will update a contact record under the specified SecureVideo Contact ID or External ID with the newly sent information.

• The Contact's "External ID" can only be updated if using the SecureVideo Contact ID to identify the contact.
• If multiple contacts have the same Contact External ID, all the contact records with a matching External ID will be updated.

On success, this request will return a 200 Status Code.

Delete Contact

Deleting a Contact will archive it, and remove it from the autofill when scheduling a session. An unarchived contact will need to be unarchived to be used again. See: Contacts: how to archive/unarchive a contact.

Delete Contact using Host and Contact Name

Using the SecureVideo Host ID and SecureVideo Contact Name:

DELETE https://api.securevideo.com/Contacts/7777?contactName=Terry%20Bollea

• (where 7777 is the SecureVideo Host ID, and "Terry Bollea" is the SecureVideo Contact Name); or,

Using the Host's External ID and SecureVideo Contact Name:

DELETE https://api.securevideo.com/Contacts/0?hostExternalId=DL12345?contactName=Terry%20Bollea

• (where DL12345 is the External ID of the host's user account in your EHR/PM system, and "Terry Bollea" is the SecureVideo Contact Name)

On success, this request will return a 200 Status Code.

Delete Contact using Contact ID or External ID

Using the SecureVideo Contact ID:

DELETE https://api.securevideo.com/Contacts/0?contactId=9999

• (where 9999 is the SecureVideo Contact ID); or,

Using the Contact's External ID:

DELETE https://api.securevideo.com/Contacts/0?contactExternalId=987654

• (where 987654 is the External ID of the contact's patient record in your EHR/PM system);) 

This will update a contact record under the specified SecureVideo host with the newly sent information.

• The Contact's "External ID" can only be updated if using the SecureVideo Contact ID to identify the contact.

On success, this request will return a 200 Status Code.

This article was last reviewed by our Support team on November 21, 2024.