Documentation Index
Fetch the complete documentation index at: https://docs.sully.ai/llms.txt
Use this file to discover all available pages before exploring further.
This guide walks you through your first Sully.ai integration: uploading an audio file, transcribing it, and generating a SOAP note.
Prerequisites
Before you begin, make sure you have:
- A Sully.ai account with API access (contact us to get started)
- Your API Key and Account ID from the Sully dashboard
- Node.js 18+ or Python 3.8+ installed (for SDK usage)
Step 1: Install the SDK
npm install @sullyai/sullyai
Step 2: Set Your Credentials
Store your credentials as environment variables:
export SULLY_API_KEY="your-api-key"
export SULLY_ACCOUNT_ID="your-account-id"
Step 3: Complete Working Example
This example demonstrates the full workflow: upload audio, wait for transcription, generate a SOAP note, and retrieve the result.
import Sully from '@sullyai/sullyai';
import * as fs from 'fs';
const sully = new Sully({
apiKey: process.env.SULLY_API_KEY,
accountId: process.env.SULLY_ACCOUNT_ID,
});
async function main() {
// 1. Upload audio file for transcription
const audioFile = fs.readFileSync('./patient-visit.mp3');
const transcriptionResponse = await sully.audio.transcriptions.create({
audio: new File([audioFile], 'patient-visit.mp3', { type: 'audio/mpeg' }),
});
const transcriptionId = transcriptionResponse.data.transcriptionId;
console.log(`Transcription started: ${transcriptionId}`);
// 2. Poll until transcription completes
let transcription;
while (true) {
const status = await sully.audio.transcriptions.get(transcriptionId);
if (status.data.status === 'completed') {
transcription = status.data.payload.transcription;
console.log('Transcription complete!');
break;
}
if (status.data.status === 'failed') {
throw new Error('Transcription failed');
}
// Status is 'pending' or 'processing' - wait and retry
await new Promise((resolve) => setTimeout(resolve, 2000));
}
// 3. Generate SOAP note from transcription
const noteResponse = await sully.notes.create({
transcript: transcription,
noteType: { type: 'soap' },
});
const noteId = noteResponse.data.noteId;
console.log(`Note generation started: ${noteId}`);
// 4. Poll until note completes
let note;
while (true) {
const status = await sully.notes.get(noteId);
if (status.data.status === 'completed') {
note = status.data.payload;
console.log('Note complete!');
break;
}
if (status.data.status === 'failed') {
throw new Error('Note generation failed');
}
// Status is 'pending' or 'processing' - wait and retry
await new Promise((resolve) => setTimeout(resolve, 2000));
}
// 5. Print the result
console.log('\n--- Generated SOAP Note ---\n');
console.log(note);
}
main().catch(console.error);
Understanding the Status Flow
Both transcriptions and notes follow the same status lifecycle:
| Status | Description |
|---|
pending | Request received, waiting to be processed |
processing | Actively being processed |
completed | Successfully finished, result available in payload |
failed | An error occurred during processing |
For production applications, consider using webhooks instead of polling to receive notifications when processing completes.
Next Steps
Audio Transcription
Learn about streaming audio, language support, and advanced transcription options
Note Customization
Create custom note styles and structured templates for your practice
TypeScript SDK
Full SDK reference and examples for Node.js applications
Python SDK
Full SDK reference and examples for Python applications