Skip to content
Last updated

Getting Started with HeyDonto API

Welcome to HeyDonto API documentation. This guide will help you get started with using our APIs.

Overview

HeyDonto provides three main APIs:

  1. HeyDonto Core API: Main application API for managing dental practices, appointments, and services
  2. FHIR R4 API: Healthcare data API following the FHIR R4 standard
  3. Authentication API: Handles user management and authentication

All APIs use JWT (JSON Web Token) authentication and are available in both staging and production environments.

Base URLs

Staging: https://api-staging.heydonto.com
Production: https://api.heydonto.com

We recommend testing your integration in the staging environment before moving to production.

Authentication

All APIs require authentication using JWT bearer tokens. Follow these steps to authenticate:

1. Generate an Authentication Token

Make a POST request to the login endpoint:

POST /auth/login
Content-Type: application/json

{
    "email": "your-email@example.com",
    "password": "your-password"
}

Successful response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

2. Use the Token

Include the token in the Authorization header for all subsequent requests:

GET /api/endpoint
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Token Management

  • Tokens are valid for 24 hours
  • Store tokens securely
  • Do not share tokens across applications
  • Regenerate tokens when expired

API Structure

HeyDonto Core API

Manages dental practice operations:

  • Appointment Types
  • Brands
  • Dental Practices
  • Dental Services
  • Organizations
  • Practice Management Systems
  • Sites
  • Assistants
  • Periomeasure

Example request:

GET /dental-practices
Authorization: Bearer your-token-here

FHIR Resources

The HeyDonto FHIR API implements the following FHIR R4 resources. Each resource is available at /fhir/{resource-name} with full CRUD operations and history tracking.

Administrative Resources

  • Account: Financial accounts, balance, and charges
  • Organization: Healthcare providers, insurers, and departments
  • Patient: Demographics and other patient administrative information
  • Practitioner: Healthcare providers' demographic and administrative information
  • PractitionerRole: Roles and specialties of practitioners at organizations
  • Location: Physical locations where services are provided
  • HealthcareService: Services provided at a location/organization

Clinical Resources

  • AllergyIntolerance: Allergies and intolerances
  • Condition: Problems, diagnoses, and health concerns
  • Procedure: Actions taken for patient
  • Observation: Measurements and simple assertions
  • DiagnosticReport: Diagnostic test reports and results
  • CarePlan: Healthcare plans and sets of actions
  • CareTeam: Group of practitioners caring for a patient
  • Goal: Desired outcomes
  • NutritionOrder: Diet and nutritional requirements

Scheduling Resources

  • Appointment: Healthcare appointments
  • AppointmentResponse: Responses to appointment requests
  • Schedule: Available time slots
  • Slot: Time slots where appointments can be booked

Medications

  • Medication: Details about medications
  • MedicationRequest: Prescriptions and medication orders
  • MedicationDispense: Dispensing of medications
  • MedicationAdministration: Administration of medications
  • MedicationStatement: Record of medication usage
  • MedicationKnowledge: Drug information and knowledge

Diagnostics & Investigations

  • ImagingStudy: Medical imaging studies
  • Media: Images, videos, and audio
  • Specimen: Physical samples
  • BodyStructure: Body sites and structures

Documents & Lists

  • DocumentReference: References to documents
  • DocumentManifest: Sets of documents
  • List: General-purpose list of resources
  • Composition: Composition of healthcare documents

Care Provision

  • ServiceRequest: Orders and requests for services
  • Task: Work items or actions
  • Communication: Record of communication events
  • CommunicationRequest: Requests for communication
  • DeviceRequest: Orders for medical devices

Financial Resources

  • Claim: Healthcare financial claim
  • ClaimResponse: Adjudication response to claims
  • Coverage: Insurance or payment coverage
  • ExplanationOfBenefit: Explanation of benefits
  • PaymentNotice: Payment notifications
  • Invoice: Billable services

Clinical Research

  • ResearchStudy: Research studies
  • ResearchSubject: Subject participation in research
  • Evidence: Evidence for clinical recommendations
  • RiskAssessment: Potential outcomes assessment

Medications & Substances

  • Substance: Physical materials
  • SubstanceSpecification: Detailed substance definitions
  • MedicinalProduct: Regulated medication products
  • MedicinalProductIngredient: Ingredients in medicinal products

Public Health & Quality

  • Measure: Quality measures and metrics
  • MeasureReport: Results of quality measures
  • ImmunizationRecommendation: Vaccine recommendations
  • Immunization: Vaccine administration records

Security & Privacy

  • AuditEvent: Security audit logs
  • Consent: Privacy consents
  • Provenance: Resource origin and changes
  • VerificationResult: Verification results

Foundation Resources

  • Binary: Raw data content
  • Bundle: Collection of resources
  • Parameters: Operation parameters
  • OperationOutcome: Operation results/errors

Conformance Resources

  • CapabilityStatement: API capabilities
  • StructureDefinition: Resource structure definitions
  • ValueSet: Value set definitions
  • CodeSystem: Code system definitions
  • SearchParameter: Search parameter definitions

Additional Resources

  • DetectedIssue: Clinical issues
  • Device: Medical devices
  • DeviceDefinition: Device definitions
  • DeviceMetric: Device measurements
  • DeviceUseStatement: Record of device usage
  • EndPoint: Network service endpoints
  • Flag: Clinical flags
  • Group: Groups of resources
  • Person: Person demographics
  • RelatedPerson: People involved in care
  • Questionnaire: Structured data collection
  • QuestionnaireResponse: Answers to questionnaires

Each resource supports the following operations:

  • GET /{resource}: Search/read resources
  • POST /{resource}: Create new resource
  • GET /{resource}/{id}: Read specific resource
  • PUT /{resource}/{id}: Update specific resource
  • DELETE /{resource}/{id}: Delete specific resource
  • GET /{resource}/{id}/history: Get resource version history

For detailed information about each resource's structure and usage, refer to the FHIR R4 specification.

Example Code

JavaScript/Node.js example using fetch:

async function getAuthToken(email, password) {
  const response = await fetch("https://api-staging.heydonto.com/auth/login", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email, password }),
  });

  return await response.json();
}

async function makeApiRequest(token, endpoint) {
  const response = await fetch(`https://api-staging.heydonto.com${endpoint}`, {
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  });

  return await response.json();
}

Python example using requests:

import requests

def get_auth_token(email, password):
    response = requests.post(
        'https://api-staging.heydonto.com/auth/login',
        json={'email': email, 'password': password}
    )
    return response.json()

def make_api_request(token, endpoint):
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    response = requests.get(
        f'https://api-staging.heydonto.com{endpoint}',
        headers=headers
    )
    return response.json()
Previous page
Next page