Talkya API · HIPAA REST API for AI Receptionist, EHR, CRM, Telehealth

Quickstart

Base URL, versions, and environments

Talkya uses HTTPS, JSON request bodies, JSON responses, cursor pagination, idempotency keys for writes, and signed webhooks. The public docs use realistic endpoint shapes; production credentials are issued per workspace after approval.

Base URLhttps://api.talkya.ai/v1

Formatapplication/json

AuthBearer token / OAuth2

WebhooksHMAC-SHA256

curl https://api.talkya.ai/v1/patients?limit=25 \
  -H "Authorization: Bearer $TALKYA_API_KEY" \
  -H "Talkya-Workspace: ws_truebliss" \
  -H "Accept: application/json"

Authentication

Every API key belongs to one Talkya workspace and has explicit scopes. Use separate keys for production, sandbox, server-to-server jobs, and local testing. Do not put API keys inside browser JavaScript or public mobile apps.

POST/oauth/token

Exchange a client credential or authorization code for a short-lived access token.

{
  "grant_type": "client_credentials",
  "client_id": "client_...",
  "client_secret": "secret_...",
  "scope": "patients:read leads:write calls:read"
}

Plain English: an API key is the password a server uses to talk to Talkya. A scope is the permission list that says what that key can read or change.

EHR / EMR endpoints

Use the patient and encounter APIs when an integration needs clinical context, visit notes, documents, prescriptions, lab orders, or audit-friendly record updates.

GET/patientsSearch patients by name, date of birth, MRN, phone, email, or tag.

POST/patientsCreate a patient after intake consent is captured.

POST/encountersCreate an encounter linked to patient, provider, location, and visit type.

POST/notesAttach SOAP, progress, procedure, or telehealth notes to an encounter.

POST/documentsAttach consent forms, lab reports, PDFs, photos, or imported records.

POST/encounters

{
  "patient_id": "pat_9a82",
  "provider_id": "usr_114",
  "type": "telehealth_follow_up",
  "reason": "GLP-1 refill review",
  "source": "ai_receptionist",
  "metadata": {
    "call_id": "call_7fd2",
    "crm_deal_id": "deal_42"
  }
}

CRM endpoints

The CRM API keeps marketing leads, consults, packages, revenue opportunities, reminders, and staff ownership connected to the same patient or contact timeline.

POST/leadsCreate a lead with source, intent, consent, and requested service.

GET/contacts/{contact_id}Read patient/contact profile, stage, tags, and open tasks.

POST/dealsTrack consult value, stage, owner, package, and probability.

POST/tasksCreate follow-up tasks for coordinators, front desk, providers, or VAs.

const lead = await fetch("https://api.talkya.ai/v1/leads", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TALKYA_API_KEY}`,
    "Talkya-Workspace": "ws_truebliss",
    "Idempotency-Key": "lead-form-2026-05-18-001",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    source: "website",
    service_interest: "Botox consult",
    patient: { name: "Maria Lopez", phone: "+13055550123" },
    consent: { sms: true, marketing: true }
  })
});

AI Receptionist endpoints

Use these endpoints to inspect calls, transcripts, detected intents, appointment outcomes, and staff handoffs. They are useful for client dashboards and weekly performance reports.

GET/callsList calls by status, source, intent, campaign, date range, or outcome.

GET/calls/{call_id}/transcriptFetch timestamped transcript, speaker labels, summary, and next steps.

POST/receptionist/routing-rulesUpdate greeting, escalation, booking, language, and after-hours behavior.

Telehealth endpoints

Create visits from the chart or CRM, invite patients and providers, then attach transcripts, recordings, and draft notes back to the encounter.

POST/telehealth/visitsCreate a visit and receive patient/provider join links.

GET/telehealth/visits/{visit_id}Read visit status, attendance, duration, recording state, and linked encounter.

POST/telehealth/visits/{visit_id}/notesGenerate or attach a draft note for clinical review.

Messenger endpoints

Talkya Messenger is the secure staff communication layer. Use it for channel messages, patient-aware handoffs, bot replies, voice/video events, and files.

POST/channelsCreate a workspace channel for front desk, providers, billing, or a client team.

POST/messagesSend text, attachments, bot replies, or staff alerts.

POST/filesUpload a file and attach it to a patient, message, encounter, or task.

OpenClaw workflow endpoints

OpenClaw is the workflow and tool-routing layer. It decides whether a request should answer, call a tool, create a task, write CRM context, open an EHR handoff, or alert a human.

POST/agents/runsStart an agent run with workspace context and allowed tools.

GET/agents/runs/{run_id}Inspect status, tool calls, handoffs, and final outcome.

POST/agents/handoffsCreate a staff handoff from an AI workflow.

Hermes communication endpoints

Hermes moves communication events through calls, messages, webhooks, staff alerts, and workspace routes. It is the layer that helps Talkya keep patient communication from becoming scattered.

POST/hermes/eventsPublish an internal communication event for routing and audit.

GET/hermes/routesList configured routes for calls, forms, bots, webhooks, and staff alerts.

POST/hermes/routes/testTest where a sample event would be delivered before going live.

Webhooks

Webhooks notify your system when a patient, lead, call, note, visit, message, agent run, or Hermes event changes. Use signature verification before trusting payloads.

patient.created lead.created deal.stage_changed receptionist.call.completed appointment.booked encounter.closed note.signed telehealth.visit.completed message.created openclaw.run.completed hermes.event.routed task.followup_due

Talkya-Signature: t=1779110400,v1=5d8c...
Talkya-Webhook-Id: wh_8d21

{
  "id": "evt_01hx",
  "type": "receptionist.call.completed",
  "created_at": "2026-05-18T14:00:00Z",
  "workspace_id": "ws_truebliss",
  "data": {
    "call_id": "call_7fd2",
    "intent": "new_consult",
    "outcome": "appointment_booked"
  }
}

Errors, pagination, and rate limits

List endpoints use cursor pagination. Write endpoints accept an Idempotency-Key header so retries do not create duplicate patients, leads, tasks, or encounters. Rate limits are workspace-scoped and increase after production review.

200Successful request.

201Created a resource.

400Invalid request body or missing field.

401Missing or invalid token.

403Token does not have the required scope.

404Resource was not found in this workspace.

409Duplicate idempotency key or conflicting state.

429Rate limit exceeded; retry after the provided delay.

Need production API access?

Send the workspace name, integration goal, PHI requirements, required scopes, expected traffic, and whether you need a BAA. Talkya will issue sandbox credentials first, then production credentials after review.

Email [email protected]

Build clinical workflows on top of Talkya.