Dorascribe Pay-as-You-Use Integration Guide

Overview

Dorascribe provides organizations with a flexible, pay-as-you-use solution for integrating medical transcription capabilities into their applications. Organizations purchase credits upfront, and credits are automatically deducted after each successful transcription. This eliminates the need for token management and simplifies your integration.

Key Features

• Simple Credit-Based Billing — Purchase credits upfront, pay only for successful transcriptions
• No Token Management — No access tokens to generate, manage, or renew
• Automatic Deduction — Credits deducted automatically after successful note generation
• Dual Integration Methods — Iframe-based or form-based widget initialization
• Flexible Data Delivery — Receive transcriptions via postMessage or callback API
• Real-time Transcription — Powered by Deepgram API for accurate speech-to-text
• Secure — Organization-level API key authentication

Pricing & Credits

Pricing Notes

• Credits are purchased upfront through the organization dashboard
• Credits are deducted after successful transcription on the /widget/generate endpoint
• Failed transcriptions are not charged — you only pay for successful note generation
• Credit balance is checked before generation — requests fail immediately if insufficient credits

Credit Purchase

To Purchase Credits:

1. Log into your organization dashboard on Dorascribe
2. Navigate to the Credits section
3. Select the amount of credits you want to purchase
4. Complete the payment through Stripe
5. Credits are added to your balance immediately after successful payment

Getting Started

Step 1: Create Organization Account

1. Navigate to the registration page
2. Complete the registration form
3. Verify your email address
4. Once logged in to your dashboard, navigate to the organization’s page on the sidebar, and click on the create organization button.

Step 2: Generate Organization API Key

1. Log into your organization dashboard
2. Navigate to API Credentials
3. Click Generate Organization API Key
4. Securely store this key (it will not be shown again). Regeneration is possible

Step 3: Purchase Credits

1. Log into your organization dashboard
2. Navigate to Credits → Purchase Credits
3. Select the amount of credits you want to purchase
4. Complete the payment through Stripe
5. Credits are added to your balance immediately

Organization Management

Dashboard Overview

Once activated, your organization dashboard provides:

• Credit Management — View balance, purchase credits, view usage history
• Usage Analytics — Monitor transcription usage and credit consumption
• API Key Management — Generate and regenerate organization API keys
• Billing History — View all credit purchases and transactions

Organization API Key

The organization API key is used to:

• Authenticate all API requests
• Initialize widget sessions
• Generate medical notes from transcriptions
• Access organization-wide analytics

Format: Bearer {your_organization_api_key} or X-API-Key: {your_organization_api_key}

Credit Management

Credit Balance

Your credit balance is displayed in the organization dashboard. You can:

• View current balance
• View credit usage history
• Purchase additional credits
• View transaction logs

Credit Deduction

Credits are automatically deducted:

• When: After successful note generation on /widget/generate
• Amount: 0.18 credits
• Timing: Deduction occurs after successful content generation
• Failed Requests: No credits are deducted for failed or incomplete transcriptions

Insufficient Credits

If your credit balance is insufficient:

• The request fails immediately with a 402 Payment Required error
• No transcription processing occurs
• You must purchase additional credits to continue

Widget Integration

Overview

Dorascribe provides a unified iframe-based widget integration that combines secure authentication with flexible user input. The widget is embedded into your application via an iframe and presents a user-friendly form for entering patient and language details before starting the transcription session.

Widget URL

https://audio-widget.dorascribe.ai

Integration Architecture

Host App → Widget Iframe → User Form → Transcription Session → Callback

1. Host application embeds the widget via iframe with authentication parameters
2. Widget validates organization API key
3. User fills in patient details and language preferences in the widget UI
4. User starts transcription session
5. Completed transcription is sent to callback URL and/or via postMessage
6. Credits are deducted after successful note generation

Required Parameters

The widget requires authentication parameters passed via URL query string:

• api_key — Organization API Key (required)
• callback — Callback URL for receiving transcription data (optional)

Widget User Interface

Once the widget loads and authentication is successful, users will see a form requesting:

Patient Information

• Patient Age — Age of the patient (number input)
• Patient Name — Name of the patient (optional text input)

Language Settings

• Input Language — Language spoken during transcription (dropdown)
• Input Language Code — Auto-selected based on language choice (e.g., “en”, “es”, “fr”)
• Output Language — Desired language for the final transcription (dropdown)
• Output Language Code — Auto-selected based on output language choice

Additional Fields

• User Name — Name of the healthcare provider/user conducting the transcription
• Template Selection — Choose from available medical note templates (SOAP, Progress Note, etc.)

After filling in these details, the user clicks “Start Transcription” to begin the session.

Implementation Examples

Basic Iframe Integration

<iframe
  src="https://widget.Dorascribe.ai/transcription?api_key=YOUR_ORG_API_KEY&callback=https://your-app.com/api/callback"
  width="100%"
  height="700px"
  frameborder="0"
  allow="microphone"
  title="Dorascribe Widget"
></iframe>

JavaScript Dynamic Loading

// Configuration
const ORG_API_KEY = 'your-org-api-key-here';
const WIDGET_URL = 'https://audio-widget.dorascribe.ai/transcription';
const CALLBACK_URL = 'https://your-app.com/api/callback';

// Create widget iframe
function loadWidget() {
  const iframe = document.createElement('iframe');
  const params = new URLSearchParams({
    api_key: ORG_API_KEY,
    callback: CALLBACK_URL
  });
  iframe.src = `${WIDGET_URL}?${params.toString()}`;
  iframe.width = '100%';
  iframe.height = '700px';
  iframe.frameBorder = '0';
  iframe.setAttribute('allow', 'microphone');
  document.getElementById('widget-container').appendChild(iframe);
}

// Load widget on page load
window.addEventListener('DOMContentLoaded', loadWidget);

