​
Eka Care Ekascribe Python SDK Integration

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

​
Overview

Eka Care provides an Ekascribe service that allows you to transcribe audio files into structured medical data. The Python 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

  • Python 3.6 or higher
  • pip for dependency management
  • Client credentials (client ID and secret) from Eka Care

​
Installation

You can add the Eka Care Python SDK to your project using pip:

pip install ekacare

​
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:

from ekacare import EkaCareClient

# Initialize the client
client = EkaCareClient(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Login to get tokens
token_response = client.auth.login()
access_token = token_response["access_token"]
refresh_token = token_response["refresh_token"]

# Set access token manually if needed
client.set_access_token(access_token)

# Refresh token when needed
refreshed_tokens = client.auth.refresh_token(refresh_token)
new_access_token = refreshed_tokens["access_token"]

​
Step 3: Upload Audio Files

Upload audio files for transcription:

# Prepare files and metadata
audio_files = [
    "path/to/audio_file1.mp3",
    "path/to/audio_file2.mp3"
]
# Optional fields transaction_id, extra_data, action
transaction_id = "unique_transaction_id"  
extra_data = {
    "mode": "dictation"
}
action = "ekascribe"

# Upload files
responses = client.files.upload(
    file_paths=audio_files, 
    txn_id=transaction_id, 
    action=action, 
    extra_data=extra_data
)

# Process responses
for response in responses:
    # Handle response data as needed
    print(response)

​
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:

import base64

# Get the session ID from the webhook callback
session_id = "unique_transaction_id"  # This comes from the webhook payload which equals to transaction_id of Step 3: Upload Audio files 

# Fetch session status and results
session_status = client.v2rx.get_session_status(session_id)

# Sample response structure
# {
#   "status": "completed",
#   "error": {},
#   "data": {
#     "output": {
#       "fhir": "base64_encoded_fhir_data..."
#     }
#   }
# }

# Extract and decode the FHIR data
if "data" in session_status and "output" in session_status["data"] and "fhir" in session_status["data"]["output"]:
    encoded_fhir = session_status["data"]["output"]["fhir"]
    decoded_bytes = base64.b64decode(encoded_fhir)
    fhir_json = decoded_bytes.decode('utf-8')

​
Complete Example

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

from ekacare import EkaCareClient
import base64
import time

def ekascribe_integration_example():
    try:
        # Initialize the client
        client = EkaCareClient(
            client_id="your_client_id",
            client_secret="your_client_secret"
        )
        
        # Authenticate
        authenticate_client(client)
        
        # Upload audio files
        transaction_id = "unique_transaction_id"
        upload_audio_files(client, transaction_id)
        
        # 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 session_id would come from the webhook payload
        session_id = transaction_id         # "session_id_from_webhook"
        get_transcription_results(client, session_id)
        
    except Exception as e:
        print(f"Error: {str(e)}")

def authenticate_client(client):
    token_response = client.auth.login()
    client.set_access_token(token_response["access_token"])

def upload_audio_files(client, transaction_id):
    audio_files = [
        "path/to/audio1.mp3",
        "path/to/audio2.mp3"
    ]
    
    extra_data = {
        "mode": "dictation"
    }
    
    responses = client.files.upload(
        file_paths=audio_files, 
        txn_id=transaction_id, 
        action="ekascribe", 
        extra_data=extra_data
    )
    
    return responses

def get_transcription_results(client, session_id):
    session_status = client.v2rx.get_session_status(session_id)
    
    if "data" in session_status and "output" in session_status["data"] and "fhir" in session_status["data"]["output"]:
        encoded_fhir = session_status["data"]["output"]["fhir"]
        decoded_bytes = base64.b64decode(encoded_fhir)
        fhir_json = decoded_bytes.decode('utf-8')
        return fhir_json
    else:
        # Handle non-completed status
        return None

if __name__ == "__main__":
    ekascribe_integration_example()

The uploader automatically:

  • Determines appropriate upload method based on file size
  • Uses multipart upload for large files (>100MB)
  • Detects content types from file extensions
  • Groups related files with transaction IDs

​
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
  4. Import Errors: Make sure you’ve installed all necessary dependencies

​
Support

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