Integration Guide

Everything you need to integrate MedSync's AI voice, transcription, and WhatsApp services into your clinic software.

The MedSync Platform API provides three products you can integrate into your EHR or clinic management software:

Transcription API — send audio of a doctor-patient conversation, get back a transcript and a structured clinical note.
WhatsApp Booking Bot — give your clinic a WhatsApp number where patients can book appointments conversationally, in their language.
Agent Calling — automated AI phone calls to patients for appointment reminders, follow-ups, and confirmations.

Getting Started

Get an API key

Contact us at hello@gomedsync.com to get your client API key. Each key is scoped to your organization with usage tracking and rate limits.

Set the API key header

Include your API key in every request:

curl -H "X-API-Key: your_api_key_here" \
  https://api.gomedsync.com/v1/usage

Choose your base URL

Environment	Base URL
Production	`https://api.gomedsync.com`
Development	`http://localhost:8080`

Authentication

All /v1/* endpoints require the X-API-Key header. Requests without a valid key receive a 401 response.

curl -H "X-API-Key: your_api_key" \
  https://api.gomedsync.com/v1/usage

Note The /health endpoint is public. Webhook callback URLs you provide do not need API key authentication.

Transcription API

Upload an audio recording of a doctor-patient conversation and receive a speaker-diarized transcript with an AI-generated clinical note.

Audio Upload

→

MedSync API

→

Transcript + Clinical Note

Transcribe Audio

POST /v1/transcribe

Request (multipart/form-data)

Field	Type	Required	Description
`audio`	file	Yes	Audio file (webm, mp4, wav, mp3, ogg, flac)
`language`	string	No	Language code: `en`, `es`, `ca`, etc. Default: `en`
`template`	string	No	Note template. Default: `general_consultation`

Example

curl -X POST https://api.gomedsync.com/v1/transcribe \
  -H "X-API-Key: your_api_key" \
  -F "audio=@visit_recording.webm" \
  -F "language=es" \
  -F "template=dental_exam"

Response

{
  "transcript": [
    {
      "text": "So tell me what brings you in today.",
      "start": 0.5,
      "end": 2.8,
      "speaker": 0
    },
    {
      "text": "I've been having headaches for the past week.",
      "start": 3.1,
      "end": 5.9,
      "speaker": 1
    }
  ],
  "clinical_note": "## Chief Complaint\nPatient presents for...",
  "duration_seconds": 342.5,
  "language": "en",
  "template": "dental_exam",
  "client_id": "your_client_id"
}

Tip Speaker 0 is typically the doctor (speaks first, closer to the microphone). Speaker 1 is the patient.

Audio Requirements

Constraint	Value
Max file size	150 MB
Supported formats	webm, mp4, wav, mp3, ogg, flac
Max duration	~60 minutes (longer recordings may timeout)
Recommended	16kHz+ sample rate, clear microphone positioning

Clinical Note Templates

Template	Use Case
`general_consultation`	Standard SOAP-format clinical note
`dental_exam`	Dental examination
`dental_hygiene`	Hygiene / cleaning visit
`dental_treatment`	Procedure / treatment note

WhatsApp Booking Bot

Give your clinic a WhatsApp number where patients can book appointments through natural conversation. The bot handles greetings, questions, slot selection, and booking confirmation in the patient's language.

Patient texts WhatsApp

→

MedSync Bot

→

Fetches your slots

→

Patient picks a time

→

POSTs to your callback

Configure Your Clinic's Bot

POST /v1/whatsapp/configure

Provide two URLs: one where we fetch available appointment slots, and one where we send confirmed bookings.

curl -X POST https://api.gomedsync.com/v1/whatsapp/configure \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_callback_url": "https://your-api.com/webhooks/new-appointment",
    "slots_endpoint_url": "https://your-api.com/api/available-slots"
  }'

Your Slots Endpoint

When a patient asks to book, MedSync calls your slots_endpoint_url to get available times. You must return slots in this format:

Request from MedSync

GET https://your-api.com/api/available-slots?date=2026-05-20&provider_id=optional

Your response

{
  "slots": [
    { "time": "09:00", "provider": "Dr. Garcia" },
    { "time": "09:30", "provider": "Dr. Garcia" },
    { "time": "10:00", "provider": "Dr. Lopez" }
  ]
}

Note Return up to 6 slots. The bot presents them as numbered options so the patient can reply with "1", "2", etc. to select a time.

Appointment Callback

When a patient confirms a booking, MedSync POSTs to your appointment_callback_url:

{
  "patient_name": "Maria Lopez",
  "patient_phone": "+34612345678",
  "date": "2026-05-20",
  "time": "09:30",
  "provider": "Dr. Garcia",
  "language": "es",
  "status": "pending_review",
  "conversation_summary": "Patient requested dental cleaning, preferred morning slot"
}

The appointment starts as pending_review. Your system should confirm or reject it, then optionally notify the patient.

Agent Calling

Make AI-powered outbound phone calls to patients. The agent follows a prompt you define and has a natural voice conversation. After the call, you get the full transcript and an AI summary.

Your App

→

MedSync API

→

AI Phone Call

→

Transcript + Summary

Initiate a Call

POST /v1/agent-call

Field	Type	Required	Description
`patient_phone`	string	Yes	Phone number in E.164 format (e.g. `+34612345678`)
`patient_name`	string	Yes	Patient's name (used in the conversation)
`purpose`	string	Yes	`appointment_reminder`, `appointment_confirmation`, `follow_up`, or `custom`
`context`	object	No	Additional context for the call (see examples below)
`callback_url`	string	No	URL to POST call results when complete
`language`	string	No	Language code. Default: `en`

Appointment Reminder

curl -X POST https://api.gomedsync.com/v1/agent-call \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_phone": "+34612345678",
    "patient_name": "Maria Lopez",
    "purpose": "appointment_reminder",
    "context": {
      "appointment_date": "2026-05-20",
      "appointment_time": "09:30",
      "provider_name": "Dr. Garcia",
      "clinic_name": "Dental Plus"
    },
    "callback_url": "https://your-api.com/webhooks/call-complete"
  }'

Follow-Up Call

{
  "patient_phone": "+34612345678",
  "patient_name": "Maria Lopez",
  "purpose": "follow_up",
  "context": {
    "visit_date": "2026-05-15",
    "procedure": "Tooth extraction",
    "provider_name": "Dr. Garcia"
  }
}

Custom Script

{
  "patient_phone": "+34612345678",
  "patient_name": "Carlos",
  "purpose": "custom",
  "context": {
    "prompt": "You are a friendly receptionist calling to inform the patient that their lab results are ready for pickup. Ask them to come during business hours (9 AM to 6 PM). Be warm and brief."
  },
  "language": "es"
}

Response

{
  "call_sid": "CA1234567890abcdef",
  "status": "initiated",
  "message": "Call initiated to +34612345678"
}

Save the call_sid to check the call status and retrieve the transcript later.

Check Call Status

GET /v1/agent-call/{call_sid}

curl https://api.gomedsync.com/v1/agent-call/CA1234567890abcdef \
  -H "X-API-Key: your_api_key"

{
  "call_sid": "CA1234567890abcdef",
  "status": "completed",
  "duration_seconds": 45,
  "purpose": "appointment_reminder",
  "summary": "Patient confirmed appointment for May 20 at 9:30 AM with Dr. Garcia.",
  "patient_phone": "+34612345678"
}

Possible statuses: initiated, ringing, in-progress, completed, failed, no-answer, busy.

Fetching the Full Transcript

After a call completes, the transcript and AI summary are included in the status response and callback payload. Poll GET /v1/agent-call/{call_sid} until status is completed:

{
  "call_sid": "CA1234567890abcdef",
  "status": "completed",
  "duration_seconds": 45,
  "purpose": "appointment_reminder",
  "summary": "Patient confirmed appointment for May 20 at 9:30 AM with Dr. Garcia.",
  "transcript": [
    { "role": "agent", "message": "Hi Maria, this is a reminder about your appointment..." },
    { "role": "user", "message": "Yes, I'll be there. Thank you!" }
  ],
  "patient_phone": "+34612345678"
}

Note The transcript may take 30-60 seconds to become available after the call ends. Poll until status is "completed" and transcript is populated. If you provided a callback_url, the transcript and summary are included in the callback POST automatically.

Callback Payload

If you provided a callback_url, MedSync POSTs when the call completes:

{
  "call_sid": "CA1234567890abcdef",
  "status": "completed",
  "duration_seconds": 45,
  "purpose": "appointment_reminder",
  "summary": "Patient confirmed appointment for May 20 at 9:30 AM.",
  "patient_phone": "+34612345678",
  "patient_name": "Maria Lopez"
}

Usage & Billing

GET /v1/usage?days=30

curl "https://api.gomedsync.com/v1/usage?days=30" \
  -H "X-API-Key: your_api_key"

{
  "client_id": "your_client_id",
  "period_days": 30,
  "services": {
    "transcription": {
      "requests": 142,
      "total_duration_seconds": 28400
    },
    "whatsapp": {
      "requests": 890,
      "total_duration_seconds": 0
    },
    "agent_call": {
      "requests": 56,
      "total_duration_seconds": 2520
    }
  }
}

Rate Limits

Plan	Requests / min
Starter	10
Professional	50
Enterprise	500

Rate-limited responses return 429 with a Retry-After header.

Error Handling

All errors return JSON:

{
  "error": "Description of what went wrong"
}

Status	Meaning
`401`	Missing or invalid API key
`413`	Audio file too large (max 150 MB)
`422`	Invalid parameters
`429`	Rate limit exceeded
`500`	Internal error (transcription or AI service failure)

Supported Languages

Deepgram Nova-2 supports 30+ languages. Most commonly used with MedSync:

Code	Language	Transcription	Agent Calls	WhatsApp Bot
`en`	English	Yes	Yes	Yes
`es`	Spanish	Yes	Yes	Yes
`ca`	Catalan	Yes	Yes	Yes
`fr`	French	Yes	Yes	Yes
`pt`	Portuguese	Yes	Yes	Yes
`de`	German	Yes	Yes	Yes
`it`	Italian	Yes	Yes	Yes

The clinical note, agent call script, and WhatsApp bot replies all use the same language as specified in the request.