Pre-filling Form Data (Optional)

If you want to pre-fill certain fields in the widget form, you can pass additional URL parameters:

<iframe
  src="https://audio-widget.dorascribe.ai/transcription?api_key=YOUR_ORG_API_KEY&callback=https://your-app.com/api/callback&uname=Dr.%20Smith&patient_age=45&language=English&language_code=en&output_language=Spanish&output_language_code=es"
  width="100%"
  height="700px"
  frameborder="0"
  allow="microphone"
></iframe>

Pre-fill Parameters

Note: Even when pre-filled, users can still modify these values before starting the transcription.

Widget Data Collection

The widget form collects the following information from users:

All of this information is included in the final transcription payload sent to your callback URL.

Widget postMessage Events

The widget communicates with the parent application through postMessage events:

Events Sent by Widget

Transcription Complete Payload

{
  type: 'transcription_complete',
  data: {
    id: 'id-here',
    raw_transcription: 'Raw audio transcription...',
    transcription: 'Processed transcription...',
    template_id: 'soap_001',
    template_name: 'SOAP Note',
    template_content: 'S: Patient reports...\nO: Vitals stable...',
    user: 'Dr. Smith',
    organization: 'XYZ Emr Ltd',
    credits_charged: 19,
    metadata: {
      patient_age: 45,
      patient_name: 'John Doe',
      language: 'English',
      language_code: 'en',
      output_language: 'English',
      output_language_code: 'en',
      duration: 180,
      timestamp: '2025-11-16T15:30:00Z'
    }
  }
}

API Reference

Widget Initialization

Endpoint: POST /api/v1/widget/init

Headers:

• X-API-Key: {your_organization_api_key} (required)
• Content-Type: application/json

Request Body:

{
  "patient_name": "Jane Doe",
  "patient_age": 45,
  "template_id": 1,
  "language": "English",
  "language_code": "en",
  "output_language": "English",
  "output_language_code": "en",
  "callback": "https://your-app.com/api/callback"
}

Response:

{
  "success": true,
  "data": {
    "note_id": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "Your Organization",
    "widget_url": "https://widget.Dorascribe.ai/transcription?note_id=..."
  }
}

Generate Note Content

Endpoint: POST /api/v1/widget/generate

Headers:

• X-API-Key: {your_organization_api_key} (required)
• Content-Type: application/json

Request Body:

{
  "note_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Patient presents with...",
  "template_id": 1,
}

Response:

{
  "success": true,
  "data": {
    "content": "Generated medical note content...",
    "template_id": 1,
  }
}

Complete Transcription

Endpoint: POST /api/v1/widget/transcription/complete

Headers:

• X-API-Key: {your_organization_api_key} (required)
• Content-Type: application/json

Request Body:

{
  "note_id": "550e8400-e29b-41d4-a716-446655440000",
  "raw_transcription": "Patient presents with...",
  "transcription": "Processed transcription...",
  "template_content": "Generated note content..."
}

Response:

{
  "success": true,
  "message": "Transcription completed successfully"
}

Error Handling

The widget will display error messages for:

• Invalid organization API key — “Authentication failed. Please contact support.”
• Insufficient credits — “Insufficient credits. Required: {amount}, Available: {balance}”
• Network connectivity issues — “Unable to connect to transcription service.”
• Microphone permission denied — “Microphone access is required for transcription.”
• Missing required fields — “Please fill in all required fields before starting.”

Error Codes

Security Best Practices

1. Origin Verification

// Always verify the message origin
window.addEventListener('message', function(event) {
  // ✅ Verify origin
  if (event.origin !== 'https://audio-widget.dorascribe.ai') {
    console.warn('Received message from untrusted origin:', event.origin);
    return;
  }

  // Process message
  handleWidgetMessage(event.data);
});

2. Callback URL Security

Ensure your callback endpoint:

• Uses HTTPS only
• Validates request signatures or tokens
• Implements rate limiting
• Logs all requests for audit purposes

Responsive Design Considerations

The widget is fully responsive and adapts to different screen sizes. Recommended iframe heights:

• Desktop: 700px
• Tablet: 650px
• Mobile: 100vh (full viewport height)

Responsive Example

.widget-container {
  width: 100%;
  height: 700px;
}

@media (max-width: 768px) {
  .widget-container {
    height: 100vh;
  }
}

<div class="widget-container">
  <iframe
    src="https://audio-widget.dorascribe.ai/transcription?..."
    width="100%"
    height="100%"
    frameborder="0"
    allow="microphone"
  ></iframe>
</div>

Testing URLs

FAQ

Credit Management

Q: How do I purchase credits?
A: Credits can only be purchased through the organization dashboard on Dorascribe. Navigate to Credits → Purchase Credits and complete the payment through Stripe.

Q: When are credits deducted?
A: Credits are deducted after successful note generation on the /widget/generate endpoint. Failed or incomplete transcriptions are not charged.

Q: What happens if I run out of credits?
A: If your credit balance is insufficient, requests will fail immediately with a 402 Payment Required error. You must purchase additional credits to continue.

Q: Can I get a refund for unused credits?
A: Contact support for information about credit refunds and policies.

Billing

Q: How are charges calculated?
A: Charges are based on organization settings. Default is $0.18 per transcription which translates to 0.18 credits per transcription

Integration

Q: Do I need access tokens?
A: No, access tokens are not required for pay-as-you-use organizations. You only need your organization API key.

Q: Can I use the same API key for multiple applications?
A: Yes, you can use the same organization API key across multiple applications and integrations.

Q: How do I handle errors?
A: The widget and API return standard HTTP error codes. Implement proper error handling in your application to manage failures gracefully.

Support

For technical support, API questions, or feature requests:

• Email: help@dorascribe.ai