Getting Started¶

This guide will help you get started with the NoteDx Python SDK.

Base URL if using HTTP requests:

https://api.notedx.io/v1

Installation¶

Install the SDK using pip:

pip install notedx-sdk

Or using Poetry:

poetry add notedx-sdk

Create an Account¶

Go to the NoteDx Admin and create an account and manage it in the admin dashboard. You can also use the API to manage it.

After creating your account:

Check your email for the verification link
Click the verification link to activate your account
You can now use either your API keys or email/password to authenticate

Authentication¶

The SDK supports two authentication methods. (But you can always use client.set_api_key(api_key) to set the api key for any operation)

from notedx_sdk import NoteDxClient

# Use your live API key for production
client = NoteDxClient(api_key=live_key)

# Or use sandbox key for testing
client = NoteDxClient(api_key=sandbox_key)

Email/Password Authentication¶

For account management and API key operations: You can add the api key to the client as well.

client = NoteDxClient(
    email="user@example.com",
    password="your-password",
    api_key="lk-xxxxxxxxxxxx" 
)

Quick Examples¶

Generate a Medical Note¶

# Initialize client with your API key
client = NoteDxClient(api_key=live_key)

# Process audio file
response = client.notes.process_audio(
    file_path="visit_recording.mp3",
    template="primaryCare",
    visit_type="initialEncounter",
    recording_type="dictation",
    lang="en"
)

# Get job ID
job_id = response["job_id"]

# Polling for job completion, but it is way better to use the webhooks!
while True:
    status = client.notes.fetch_status(job_id)
    if status["status"] == "completed":
        # Get the note
        note = client.notes.fetch_note(job_id)
        print(note["note"])
        break
    elif status["status"] == "error":
        print(f"Error: {status['message']}")
        break
    time.sleep(5)  # Wait 5 seconds before checking again

Manage Account Settings¶

# Initialize with email/password
client = NoteDxClient(
    email="user@example.com",
    password="your-password"
)

# Get account info
account_info = client.account.get_account()
print(f"Company: {account_info['company_name']}")

# Update settings
client.account.update_account(
    company_name="New Company Name",
    contact_email="new@example.com"
)

Manage API Keys¶

# Create a new live API key
key = client.keys.create_api_key(
    key_type="live",
    metadata={"environment": "production"}
)
print(f"New API key: {key['api_key']}")

# List all keys
keys = client.keys.list_api_keys()
for key in keys:
    print(f"Key: {key['key']}, Type: {key['type']}")

Configure Webhooks¶

# Set up webhooks for notifications
client.webhooks.update_webhook_settings(
    webhook_dev="http://localhost:3000/webhook",
    webhook_prod="https://api.example.com/webhook"
)

Error Handling¶

The SDK provides detailed error classes for better error handling:

from notedx_sdk.exceptions import (
    AuthenticationError,
    AuthorizationError,
    PaymentRequiredError,
    InactiveAccountError,
    ValidationError,
    NetworkError,
    JobError
)

try:
    response = client.notes.process_audio(...)
except AuthenticationError:
    print("Invalid API key or missing user")
except PaymentRequiredError as e:
    if "Free trial jobs depleted" in str(e):
        print("Free trial (100 jobs) depleted. Please subscribe.")
    else:
        print(f"Payment required: {e}")
except InactiveAccountError:
    print("Account is inactive. Please complete setup.")
except ValidationError as e:
    print(f"Invalid parameters: {e}")
except NetworkError as e:
    print(f"Connection error: {e}")
except JobError as e:
    print(f"Job failed: {e}")

Free Trial Limits¶

Each account starts with 100 free jobs with a live API key
After 100 jobs, payment is required to continue
Sandbox API keys have unlimited usage for testing

Account Status¶

Your account can be in one of these states:

active: Full access to all features
trial: Access to 100 free jobs
pending_subscription: Payment required to activate
inactive: Account setup incomplete

For billing details, see Billing & Pricing.

Next Steps¶

Check out the API Reference for detailed documentation
See Examples for more use cases
Contact support at team@notedxai.com for help