API reference — FHIR R4

Standards-based access
to your clinic's data.

The TeleClinicOS API is a FHIR R4-compliant REST API. Authentication uses OAuth 2.0 with SMART on FHIR scopes. All endpoints require TLS 1.3. PHI access is logged to your clinic's immutable audit trail.

https://api.teleclinicos.com/fhir/r4FHIR R4SMART on FHIR

Authentication

OAuth 2.0 + SMART on FHIR

Use the authorization code flow to obtain a short-lived access token. Include the token as a Bearer credential on every request. Tokens expire after 15 minutes; use the refresh token to rotate.

1 — Authorization requestStep 1

GET https://auth.teleclinicos.com/oauth2/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.example.com%2Fcallback
  &scope=openid+fhirUser+patient%2F*.read+patient%2F*.write
  &state=RANDOM_STATE_STRING
  &aud=https%3A%2F%2Fapi.teleclinicos.com%2Ffhir%2Fr4

2 — Exchange code for tokenStep 2

curl -X POST https://auth.teleclinicos.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_REDIRECT" \
  -d "redirect_uri=https://yourapp.example.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

# Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "8xLOxBtZp8",
  "scope": "openid fhirUser patient/*.read patient/*.write",
  "patient": "pat-00a1b2c3d4e5"
}

3 — Authenticated requestStep 3

curl https://api.teleclinicos.com/fhir/r4/Patient/pat-00a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept: application/fhir+json"

FHIR endpoints

Supported resources

GET

/fhir/r4/Patient

Search patients by name, DOB, MRN

GET

/fhir/r4/Patient/:id

Fetch a single patient record

POST

/fhir/r4/Patient

Create a new patient

PUT

/fhir/r4/Patient/:id

Update patient demographics

GET

/fhir/r4/Appointment

Search appointments by date, provider, patient

POST

/fhir/r4/Appointment

Book a new appointment

PUT

/fhir/r4/Appointment/:id

Reschedule or cancel appointment

GET

/fhir/r4/Encounter

List encounters for a patient

POST

/fhir/r4/Encounter

Open a new encounter (session start)

GET

/fhir/r4/DocumentReference

Fetch SOAP notes for an encounter

POST

/fhir/r4/DocumentReference

Submit a signed SOAP note

GET

/fhir/r4/Observation

PHQ-9, GAD-7, vitals by patient/date

POST

/fhir/r4/Observation

Record a clinical observation

GET

/fhir/r4/MedicationRequest

Active prescriptions for a patient

GET

/fhir/r4/Practitioner/:id

Fetch provider profile

GET

/fhir/r4/metadata

CapabilityStatement (FHIR conformance)

FHIR resources — examples

Patient

GET /fhir/r4/Patient/pat-00a1b2c3d4e5200 OK

{
  "resourceType": "Patient",
  "id": "pat-00a1b2c3d4e5",
  "meta": {
    "versionId": "3",
    "lastUpdated": "2026-04-13T08:30:00Z",
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
    ]
  },
  "identifier": [{
    "system": "https://api.teleclinicos.com/ns/patient-id",
    "value": "pat-00a1b2c3d4e5"
  }],
  "name": [{
    "use": "official",
    "family": "Reyes",
    "given": ["Maria", "Elena"]
  }],
  "gender": "female",
  "birthDate": "1988-03-14",
  "address": [{
    "use": "home",
    "line": ["342 Haight St"],
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "US"
  }]
}

Webhooks

Event-driven integration

Subscribe to clinic events via webhooks. Payloads are signed with HMAC-SHA256 using your webhook secret. Verify the X-TeleClinic-Signature header on every delivery.

Available events

appointment.bookedNew appointment created

appointment.cancelledAppointment cancelled or rescheduled

encounter.startedVideo session joined by provider

encounter.endedVideo session ended

document.signedProvider e-signed a SOAP note

patient.createdNew patient record created

claim.submittedInsurance claim submitted

payment.receivedCash-pay or copay payment received

Error handling