Skip to main content

​
Welcome to the MediSync API

MediSync provides APIs for medical AI, transcription, and healthcare data management. This guide walks you through a first integration with the Dashboard API: authenticate, create an appointment, attach a recording, and retrieve the AI-generated transcription and clinical notes.

​
Prerequisites

Sign up for a MediSync account at app.medisync.me. You’ll authenticate with your professional email and password.
Creating appointments and generating AI notes require an active subscription or trial. New accounts start on a trial; check your status in the dashboard.

​
Step 1: Authenticate

Authenticate with your MediSync credentials to obtain a JWT token: 
curl -X POST https://app.medisync.me/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "doctor@example.com",
    "password": "your_password",
    "remember": false
  }'
Response: 
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "uid": "6578a1b2c3d4e5f601234567",
  "userTitle": "Dr.",
  "firstName": "John",
  "lastName": "Doe",
  "twoFactorEnabled": false
}
Save the token — you’ll send it as a Bearer token on every protected request. The token carries your user identity, so no separate user id is needed. Standard tokens are valid for 24 hours (7 days when remember is true). See Authentication.
Include the token in the Authorization header on all protected endpoints: 
Authorization: Bearer YOUR_JWT_TOKEN

​
Step 2: Create an appointment

Create an appointment. The doctor is taken from your token. 
curl -X POST https://app.medisync.me/api/appointments/add \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Erstberatung",
    "date": "2026-07-15",
    "time": "14:30",
    "status": "planned",
    "language": "de",
    "appointment_type": "in_person"
  }'
Response: 
{
  "success": true,
  "data": {
    "_id": "665f8a1b2c3d4e5f6789012f3",
    "name": "Erstberatung",
    "date": "2026-07-15T00:00:00.000Z",
    "time": "14:30",
    "status": "planned",
    "doctor_id": "6578a1b2c3d4e5f601234567",
    "language": "de",
    "appointment_type": "in_person"
  }
}
Keep the appointment _id — the recording, transcription, and notes endpoints are all scoped to it.

​
Step 3: Upload a recording

Upload the consultation audio for the appointment. This uses multipart/form-data with an audio file field. 
curl -X POST https://app.medisync.me/api/recordings/add/665f8a1b2c3d4e5f6789012f3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "audio=@consultation_recording.wav"
Supported formats: WAV (recommended), MP3, M4A. Max file size: 500 MB. 16 kHz / 16-bit mono gives the best transcription results. Only one recording is stored per appointment.

​
Step 4: Get the transcription

Retrieve the transcription for the appointment. The response also reports the appointment’s processing status, so you can poll until notes are ready. 
curl -X GET https://app.medisync.me/api/transcriptions/665f8a1b2c3d4e5f6789012f3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "data": [
    {
      "_id": "665f8a1b2c3d4e5f6789012f7",
      "appointment_id": "665f8a1b2c3d4e5f6789012f3",
      "transcription": [
        { "sender": "speaker_0", "message": "Guten Tag, was führt Sie zu mir?", "start_time": "00:00:01,200" },
        { "sender": "speaker_1", "message": "Ich habe seit heute Morgen Brustschmerzen.", "start_time": "00:00:05,800" }
      ]
    }
  ],
  "appointmentStatus": "processing",
  "appointmentUpdatedAt": "2026-07-15T13:31:00.000Z"
}
Each transcription is an ordered array of segments (sender, message, start_time). sender values such as speaker_0 / speaker_1 are diarization speaker labels. Adding a transcription automatically triggers clinical note generation in the background.

​
Step 5: Get the AI-generated notes

Once note generation finishes (appointmentStatus becomes finished), retrieve the clinical notes for the appointment: 
curl -X GET https://app.medisync.me/api/notes/665f8a1b2c3d4e5f6789012f3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "data": [
    {
      "_id": "665f1c2a9b1e8a0012ab34cd",
      "appointment_id": "665f8a1b2c3d4e5f6789012f3",
      "notes": "S: Patient reports chest pain since this morning...\nO: ...\nA: ...\nP: ...",
      "summary": "Chest pain, normal findings, continue monitoring"
    }
  ]
}
You can also set or overwrite the notes yourself: 
curl -X POST https://app.medisync.me/api/notes/add/665f8a1b2c3d4e5f6789012f3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "S: ...\nO: ...\nA: ...\nP: ...",
    "summary": "Brief summary of the consultation"
  }'

​
Real-time transcription (Speech API)

For live captioning during a consultation, stream audio to the Speech API over a WebSocket. The JWT is passed as a token query parameter (browser WebSocket clients cannot set custom headers). 
const token = "YOUR_JWT_TOKEN";
const ws = new WebSocket(
  `wss://speech.medisync.me/api/v2/ws/transcribe?token=${token}`
);
ws.binaryType = "arraybuffer";

ws.onopen = () => ws.send(JSON.stringify({
  type: "config",
  audio: { encoding: "pcm_s16le", sample_rate: 16000, channels: 1 },
  language: "de",
  chunk: { strategy: "balanced" }
}));

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "session_ready") startMic(ws);          // begin sending PCM frames
  else if (msg.type === "transcript") console.log(msg.text);
};
See the Speech API for the full protocol.

​
Error handling

MediSync APIs use standard HTTP status codes. Error bodies are JSON; the exact shape depends on the endpoint (some use error, some use message), and platform messages are returned in German. 
{
  "success": false,
  "error": "Appointment not found"
}

Common status codes

  • 401 — missing or invalid token
  • 403 — not the owner of the resource, or subscription required
  • 404 — resource not found
  • 429 — rate limit exceeded (login only)

Authentication tips

  • Send Authorization: Bearer <token>
  • Re-authenticate when a token expires (there is no refresh endpoint)
  • Handle the 2FA challenge on login if enabled

​
Next steps

Live transcription

Real-time speech-to-text over a WebSocket.

Documents

Upload and manage clinical documents.

Connect API

Exchange data with hospital and practice systems.

​
Support

Need help? Email support@medisync.me or visit app.medisync.me.