# 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:


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

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

Successful response:


```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 2. Use the Token

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


```http
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:


```http
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](http://hl7.org/fhir/R4/).

### Example Code

JavaScript/Node.js example using fetch:


```javascript
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:


```python
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()
```