Integrate Vantra without guesswork

Use Vantra as a governed clinic backend: send leads into the shared pipeline, reconcile appointments, ingest FHIR R4 observations for Sentinel, or embed the agent on a clinic website. Every REST request uses a revocable, scoped per-clinic API key; managed hospital devices use the separately documented Vantra Bridge runtime.

REST API v13 production endpoints

Manage API keys Start integrating

Base URL: https://www.vantra.xyz; OpenAPI JSON ↗
Authentication: Bearer vk_…
Format: JSON over HTTPS

From key to first response

Three steps, one read-only verification call. No SDK is required.

1
Create a named API key
A clinic manager can create and revoke keys in the dashboard. Use one key per integration and environment, selecting only the endpoint scopes it needs, so access can be rotated without disrupting anything else.
Manage API keys →
2
Store it as a server-side secret
The full key is shown once. Put it in your secret manager or deployment environment; never ship it in browser, mobile-app, or widget code.
.env
VANTRA_BASE_URL=https://www.vantra.xyz VANTRA_API_KEY=vk_your_key_here
3
Verify the connection
Start with the read-only appointments endpoint. A valid key returns a 200 response, even when the appointments array is empty.
bash
curl "$VANTRA_BASE_URL/api/public/v1/appointments" \ -H "Authorization: Bearer $VANTRA_API_KEY" \ -H "Accept: application/json"

One key, one clinic

API keys are server-side credentials. Name them by integration and environment, and rotate them independently.

Send Authorization: Bearer vk_… on every REST request. The key selects the clinic; never send a clinic_id in the body as an authorization mechanism.
Keys are created by clinic managers in API & Webchat → Public API keys. Plaintext is shown once; only a SHA-256 hash is stored.
Use a separate, clearly named key per integration and environment. Revocation is immediate and remains visible in the tamper-evident audit trail.
Keys authorize only their selected scopes. Hospital Bridge/device scopes additionally require a credential-bound Bridge ID and are not available to legacy unbound keys.

Operation	Allowance
Lead writes	Default 120 requests / minute / key
Appointment reads	Default 60 requests / minute / key
FHIR observation ingestion	Default 600 requests / minute / key
Managed Bridge endpoints	120–1,200 requests / minute / key, depending on route
Enterprise plans	Negotiated per-key overrides available — contact Vantra

Public REST API

All endpoints use the same bearer key and return JSON. Paths below are relative to the production base URL.

Create or update a lead

POST/api/public/v1/leads

Default 120 requests / minute / key

Push a lead into the same pipeline used by the dashboard, dossier and reactivation tools. Leads are keyed by normalized phone number, making retries idempotent. This endpoint never queues a call; outbound actions remain behind the clinic's own controls.

Parameter	In	Type	Required	Details
`phone`	Body	string	Yes	E.164 strongly preferred (+905551112233); other formats receive formatting normalization but cannot be country-resolved.
`name`	Body	string	No	Full name.
`email`	Body	string	No	Email address.
`note`	Body	string	No	Lead summary; truncated to 500 characters.

Request

curl -X POST https://www.vantra.xyz/api/public/v1/leads \
  -H "Authorization: Bearer $VANTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+905551112233","name":"Jane Doe","note":"Asked about whitening"}'

200 response

{ "ok": true }

List appointments

GET/api/public/v1/appointments

Default 60 requests / minute / key

Read appointment rows for reconciliation with an external system of record. The window defaults to the next 14 days, is capped at 92 days, and returns at most 1,000 rows. Patient fields are included because the caller is the clinic's authorized system; treat them as PHI.

Parameter	In	Type	Required	Details
`from`	Query	ISO datetime	No	Window start. Defaults to the current time.
`to`	Query	ISO datetime	No	Window end. Defaults to from + 14 days; windows over 92 days are clamped.

Request

curl "https://www.vantra.xyz/api/public/v1/appointments?from=2026-07-01T00:00:00Z&to=2026-07-14T00:00:00Z" \
  -H "Authorization: Bearer $VANTRA_API_KEY"

200 response

{
  "clinic_id": "clinic_123",
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-07-14T00:00:00.000Z",
  "appointments": [
    {
      "id": "appt_1",
      "start": "2026-07-02T09:00:00.000Z",
      "end": "2026-07-02T09:30:00.000Z",
      "status": "scheduled",
      "service": "Cleaning",
      "patient_name": "Jane Doe",
      "patient_phone": "+905551112233",
      "doctor_id": "doc_7",
      "source": "ai_whatsapp"
    }
  ]
}

Ingest FHIR observations

POST/api/public/v1/observations

Default 600 requests / minute / key

Send one HL7 FHIR R4 Observation or a Bundle of up to 500 entries from an HMIS or bedside integration. Vantra normalizes units, deduplicates by Observation.id, scores NEWS2, and can raise a governed deterioration alert.

Requires Sentinel to be enabled for the clinic; otherwise the API returns 403.

Parameter	In	Type	Required	Details
`resource`	Body	FHIR R4 Observation \| Bundle	Yes	Send the FHIR resource as JSON. Bundles are limited to 500 entries. Stable, non-empty Observation ids enable safe automatic retries.
`encounter_id`	Query	string	No	External non-PHI encounter reference for a single-patient push. Vantra hashes it and returns a stable opaque encounterId.
`facility_id`	Query	string	No	Facility ID stamped on newly created encounters.

Request

