X

API How-To

Data Export

Introduction

Every organization has unique reporting needs. So, nVoq makes transaction data available via the API, allowing the creation of reports on any systems according to any methodology. All transactions can be exported and filtered by a variety of properties such as start and end dates, external ID, and so on. This allows the export and import of transaction data into any reporting environment to query and view the data as required.

This How-To covers the export of transaction data via the API.

Before You Begin

API User Account

If your organization has not already been in contact with our Sales team, please complete this short form on the Developer Registration Page and we will reach out to you regarding a user account and development with our APIs.

Once you have an account, you must change your password before the account can be used for API calls.

Create Some Data

In order to export transaction data from the nVoq system, you must have performed some operations - dictations, shortcuts, etc. The easiest way to do this is to log on with nVoq.Voice and do five to ten dictations. Of course, if you already have an active user base and data on test.nvoq.com, you can skip this step as you will have plenty of transaction data to work with.

External Dependecies

Depending on your programming language of choice, make sure you have the appropriate libraries installed as specified below.

Start your IDE

The nVoq API is a RESTful Web Services and WebSocket API and therefore does not constrain you to any specific platform or programming language. We provide sample code below for Python, C#, and Java. Follow along and run this code in your environment. But, if you prefer C++, Go, or some other language, that's great! Just adapt the code below to your language's web services functionality and you should be good to go.

Let's Go!

Choose your programming language...

Data Request Specifics

The transaction API provides great flexibility for data retrieval. The full list of options can be found in the detailed API documentation here.

The most commonly used search parameters are the start date and end date. Typically, data retrieval is done in batches by date ranges. For example, at 2:15 AM, a job might retrieve the transactions from the prior day between 12:00 AM and 11:59 PM.

Another commonly used feature and/or query parameter is startResult and startLimit. This allows for paging through the data for large data sets. This is illustrated in the code sample below.

# Load the dictations between the start and end date into a pandas dataframe.
# Then write the data to a csv file.
	
import requests
import json
import pandas as pd

#set parameters below. Server options are test.nvoq.com & healthcare.nvoq.com
#########################################
server = "test.nvoq.com"
username = "YOUR_USERNAME"
password = "YOUR_PASSWORD"
startDay = "01-01-2024"
endDay = "01-31-2024"
#########################################

headers = {"Accept":"application/json"}
params = {"includeDeleted":"false"}

#get the top level org in the hierarchy
getOrgString =  "https://"+server+"/SCVmcServices/rest/organizations"
r = requests.get(getOrgString, params=params, headers=headers,auth=(username,password))
orgs = r.json()
orgId=orgs['id']

#download the dictations
dictationsDF = pd.DataFrame()
print ("downloading transactions...")
resultLimit = 3000
startResult = 0
returnCount = resultLimit
    
#page our way through downloading the data and add it to the dataframe
while returnCount >= resultLimit:
    requestString = "https://"+ server + "/SCVmcServices/rest/transactions"
      params = {"startDate":startDay+" 00:00:00 -0600","endDate":endDay+" 23:59:59 -0600","resultLimit":str(resultLimit), "startResult":str(startResult),"itemType":"dictation"}
    r = requests.get(requestString, params=params, headers=headers,auth=(username,password))
    jsondata = json.loads(r.text)
    df = pd.json_normalize(jsondata)
    returnCount = len(df.index)
    startResult = startResult + resultLimit
    print ("downloaded batch of " + str(returnCount) + " ...")
    if (returnCount != 0):
        #if this is the first set of data, use initialized empty dataframe
        if len(dictationsDF.index) == 0:
            dictationsDF = df
        #otherwise append the newly downloaded data
        else:
            frames = [dictationsDF, df]
            dictationsDF = pd.concat(frames)

print ("Total Dictations Downloaded: " + str(len(dictationsDF.index)))
dictationsDF.to_csv("nVoqDictationExport-"+startDay+"-"+endDay+".csv")
  
import java.io.*;

//...

public class Program {

   //...

