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()
 
Next page