​
Eka Care Ekascribe Java SDK Integration

This guide explains how to integrate the Eka Care Ekascribe Java SDK.

​
Overview

Eka Care provides an Ekascribe service that allows you to transcribe audio files into structured medical data. The Java SDK simplifies this integration process.

​
Quick Start

The integration process follows these main steps:

  1. Set up webhook registration (one-time setup)
  2. Install the SDK
  3. Implement authentication
  4. Upload audio files
  5. Process the webhook callback
  6. Retrieve and parse the Ekascribe results

​
Prerequisites

  • Java 8 or higher
  • Maven or Gradle for dependency management
  • Client credentials (client ID and secret) from Eka Care

​
Installation

You can add the Eka Care Java SDK to your project in two ways:

​
Option 1: Using dependency management

​
Maven

<dependency>
    <groupId>care.eka</groupId>
    <artifactId>ekacare-java-sdk</artifactId>
    <version>latest-version</version>
</dependency>

​
Gradle

implementation 'care.eka:ekacare-java-sdk:latest-version'

​
Option 2: Direct download

Download the Eka Java SDK from Maven repository Here

​
Available Template IDs

Eka Care supports multiple output templates for different medical documentation needs. Choose the appropriate template ID based on your requirements:

Template IDDescriptionUse Case
clinical_notes_templateComprehensive clinical notes with structured medical informationGeneral clinical documentation, patient consultations
eka_emr_templateEMR-compatible format for electronic medical recordsIntegration with EMR systems
transcript_templateBasic transcription with minimal structuringSimple audio-to-text conversion

​
Supported Input Languages

Eka Care supports transcription in multiple languages. Specify the appropriate language ID in the input_language parameter:

Language IDLanguage Name
en-INEnglish (India)
en-USEnglish (United States)
hiHindi
guGujarati
knKannada
mlMalayalam
taTamil
teTelugu
bnBengali
mrMarathi
paPunjabi

​
Step 1: Register Webhook (One-time Setup)

Before using the Ekascribe service, register a webhook to receive notifications when transcription is complete:

curl --request POST \
  --url https://api.eka.care/notification/v1/connect/webhook/subscriptions \
  --header 'Authorization: Bearer <auth_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_names": [
      "v2rx.completed"
    ],
    "endpoint": "your-endpoint-url",
    "signing_key": "supersecretkey",
    "protocol": "https"
  }'

​
Step 2: Authentication

Initialize the client with your credentials and obtain access tokens:

import care.eka.EkaCareClient;
import com.fasterxml.jackson.databind.JsonNode;

// Initialize the client
EkaCareClient client = new EkaCareClient("your_client_id", "your_client_secret");

// Login to get tokens
JsonNode tokenResponse = client.getAuth().login();
String accessToken = tokenResponse.get("access_token").asText();
String refreshToken = tokenResponse.get("refresh_token").asText();

// Set access token manually if needed
client.setAccessToken(accessToken);

// Refresh token when needed
JsonNode refreshedTokens = client.getAuth().refreshToken(refreshToken);
String newAccessToken = refreshedTokens.get("access_token").asText();

​
Step 3: Upload Audio Files

Upload audio files for transcription:

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

// Collect all audio files in a list
List<String> audioFiles = new ArrayList<>();
audioFiles.add("<full file path>");
audioFiles.add("<full file path 2>");

// Set your own txn id
String transactionId = "unique_transaction_id";

//Custom keys , you'll get back the exact same in result API
Map<String, Object> extraData = new HashMap<>();
extraData.put("mode", "dictation");
extraData.put("uhid", "unique_patient_id");
extraData.put("hfid", "unique_health_facility_id");

// Define the output format for the V2RX action
Map<String, Object> outputFormat = new HashMap<>();
outputFormat.put("input_language", Arrays.asList("en-IN", "hi"));

// output template ids
Map<String, Object> templateMap1 = new HashMap<>();
templateMap1.put("template_id", "clinical_notes_template");
templateMap1.put("language_output", "en-IN");
// set true if you need codified data (if out supports that)
templateMap1.put("codification_needed", true);

// Sample second template id
Map<String, Object> templateMap2 = new HashMap<>();
templateMap2.put("template_id", "eka_emr_template");
templateMap2.put("language_output", "en-IN");

outputFormat.put("output_template", Arrays.asList(templateMap1, templateMap2));

// Keep this the same
String action = "ekascribe-v2";

// Upload files
JsonNode responses = client.getV2RX().upload(audioFiles, transactionId, action, extraData, outputFormat);

// Process responses
for (JsonNode response : responses) {
    // Handle response data as needed
}

​
Step 4: Handle Webhook Callback

When the transcription is complete, Eka Care will send a webhook notification to your registered endpoint. Here’s a sample of what you’ll receive:

{
  "event": "v2rx.completed",
  "data": {
    "transaction_id": "unique_transaction_id",
    "status": "completed",
    "session_id": "unique_transaction_id"
  },
  "timestamp": "2023-07-20T10:30:00Z"
}

​
Step 5: Retrieve Ekascribe Results

After receiving the webhook notification, retrieve the transcription results:

// Get the transactionId from the webhook callback
String transactionId = "unique_transaction_id";  // This comes from the webhook payload
String action = "ekascribe-v2";

// Fetch session status and results
JsonNode sessionStatus = client.getV2RX().getSessionStatus(transactionId, action);

// Sample response structure
'''{
    "data": {
        "output": [
            {
                "template_id": "clinical_notes_template",
                "value": "<base 64 encoded value>",
                "name": "Clinical Notes Template",
                "status": "success",
                "errors": [],
                "warnings": []
            }
        ]
    }
}'''