curl -X POST "https://www.vantra.xyz/api/public/v1/observations?encounter_id=enc_123" \
  -H "Authorization: Bearer $VANTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType":"Observation",
    "id":"obs-1",
    "status":"final",
    "code":{"coding":[{"system":"http://loinc.org","code":"8867-4"}]},
    "subject":{"reference":"Patient/mrn-88231"},
    "effectiveDateTime":"2026-07-04T10:00:00Z",
    "valueQuantity":{"value":88,"unit":"/min"}
  }'

200 response

{
  "ok": true,
  "recorded": 1,
  "duplicates": 0,
  "skipped": [],
  "encounters": [
    {
      "encounterId": "pt_a1b2c3d4e5f60718293a4b5c",
      "severity": "normal",
      "news2": 0,
      "alerted": false,
      "missing": ["resp_rate", "spo2", "systolic_bp", "temperature", "consciousness", "supplemental_o2"]
    }
  ]
}

Errors and retries

Non-2xx responses return JSON with an error field. Treat 429 and 5xx responses as transient; do not retry validation or authorization errors unchanged.

Status	Meaning	What to do
400	Invalid request	Check the JSON body, phone number, or appointment window.
401	Unauthorized	Check that the bearer key is complete, active, scoped for the route, and sent from the server. Bridge calls also require the bound x-vantra-bridge-id.
403	Feature unavailable	The key is valid, but the clinic has not enabled the requested product, such as Sentinel.
413	Payload too large	Split FHIR Bundles into batches of at most 500 entries.
429	Rate limited	Retry with exponential backoff and jitter.
500	Server error	Retry reads and lead upserts. Retry FHIR writes automatically only when every Observation has a stable, non-empty id.

TypeScript SDK

SDK 0.2.0, Partner preview

A fully typed, zero-dependency TypeScript client covers leads, appointments, and FHIR observations with bearer auth, timeouts, idempotency-aware transient retries, and typed errors. It is not yet published on the public npm registry. Use the REST examples today, or contact the integrations team for the current partner-preview distribution.

Preview API shape

import { VantraClient, VantraRateLimitError } from "@vantra/sdk";

const vantra = new VantraClient({ apiKey: process.env.VANTRA_API_KEY! });

await vantra.leads.create({ phone: "+905551112233", name: "Jane Doe" });
const { appointments } = await vantra.appointments.list();
const result = await vantra.observations.ingest({ resource: fhirBundle });

try {
  await vantra.appointments.list();
} catch (error) {
  if (error instanceof VantraRateLimitError) {
    // Apply your queue's retry policy.
  }
}

Request SDK preview access →

Embeddable agent widget

Embed the clinic's real text agent with one script tag. The widget uses the same orchestrator, tools, and safety gates as Vantra's messaging channels. A clinic manager can enable it under API & Webchat, choose the launcher colour, and copy the clinic-specific snippet. The widget key is a public identifier, not an API credential, so the snippet is safe for browser code.

HTML

<script
  src="https://www.vantra.xyz/webchat-widget.js"
  data-vantra-widget="wgt_your_widget_key"
  async
></script>

Versioning and support

The /api/public/v1/* contract is additive-only: new optional fields may appear without a version change, while breaking changes ship under a new version path. The documented managed Hospital Bridge routes are consumed through the versioned on-site Bridge runtime. The /webchat-widget.js loader is the current widget integration; its /api/webchat/* transport and legacy /api/widget/* compatibility routes are internal and are not SDK surface.

Need a product enabled, higher limits, or an integration review? Email info@vantra.xyz or contact the team.

Appointment and observation payloads may contain patient-identifying data. Use a signed agreement, least-privilege infrastructure, encrypted transport and storage, and your organization's PHI controls.

VANTRA

Loading this page

Ingest FHIR observations

POST/api/public/v1/observations

Default 600 requests / minute / key

Requires Sentinel to be enabled for the clinic; otherwise the API returns 403.

Parameter	In	Type	Required	Details
`resource`	Body	FHIR R4 Observation \| Bundle	Yes	Send the FHIR resource as JSON. Bundles are limited to 500 entries. Stable, non-empty Observation ids enable safe automatic retries.
`encounter_id`	Query	string	No	External non-PHI encounter reference for a single-patient push. Vantra hashes it and returns a stable opaque encounterId.
`facility_id`	Query	string	No	Facility ID stamped on newly created encounters.

Request

curl -X POST "https://www.vantra.xyz/api/public/v1/observations?encounter_id=enc_123" \
  -H "Authorization: Bearer $VANTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType":"Observation",
    "id":"obs-1",
    "status":"final",
    "code":{"coding":[{"system":"http://loinc.org","code":"8867-4"}]},
    "subject":{"reference":"Patient/mrn-88231"},
    "effectiveDateTime":"2026-07-04T10:00:00Z",
    "valueQuantity":{"value":88,"unit":"/min"}
  }'

200 response

{
  "ok": true,
  "recorded": 1,
  "duplicates": 0,
  "skipped": [],
  "encounters": [
    {
      "encounterId": "pt_a1b2c3d4e5f60718293a4b5c",
      "severity": "normal",
      "news2": 0,
      "alerted": false,
      "missing": ["resp_rate", "spo2", "systolic_bp", "temperature", "consciousness", "supplemental_o2"]
    }
  ]
}

From key to first response

Create a named API key

Store it as a server-side secret

Verify the connection

One key, one clinic

Public REST API

Create or update a lead

List appointments

Ingest FHIR observations

Errors and retries

TypeScript SDK

Embeddable agent widget

Versioning and support

From key to first response

Create a named API key

Store it as a server-side secret

Verify the connection

One key, one clinic

Public REST API

Create or update a lead

List appointments

Ingest FHIR observations

Errors and retries

TypeScript SDK

Embeddable agent widget

Versioning and support