Documents API
There are 3 API methods available to retrieve SecureVideo E-Documents and their associated metadata:
The two GET methods are designed to be used in conjunction with one another. First, you can call the Get Documents API method to obtain a list of documents for a given date range (required, maximum 75 days per request). You can optionally filter by the type of document, and/or by the session host to whom the document was submitted. The Get Documents method returns all data for each document, including the SecureVideo DocumentId, and also returns participant responses to any customer-defined custom metadata associated with the document.
Then, if you wish to retrieve PDFs of any or all of the documents returned by the Get Documents method, you can call the Get PDF API method using the SecureVideo DocumentId to retrieve a Base 64 encoded PDF content which you can then convert back to a binary PDF file. To keep Get PDF calls fast, you can get a maximum of a single Base 64 encoded PDF per call to the Get PDF API.
When retrieving PDFs, the expected usage pattern is to make a single call to the Get Documents endpoint, and then for each Document ID returned by the Get Documents endpoint, call the Get PDF endpoint to retrieve that document.
Get Documents
GET https://api.securevideo.com/document?fromDt=2020-06-01&toDt=2020-08-31
Gets a list of e-documents submitted to all hosts between 6/1/2020 00:00:00 UTC and 2020-08-31 23:59:59 UTC.
GET https://api.securevideo.com/document?fromDt=2020-06-01&toDt=2020-08-31&documentTemplateId=111
Gets a list of e-documents of Document Template Type ID 111 submitted to all hosts between 6/1/2020 00:00:00 UTC and 2020-08-31 23:59:59 UTC.
GET https://api.securevideo.com/document/12345?fromDt=2020-06-01&toDt=2020-08-31
Gets a list of all e-documents submitted to host user ID 12345 between 6/1/2020 00:00:00 UTC and 2020-08-31 23:59:59 UTC.
GET https://api.securevideo.com/document/12345?fromDt=2020-06-01&toDt=2020-08-31&documentTemplateId=111
Gets a list of all e-documents of Document Template ID 111 submitted to host user ID 12345 between 6/1/2020 00:00:00 UTC and 2020-08-31 23:59:59 UTC.
Query String Parameters are as follows::
- FromDt (required): format should be yyyy-mm-dd, the start of the date range on which the e-document was submitted by the session participant. Document time will be queried in UTC, starting at midnight on the date specified.
- ToDt (required): format should be yyyy-mm-dd, the end of the date range on which the e-document was submitted by the session participant. Document time will be queried in UTC, ending at 23:59:59 on the date specified. To keep the API interface performant, ToDt must be no more than 75 days greater than FromDt.
- DocumentTemplateId (optional): an integer specifying the the Document Template ID to filter on. An Administrator can log on and click on Features > E-Documents to view a list of active and inactive Document Templates. In that list are listed the Document Template IDs (e.g., "(ID: 111)").
Document JSON is returned, for example:
[
{
"ReceivedDocumentId": 1493216,
"ReceivedTs": "2020-10-09T07:08:16.557",
"DocumentTemplateId": 12723,
"DocumentTemplateName": "Post-Session Survey",
"ParticipantId": 96028428,
"ViewUrl": "https://yoursubdomain.securevideo.com/Document/ParticipantView/E6AC253872034CE19854846F41660B93A94770618A5E4286BE7D11C7CFA14722?stu=8653ecd6c66d28153ed51bd9b056f0ea",
"FromSystemUserId": 3323234,
"FromSystemUserName": "Perry Patient",
"ToSystemHostId": 1289833,
"ToSystemHostName": "Dr. Kermit Phrog",
"ServiceId": 0,
"ServiceName": null,
"SignedByName": "",
"DocumentIsLandscape": false,
"MetaData": {
"Session Rating": "Fantastic!",
"Use Telehealth Again": "Absolutely!",
"What comedies are you watching": "The Good Place,Silicon Valley"
}
}
]
Returned Document JSON is as follows:
- ReceivedDocumentId is the unique identifier for the Received E-Document.
- ReceivedTs is the time, in UTC, that the E-Documentwas submitted to the host.
- DocumentTemplateId is the ID of the Document Template used to generate the E-Document.
- DocumentTemplateName is the name of the Document Template at the time the E-Document was submitted by the participant.
- ParticipantId is the participant session of the submitter of the E-Document. See Session JSON documentation for more information.
- ViewUrl is a URL which you can use to display the E-Document to a user.
- FromSystemUserId is the SecureVideo User ID of the participant who submitted the E-Document.
- FromSystemUserName is the name of the SecureVideo user at the time the E-Document was submitted.
- ToSystemHostId is the SecureVideo User ID of the session host to whom the E-Document was submitted.
- ToSystemHostName is the name of the session host to whom the E-Document was submitted, at the time the document was submitted.
- ServiceId is the ID of the Service defined for the session in which the E-Document was submitted, if applicable. Otherwise will be 0. This is not widely used.
- ServiceName is the name of the Service defined for the session in which the E-Document was submitted, at the time the E-Document was submitted.
- SignedByName contains the name used in a typed signature. This will be a blank string when mouse- or finger-drawn signatures are used.
- DocumentIsLandscape is a true/false value which indicates whether the Document Template had a Landscape orientation at the time the E-Document was submitted.
- MetaData is a JSON object containing one property per customer-defined field, along with the value entered by the submitter of the E-Document, as follows:
- For textboxes and textareas: the value entered by the user
- For radio buttons: the value shown next to the radio button selected by the user
- For checkbox lists: a comma-separated list of the zero to many values selected by the user
The MetaData returned in the example Document JSON above would have been generated using two steps. First, the MetaData property names "Session Rating", "Use Telehealth Again", and "What comedies are you watching" are defined when editing the Document Template:
Then, the MetaData property values are the responses by the submitter of each E-Document:
So, for each Document Template, as long as you don't change the property names in the Document Template, you will always receive the same MetaData property names for all documents of a certain type, and the MetaData property values will be unique to each submission of the E-Document.
Get PDF
GET https://api.securevideo.com/pdf/888888 (where 888888 is the document ID obtained from the Get Document method)
Returns the Document JSON properties returned by the Get Documents API endpoint, along with the addition of the property PdfBase64Encoded.
[
{
"PdfBase64Encoded": "JVBERi0xLjQKMSAwIG9iag[...Super Long Encoding Here...]AAZABmACAAMAAuADEAMgAuADQpCi9Qcm9kdWNlciAo/v8AUQB0ACAANAAuADgALgA3KQovQ3JlYXRpb25EYXRlIChE",
"ReceivedDocumentId": 1493216,
"ReceivedTs": "2020-10-09T07:08:16.557",
"DocumentTemplateId": 12723,
"DocumentTemplateName": "Post-Session Survey",
"ParticipantId": 96028428,
"ViewUrl": "https://yoursubdomain.securevideo.com/Document/ParticipantView/E6AC253872034CE19854846F41660B93A94770618A5E4286BE7D11C7CFA14722?stu=8653ecd6c66d28153ed51bd9b056f0ea",
"FromSystemUserId": 3323234,
"FromSystemUserName": "Perry Patient",
"ToSystemHostId": 1289833,
"ToSystemHostName": "Dr. Kermit Phrog",
"ServiceId": 0,
"ServiceName": null,
"SignedByName": "",
"DocumentIsLandscape": false,
"MetaData": {
"Session Rating": "Fantastic!",
"Use Telehealth Again": "Absolutely!",
"What comedies are you watching": "The Good Place,Silicon Valley"
}
}
]
If the received document ID is valid but the PDF document is empty or cannot be found, then the PdfBase64Encoded property value will be null.
Delete a Document
DELETE https://api.securevideo.com/document/12345 (where 12345 is the Received Document ID)
Deletes the document with the Received Document ID specified in the URI.
On success, this request will return a 204 Status Code, indicating No Content.
This article was last reviewed by our Support team on February 10, 2021.