// Extract and decode the Template data
if (sessionStatus.has("data") &&
        sessionStatus.get("data").has("output") &&
        sessionStatus.get("data").get("output").isArray() &&
        sessionStatus.get("data").get("output").size() > 0) {

    JsonNode outputNode = sessionStatus.get("data").get("output");
    Integer step = 0;
    for (JsonNode node : outputNode) {
        if (node.has("value")) {
            step++;
            String templateId = node.get("template_id").asText();
            String templateName = node.get("name").asText();
            String encodedValue = node.get("value").asText();
            byte[] decodedBytes = Base64.getDecoder().decode(encodedValue);
            String templateJson = new String(decodedBytes);
            System.out.println("Template: " + templateName + " (" + templateId + ")");
            System.out.println("Decoded Data " + step + " :" + templateJson);
        } else {
            System.out.println("No value found in output node "+ step+ " :"+ node.toPrettyString());
        }
    }

}

​
Complete Example

Here’s a complete example integrating all the above steps:


import care.eka.EkaCareClient;
import com.fasterxml.jackson.databind.JsonNode;

import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Arrays;
import java.util.Base64;

public class EkascribeIntegrationExample {
    public static void main(String[] args) {
        try {
            // Initialize the client
            EkaCareClient client = new EkaCareClient("your_client_id", "your_client_secret");
            
            // Authenticate
            authenticateClient(client);
            
            // Upload audio files
            String transactionId = "unique_transaction_id";
            String action = "ekascribe-v2";

            uploadAudioFiles(client, transactionId, action);
            
            // NOTE: At this point, wait for the webhook callback
            // This would typically be handled by your web server
            
            // Once webhook is received, fetch results
            // The sessionId would come from the webhook payload
            getTranscriptionResults(client, transactionId, action);
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    private static void authenticateClient(EkaCareClient client) throws IOException {
        JsonNode tokenResponse = client.getAuth().login();

        // Extras
        System.out.println("Access Token: " + tokenResponse.get("access_token").asText());
        System.out.println("Refresh Token: " + tokenResponse.get("refresh_token").asText());

        client.setAccessToken(tokenResponse.get("access_token").asText());

        // Refresh token when needed
        JsonNode refreshedTokens = client.getAuth().refreshToken(tokenResponse.get("refresh_token").asText());
        
        // Extras
        System.out.println("New Access Token: " + refreshedTokens.get("access_token").asText());
    }
    
    private static void uploadAudioFiles(EkaCareClient client, String transactionId, String action) throws IOException {
        // Collect all audio files in a list
        List<String> audioFiles = new ArrayList<>();
        audioFiles.add("<full file path>");
        audioFiles.add("<full file path 2>");

        Map<String, Object> extraData = new HashMap<>();
        extraData.put("mode", "dictation");

        //Custom keys , you'll get back the exact same in result API
        extraData.put("uhid", "unique_patient_id"); 
        extraData.put("hfid", "unique_health_facility_id");

        // Define the output format for the V2RX action
        Map<String, Object> outputFormat = new HashMap<>();
        outputFormat.put("input_language", Arrays.asList("en-IN", "hi"));

        // output template ids
        Map<String, Object> templateMap1 = new HashMap<>();
        templateMap1.put("template_id", "clinical_notes_template");
        templateMap1.put("language_output", "en-IN");
        // set true if you need codified data (if out supports that)
        templateMap1.put("codification_needed", true);
        
        // Sample second template id
        Map<String, Object> templateMap2 = new HashMap<>();
        templateMap2.put("template_id", "eka_emr_template");
        templateMap2.put("language_output", "en-IN");
        
        // Add both templates to the output_template list
        outputFormat.put("output_template", Arrays.asList(templateMap1, templateMap2));
        
        List<JsonNode> responses = client.getV2RX().upload(audioFiles, transactionId, action, extraData, outputFormat);
        System.out.println("Upload Responses: " + responses.toString());
    }
    
    private static void getTranscriptionResults(EkaCareClient client, String sessionId, String action) throws IOException {
        JsonNode sessionStatus = client.getV2RX().getSessionStatus(sessionId, action);
        System.out.println("Session Status: " + sessionStatus.toPrettyString());
        
        if (sessionStatus.has("data") &&
                sessionStatus.get("data").has("output") &&
                sessionStatus.get("data").get("output").isArray() &&
                sessionStatus.get("data").get("output").size() > 0) {

            JsonNode outputNode = sessionStatus.get("data").get("output");
            Integer step = 0;
            for (JsonNode node : outputNode) {
                if (node.has("value")) {
                    step++;
                    String templateId = node.get("template_id").asText();
                    String templateName = node.get("name").asText();
                    String encodedValue = node.get("value").asText();
                    byte[] decodedBytes = Base64.getDecoder().decode(encodedValue);
                    String templateJson = new String(decodedBytes);
                    System.out.println("Template: " + templateName + " (" + templateId + ")");
                    System.out.println("Decoded Data " + step + " :" + templateJson);
                } else {
                    System.out.println("No value found in output node "+ step+ " :"+ node.toPrettyString());
                }
            }

        }
    }
}

​
Additional Resources

​
Troubleshooting

​
Common Errors

  1. Authentication Failed: Verify your client ID and secret are correct
  2. File Upload Failed: Ensure file paths are valid and files are readable
  3. Webhook Not Received: Check your endpoint is publicly accessible and correctly registered

​
Support

For additional support, contact the Eka Care developer support team at support@eka.care.