ModMed Encounter API

openapi: 3.2.0
info:
  title: ModMed Certified Encounter API
  contact: {}
  version: 4.1-SNAPSHOT
  description: '**FHIR endpoints are customer-specific.** Each practice has its own Certified FHIR endpoint — browse the directory at https://mm-fhir-endpoint-display.prod.fhir.ema-api.com/. The server below (`https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4`) is a production **demonstration endpoint** for testing your integration; it behaves exactly like any practice''s endpoint. See the **Authentication** documentation for the OAuth 2.0 / SMART App Launch flow.'
servers:
- url: https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4
  description: EMA Certified FHIR API
  variables:
    firm:
      default: fhirmp
      description: Your firm subdomain (e.g. fhirmp, auraderm). Find yours at https://mm-fhir-endpoint-display.prod.fhir.ema-api.com/
security:
- smartOnFhir:
  - openid
  - fhirUser
  - profile
  - launch/patient
  - offline_access
  - patient/AllergyIntolerance.rs
  - patient/CarePlan.rs
  - patient/CareTeam.rs
  - patient/Condition.rs
  - patient/Coverage.rs
  - patient/Device.rs
  - patient/DiagnosticReport.rs
  - patient/DocumentReference.rs
  - patient/Encounter.rs
  - patient/Goal.rs
  - patient/Immunization.rs
  - patient/Location.rs
  - patient/Medication.rs
  - patient/MedicationRequest.rs
  - patient/Observation.rs
  - patient/Organization.rs
  - patient/Patient.rs
  - patient/Practitioner.rs
  - patient/PractitionerRole.rs
  - patient/Procedure.rs
  - patient/Provenance.rs
  - patient/RelatedPerson.rs
  - patient/ServiceRequest.rs
  - user/AllergyIntolerance.rs
  - user/CarePlan.rs
  - user/CareTeam.rs
  - user/Condition.rs
  - user/Coverage.rs
  - user/Device.rs
  - user/DiagnosticReport.rs
  - user/DocumentReference.rs
  - user/Encounter.rs
  - user/Goal.rs
  - user/Immunization.rs
  - user/Location.rs
  - user/Medication.rs
  - user/MedicationRequest.rs
  - user/Observation.rs
  - user/Organization.rs
  - user/Patient.rs
  - user/Practitioner.rs
  - user/PractitionerRole.rs
  - user/Procedure.rs
  - user/Provenance.rs
  - user/RelatedPerson.rs
  - user/ServiceRequest.rs
  - system/AllergyIntolerance.rs
  - system/CarePlan.rs
  - system/CareTeam.rs
  - system/Condition.rs
  - system/Coverage.rs
  - system/Device.rs
  - system/DiagnosticReport.rs
  - system/DocumentReference.rs
  - system/Encounter.rs
  - system/Goal.rs
  - system/Immunization.rs
  - system/Location.rs
  - system/Medication.rs
  - system/MedicationRequest.rs
  - system/Observation.rs
  - system/Organization.rs
  - system/Patient.rs
  - system/Practitioner.rs
  - system/PractitionerRole.rs
  - system/Procedure.rs
  - system/Provenance.rs
  - system/RelatedPerson.rs
  - system/ServiceRequest.rs
tags:
- name: Encounter
  description: 'The Encounter FHIR resource type<br/>Base profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter'