   /*
    *  Get all the transactions between start date/time and end date/time
    *  using a specific page size for the request processing.
    */
   private void getTransactions(String aStartDate, String aEndDate, int aPageSize) {

      // Pagination -->
      // Start with item 0 and increment by page size for 
      // subsequent requests.  For example, with a page size of 10,
      // request startResult 0 which returns 0-9, then start result 10
      // which returns 10-19, and so on.  The last page with have <= 10
      // items. When the query returns 0 items, you have reached the end.
      int startResult = 0;
      int returnedResults = Integer.MAX_VALUE;
      
      while (returnedResults > 0) {

         String url = baseUrl + "/SCVmcServices/rest/transactions";

         // query method parameters
         // dates are of the form MM-dd-yyyy, MM-dd-yyyy HH:mm:ss, 
         // or MM-dd-yyyy HH:mm:ss Z
         Map<String, String> myParams = new HashMap<String, String>();
         myParams.put("startDate", aStartDate);
         myParams.put("endDate", aEndDate);
         myParams.put("resultLimit", Integer.toString(aPageSize));
         myParams.put("startResult", Integer.toString(startResult));
         //increment start result for requesting the next batch
         startResult = startResult + aPageSize;
         
         //create a query string to use with our request
         String qString = createQueryString(myParams);

         try {
            StringBuffer sb = httpHelper("GET", url, qString);
            JSONParser jsonParser = new JSONParser();
            Object obj = jsonParser.parse(sb.toString());
            JSONArray xactArray = (JSONArray) obj;
            returnedResults = xactArray.size();
            xactArray.forEach((xact) -> myTransactions.add(new Transaction(xact.toString())));
         } catch (Exception e) {
            System.out.println(e.toString());
         }
      }
   }

   
   //...
}
 

<script>
//TBD
</script>
  
  
using Newtonsoft.Json;

//...

namespace nVoqHttpApiCSharp
{
    class Program
    {

        //...
        /**
        *  Get all the transactions between start date/time and end date/time
        *  using a specific page size for the request processing.
        */
        private static List<Transaction> getTransactions(String aStartDate, String aEndDate, int aPageSize)
        {
            // Pagination -->
            // Start with item 0 and increment by page size for 
            // subsequent requests.  For example, with a page size of 10,
            // request startResult 0 which returns 0-9, then start result 10
            // which returns 10-19, and so on.  The last page with have <= 10
            // items. When the query returns 0 items, you have reached the end.
            int startResult = 0;
            int returnedResults = int.MaxValue;
            List<Transaction> transactions = new List<Transaction>();

            while (returnedResults > 0)
            {

                // query method parameters
                // dates are of the form MM-dd-yyyy, MM-dd-yyyy HH:mm:ss, 
                // or MM-dd-yyyy HH:mm:ss Z
                SortedDictionary<string, string> queryParams = new SortedDictionary<string, string>();
                queryParams.Add("startDate", aStartDate);
                queryParams.Add("endDate", aEndDate);
                queryParams.Add("resultLimit", aPageSize.ToString());
                queryParams.Add("startResult", startResult.ToString());
                startResult = startResult + aPageSize;
                String queryString = createQueryString(queryParams);
                String url = BaseUrl + "/SCVmcServices/rest/transactions";
                url = url + "?" + queryString;
                Console.WriteLine(url);
                List<Transaction> batch = JsonConvert.DeserializeObject<List<Transaction>>(httpHelper("GET", url, null));
                returnedResults = batch.Count;
                if (returnedResults > 0)
                {
                    transactions.AddRange(batch);
                }
            }
            return transactions;
        }

  

Full Sample Code



Below is the full sample code. Copy and paste the entire contents of the code below into your favorite editor and save locally on your machine. Modify the URL's and username/password according to your credentials and system access. Then, run the program and enjoy all the excitement of exporting your transactions from the nVoq.API platform.


  

  

  

  


If you have any questions, please reach out to support@nvoq.com.

© 2024 nVoq Inc. | Privacy Policy