Voti Developer API

Base URL

Use versioned HTTPS endpoints only.

https://api.voti.ai/v1

Authentication

Voti uses invite-only API keys. An API key is a secret password for a partner system; it is scoped to one approved organization and to specific actions.

Authorization: Bearer voti_test_REDACTED
Authorization: Bearer voti_live_REDACTED

Use voti_test_ keys for sandbox/fake-data testing. Use voti_live_ keys only after Voti has approved production access and the required BAA evidence is recorded.

Do not send API keys in URLs, browser code, mobile apps, screenshots, or support tickets.

Patient External-ID Links

Integrations must link an external EHR or CRM patient ID to the matching Voti patient. This avoids unsafe matching by name or date of birth.

Method	Path	Use
`POST`	`/patients/link`	Create or update an external patient ID link.
`GET`	`/patients/external-link`	Check whether an external patient ID is linked.

curl https://api.voti.ai/v1/patients/link \
  -H "Authorization: Bearer voti_test_REDACTED" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-link-001" \
  -d '{
    "external_system": "demo_ehr",
    "external_patient_id": "ehr_demo_456",
    "patient_local_id": "local_pat_demo_123",
    "display_label": "Demo patient link"
  }'

Reviewed Clinical Notes

Voti only exposes reviewed note export payloads in v1. Raw audio is not exposed through this API.

Method	Path	Use
`GET`	`/clinical-notes`	Get a reviewed note by Voti note ID or external patient link.

curl "https://api.voti.ai/v1/clinical-notes?note_local_id=local_note_demo_123" \
  -H "Authorization: Bearer voti_test_REDACTED"

{
  "ok": true,
  "clinical_note": {
    "id": "note_demo_123",
    "patient_local_id": "local_pat_demo_123",
    "reviewed": true,
    "sections": {
      "subjective": "Demo patient reports improved sleep.",
      "objective": "Demo vitals stable.",
      "assessment": "Demo follow-up note for testing.",
      "plan": "Demo plan: continue current care plan."
    },
    "transcript": "Demo transcript text only."
  }
}

Webhooks

Keragon can subscribe to Voti events and receive signed HTTPS webhook payloads.

Event	When it fires
`clinical_note.reviewed`	A clinician reviewed a Voti note and it is ready for export.

Create a subscription

curl https://api.voti.ai/v1/webhooks \
  -H "Authorization: Bearer voti_test_REDACTED" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-webhook-001" \
  -d '{
    "url": "https://example.com/voti-webhook",
    "events": ["clinical_note.reviewed"]
  }'

Signature verification

Every webhook includes x-voti-event-id, x-voti-timestamp, and x-voti-signature. Verify the HMAC before trusting the body and reject old timestamps to reduce replay risk.

const signedPayload = `${timestamp}.${rawBody}`;
const expected = hmacSha256(webhookSigningSecret, signedPayload);
if (expected !== headerSignature) throw new Error("Invalid Voti webhook signature");

Admin Setup

Voti keys are not self-serve. After access approval, a Voti workspace admin creates a scoped sandbox key, rotates it if exposed, and revokes it when no longer needed.

Admin action	What it does	Why it matters
Create key	Issues a one-time `voti_test_` or `voti_live_` secret.	The real key is shown once; Convex stores only its hash.
Rotate key	Replaces the old secret for the same integration.	Use this after staff turnover, vendor changes, or suspected exposure.
Revoke key	Immediately disables a key.	Stops future API calls without deleting audit history.
Record Keragon BAA	Marks Keragon BAA evidence as `pending` or `signed`.	Production keys are blocked until signed evidence exists.

Sandbox keys can be used with fake data before the Keragon BAA is signed. Production keys require Voti HIPAA mode plus signed Keragon BAA evidence.

Security Model

API keys are hashed server-side and scoped by organization, environment, action, and expiration.
Production partner API calls are blocked unless Voti HIPAA mode and signed Keragon BAA evidence are present.
Write requests require an Idempotency-Key header so retries do not duplicate work.
Audit logs are designed to record access without putting PHI in log summaries.
Voti is BAA-backed and HIPAA-compliant for approved production customers; Voti does not claim government HIPAA certification.

Request Access

Partner API access is not self-serve. Contact Voti with the company name, use case, expected systems, security contact, and whether PHI will be involved.

Request Voti API access