paths:
  /Encounter/{id}:
    get:
      tags:
      - Encounter
      summary: 'read-instance: Read Encounter instance'
      parameters:
      - name: id
        in: path
        description: The resource ID
        required: true
        style: simple
        schema:
          minimum: 1
          type: string
        example: '123'
      responses:
        '200':
          description: Success
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIR-JSON-RESOURCE'
              examples:
                ambulatory-new-patient-visit:
                  summary: Ambulatory new patient visit — CPT 99203, finished, with reasonCode text and reasonReference
                  value:
                    resourceType: Encounter
                    id: 1.120182.10.32975932
                    meta:
                      source: Organization/1.120182
                      profile:
                      - http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter
                    identifier:
                    - system: http://www.hl7.org/fhir/v2/0203/index.html#v2-0203-VN
                      value: 120182VIS000000955
                    status: finished
                    class:
                      system: http://terminology.hl7.org/CodeSystem/v3-ActCode
                      code: AMB
                      display: ambulatory
                    type:
                    - coding:
                      - system: http://www.ama-assn.org/go/cpt
                        code: '99203'
                        display: Office or other outpatient visit for the evaluation and management of a new patient, which requires a medically appropriate history and/or examination and low level of medical decision making. When using total time on the date of the encounter for code selection, 30 minutes must be met or exceeded.
                    subject:
                      reference: Patient/1.120182.1.17082675
                      type: Patient
                    participant:
                    - type:
                      - coding:
                        - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                          code: PPRF
                          display: primary performer
                      period:
                        start: '2025-03-03T13:32:19+00:00'
                        end: '2026-03-02T13:38:07+00:00'
                      individual:
                        reference: Practitioner/1.120182.2.17081470
                        type: Practitioner
                    - type:
                      - coding:
                        - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                          code: SPRF
                          display: secondary performer
                      period:
                        start: '2025-03-03T13:32:19+00:00'
                        end: '2026-03-02T13:38:07+00:00'
                      individual:
                        reference: Practitioner/1.120182.2.17081470
                        type: Practitioner
                    period:
                      start: '2025-03-03T13:32:19+00:00'
                      end: '2026-03-02T13:38:07+00:00'
                    reasonCode:
                    - text: Evaluation of Skin Lesion(s)
                    reasonReference:
                    - reference: Condition/1.120182.7.1.60732921
                      type: Condition
                    hospitalization:
                      dischargeDisposition:
                        coding:
                        - system: http://terminology.hl7.org/CodeSystem/discharge-disposition
                          code: oth
                          display: Other
                    location:
                    - location:
                        reference: Location/1.120182.14.5975
                        type: Location
                    serviceProvider:
                      reference: Organization/1.120182
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/FHIR-XML-RESOURCE'
  /Encounter:
    get:
      tags:
      - Encounter
      summary: 'search-type: Search for Encounter instances'
      description: This is a search type
      parameters:
      - name: _id
        in: query
        description: The ID of the resource
        required: false
        schema:
          type: string
      - name: class
        in: query
        description: Classification of patient encounter
        required: false
        schema:
          type: string
      - name: date
        in: query
        description: A date within the period the Encounter lasted
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: string
            format: date
      - name: identifier
        in: query
        description: Identifier(s) by which this encounter is known
        required: false
        schema:
          type: string
      - name: patient
        in: query
        description: The patient or group present at the encounter
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: planned | arrived | triaged | in-progress | onleave | finished | cancelled +
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: Specific type of encounter
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIR-JSON-RESOURCE'
              examples:
                encounter-bundle:
                  summary: 'All 4 encounters: 2 CPT-coded office visits (99203 new patient, 99213 established) and 2 SNOMED Consultation encounters across 3 practitioners'
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 4
                    link:
                    - relation: self
                      url: https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4/Encounter?patient=1.120182.1.17082675
                    entry:
                    - fullUrl: https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4/Encounter/1.120182.10.32975932
                      resource:
                        resourceType: Encounter
                        id: 1.120182.10.32975932
                        meta:
                          source: Organization/1.120182
                          profile:
                          - http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter
                        identifier:
                        - system: http://www.hl7.org/fhir/v2/0203/index.html#v2-0203-VN
                          value: 120182VIS000000955
                        status: finished
                        class:
                          system: http://terminology.hl7.org/CodeSystem/v3-ActCode
                          code: AMB
                          display: ambulatory
                        type:
                        - coding:
                          - system: http://www.ama-assn.org/go/cpt
                            code: '99203'
                            display: Office or other outpatient visit for the evaluation and management of a new patient, which requires a medically appropriate history and/or examination and low level of medical decision making. When using total time on the date of the encounter for code selection, 30 minutes must be met or exceeded.
                        subject:
                          reference: Patient/1.120182.1.17082675
                          type: Patient
                        participant:
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: PPRF
                              display: primary performer
                          period:
                            start: '2025-03-03T13:32:19+00:00'
                            end: '2026-03-02T13:38:07+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.17081470
                            type: Practitioner
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: SPRF
                              display: secondary performer
                          period:
                            start: '2025-03-03T13:32:19+00:00'
                            end: '2026-03-02T13:38:07+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.17081470
                            type: Practitioner
                        period:
                          start: '2025-03-03T13:32:19+00:00'
                          end: '2026-03-02T13:38:07+00:00'
                        reasonCode:
                        - text: Evaluation of Skin Lesion(s)
                        reasonReference:
                        - reference: Condition/1.120182.7.1.60732921
                          type: Condition
                        hospitalization:
                          dischargeDisposition:
                            coding:
                            - system: http://terminology.hl7.org/CodeSystem/discharge-disposition
                              code: oth
                              display: Other
                        location:
                        - location:
                            reference: Location/1.120182.14.5975
                            type: Location
                        serviceProvider:
                          reference: Organization/1.120182
                    - fullUrl: https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4/Encounter/1.120182.10.32976936
                      resource:
                        resourceType: Encounter
                        id: 1.120182.10.32976936
                        meta:
                          source: Organization/1.120182
                          profile:
                          - http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter
                        identifier:
                        - system: http://www.hl7.org/fhir/v2/0203/index.html#v2-0203-VN
                          value: 120182VIS000000956
                        status: finished
                        class:
                          system: http://terminology.hl7.org/CodeSystem/v3-ActCode
                          code: AMB
                          display: ambulatory
                        type:
                        - coding:
                          - system: http://www.ama-assn.org/go/cpt
                            code: '99213'
                            display: Office or other outpatient visit for the evaluation and management of an established patient, which requires a medically appropriate history and/or examination and low level of medical decision making. When using total time on the date of the encounter for code selection, 20 minutes must be met or exceeded.
                        subject:
                          reference: Patient/1.120182.1.17082675
                          type: Patient
                        participant:
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: PPRF
                              display: primary performer
                          period:
                            start: '2026-03-02T14:00:21+00:00'
                            end: '2026-03-02T14:02:35+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.17081470
                            type: Practitioner
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: SPRF
                              display: secondary performer
                          period:
                            start: '2026-03-02T14:00:21+00:00'
                            end: '2026-03-02T14:02:35+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.17081470
                            type: Practitioner
                        period:
                          start: '2026-03-02T14:00:21+00:00'
                          end: '2026-03-02T14:02:35+00:00'
                        reasonCode:
                        - text: Evaluation of Skin Lesion(s)
                        reasonReference:
                        - reference: Condition/1.120182.7.1.60734256
                          type: Condition
                        hospitalization:
                          dischargeDisposition:
                            coding:
                            - system: http://terminology.hl7.org/CodeSystem/discharge-disposition
                              code: oth
                              display: Other
                        location:
                        - location:
                            reference: Location/1.120182.14.5975
                            type: Location
                        serviceProvider:
                          reference: Organization/1.120182
                    - fullUrl: https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4/Encounter/1.120182.10.33611285
                      resource:
                        resourceType: Encounter
                        id: 1.120182.10.33611285
                        meta:
                          source: Organization/1.120182
                          profile:
                          - http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter
                        identifier:
                        - system: http://www.hl7.org/fhir/v2/0203/index.html#v2-0203-VN
                          value: 120182VIS000000957
                        status: finished
                        class:
                          system: http://terminology.hl7.org/CodeSystem/v3-ActCode
                          code: AMB
                          display: ambulatory
                        type:
                        - coding:
                          - system: http://snomed.info/sct
                            code: '11429006'
                            display: Consultation
                        subject:
                          reference: Patient/1.120182.1.17082675
                          type: Patient
                        participant:
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: PPRF
                              display: primary performer
                          period:
                            start: '2026-04-06T16:35:13+00:00'
                            end: '2026-04-06T17:51:51+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.14672596
                            type: Practitioner
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: SPRF
                              display: secondary performer
                          period:
                            start: '2026-04-06T16:35:13+00:00'
                            end: '2026-04-06T17:51:51+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.14672596
                            type: Practitioner
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: SPRF
                              display: secondary performer
                          period:
                            start: '2026-04-06T16:35:13+00:00'
                            end: '2026-04-06T17:51:51+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.17081470
                            type: Practitioner
                        period:
                          start: '2026-04-06T16:35:13+00:00'
                          end: '2026-04-06T17:51:51+00:00'
                        reasonReference:
                        - reference: Condition/1.120182.7.1.62507158
                          type: Condition
                        hospitalization:
                          dischargeDisposition:
                            coding:
                            - system: http://terminology.hl7.org/CodeSystem/discharge-disposition
                              code: oth
                              display: Other
                        location:
                        - location:
                            reference: Location/1.120182.14.5975
                            type: Location
                        serviceProvider:
                          reference: Organization/1.120182
                    - fullUrl: https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4/Encounter/1.120182.10.34997323
                      resource:
                        resourceType: Encounter
                        id: 1.120182.10.34997323
                        meta:
                          source: Organization/1.120182
                          profile:
                          - http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter
                        identifier:
                        - system: http://www.hl7.org/fhir/v2/0203/index.html#v2-0203-VN
                          value: 120182VIS000000960
                        status: finished
                        class:
                          system: http://terminology.hl7.org/CodeSystem/v3-ActCode
                          code: AMB
                          display: ambulatory
                        type:
                        - coding:
                          - system: http://snomed.info/sct
                            code: '11429006'
                            display: Consultation
                        subject:
                          reference: Patient/1.120182.1.17082675
                          type: Patient
                        participant:
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: PPRF
                              display: primary performer
                          period:
                            start: '2026-05-14T18:24:31+00:00'
                            end: '2026-05-14T18:27:41+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.14672591
                            type: Practitioner
                        - type:
                          - coding:
                            - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                              code: SPRF
                              display: secondary performer
                          period:
                            start: '2026-05-14T18:24:31+00:00'
                            end: '2026-05-14T18:27:41+00:00'
                          individual:
                            reference: Practitioner/1.120182.2.14672591
                            type: Practitioner
                        period:
                          start: '2026-05-14T18:24:31+00:00'
                          end: '2026-05-14T18:27:41+00:00'
                        reasonReference:
                        - reference: Condition/1.120182.7.1.64546691
                          type: Condition
                        hospitalization:
                          dischargeDisposition:
                            coding:
                            - system: http://terminology.hl7.org/CodeSystem/discharge-disposition
                              code: oth
                              display: Other
                        location:
                        - location:
                            reference: Location/1.120182.14.5975
                            type: Location
                        serviceProvider:
                          reference: Organization/1.120182
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/FHIR-XML-RESOURCE'
components:
  schemas:
    FHIR-XML-RESOURCE:
      type: object
      description: A FHIR resource
    FHIR-JSON-RESOURCE:
      type: object
      description: A FHIR resource
  securitySchemes:
    smartOnFhir:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4/auth/realms/fhir/protocol/openid-connect/auth
          tokenUrl: https://fhirmp.mmi.prod.fhir.ema-api.com/fhir/r4/auth/realms/fhir/protocol/openid-connect/token
          scopes:
            openid: OpenID Connect (auto-granted)
            fhirUser: FHIR reference to the authenticated practitioner
            profile: Standard OIDC profile claims
            launch/patient: Request patient context in the token
            offline_access: Request a long-lived refresh token
            patient/AllergyIntolerance.rs: Read/search AllergyIntolerance (patient context)
            patient/CarePlan.rs: Read/search CarePlan (patient context)
            patient/CareTeam.rs: Read/search CareTeam (patient context)
            patient/Condition.rs: Read/search Condition (patient context)
            patient/Coverage.rs: Read/search Coverage (patient context)
            patient/Device.rs: Read/search Device (patient context)
            patient/DiagnosticReport.rs: Read/search DiagnosticReport (patient context)
            patient/DocumentReference.rs: Read/search DocumentReference (patient context)
            patient/Encounter.rs: Read/search Encounter (patient context)
            patient/Goal.rs: Read/search Goal (patient context)
            patient/Immunization.rs: Read/search Immunization (patient context)
            patient/Location.rs: Read/search Location (patient context)
            patient/Medication.rs: Read/search Medication (patient context)
            patient/MedicationRequest.rs: Read/search MedicationRequest (patient context)
            patient/Observation.rs: Read/search Observation (patient context)
            patient/Organization.rs: Read/search Organization (patient context)
            patient/Patient.rs: Read/search Patient (patient context)
            patient/Practitioner.rs: Read/search Practitioner (patient context)
            patient/PractitionerRole.rs: Read/search PractitionerRole (patient context)
            patient/Procedure.rs: Read/search Procedure (patient context)
            patient/Provenance.rs: Read/search Provenance (patient context)
            patient/RelatedPerson.rs: Read/search RelatedPerson (patient context)
            patient/ServiceRequest.rs: Read/search ServiceRequest (patient context)
            user/AllergyIntolerance.rs: Read/search AllergyIntolerance (user context)
            user/CarePlan.rs: Read/search CarePlan (user context)
            user/CareTeam.rs: Read/search CareTeam (user context)
            user/Condition.rs: Read/search Condition (user context)
            user/Coverage.rs: Read/search Coverage (user context)
            user/Device.rs: Read/search Device (user context)
            user/DiagnosticReport.rs: Read/search DiagnosticReport (user context)
            user/DocumentReference.rs: Read/search DocumentReference (user context)
            user/Encounter.rs: Read/search Encounter (user context)
            user/Goal.rs: Read/search Goal (user context)
            user/Immunization.rs: Read/search Immunization (user context)
            user/Location.rs: Read/search Location (user context)
            user/Medication.rs: Read/search Medication (user context)
            user/MedicationRequest.rs: Read/search MedicationRequest (user context)
            user/Observation.rs: Read/search Observation (user context)
            user/Organization.rs: Read/search Organization (user context)
            user/Patient.rs: Read/search Patient (user context)
            user/Practitioner.rs: Read/search Practitioner (user context)
            user/PractitionerRole.rs: Read/search PractitionerRole (user context)
            user/Procedure.rs: Read/search Procedure (user context)
            user/Provenance.rs: Read/search Provenance (user context)
            user/RelatedPerson.rs: Read/search RelatedPerson (user context)
            user/ServiceRequest.rs: Read/search ServiceRequest (user context)
            system/AllergyIntolerance.rs: Read/search AllergyIntolerance (system/bulk context)
            system/CarePlan.rs: Read/search CarePlan (system/bulk context)
            system/CareTeam.rs: Read/search CareTeam (system/bulk context)
            system/Condition.rs: Read/search Condition (system/bulk context)
            system/Coverage.rs: Read/search Coverage (system/bulk context)
            system/Device.rs: Read/search Device (system/bulk context)
            system/DiagnosticReport.rs: Read/search DiagnosticReport (system/bulk context)
            system/DocumentReference.rs: Read/search DocumentReference (system/bulk context)
            system/Encounter.rs: Read/search Encounter (system/bulk context)
            system/Goal.rs: Read/search Goal (system/bulk context)
            system/Immunization.rs: Read/search Immunization (system/bulk context)
            system/Location.rs: Read/search Location (system/bulk context)
            system/Medication.rs: Read/search Medication (system/bulk context)
            system/MedicationRequest.rs: Read/search MedicationRequest (system/bulk context)
            system/Observation.rs: Read/search Observation (system/bulk context)
            system/Organization.rs: Read/search Organization (system/bulk context)
            system/Patient.rs: Read/search Patient (system/bulk context)
            system/Practitioner.rs: Read/search Practitioner (system/bulk context)
            system/PractitionerRole.rs: Read/search PractitionerRole (system/bulk context)
            system/Procedure.rs: Read/search Procedure (system/bulk context)
            system/Provenance.rs: Read/search Provenance (system/bulk context)
            system/RelatedPerson.rs: Read/search RelatedPerson (system/bulk context)
            system/ServiceRequest.rs: Read/search ServiceRequest (system/bulk context)