ModMed Charges/Financial API

Charges/Financial details

OpenAPI Specification

modernizing-medicine-charges-financial-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: EMA Proprietary Charges/Financial API
  contact:
    email: ankit.srivastava@modmed.com
  version: 3.4.3_FINAL
  description: 'The EMA Proprietary FHIR API provides programmatic access to ModMed EMA clinical and practice-management data using FHIR R4-style resources under `/fhir/v2`.


    This documentation targets the **public sandbox** (`stage.ema-api.com`).


    **Authentication.** Two mechanisms are supported during the current migration: the **legacy OAuth2 `password` grant** (being sunset) and the **new OAuth2 `client_credentials`** flow (recommended for new integrations) — see the **Authentication** guide. Every API call also requires the `x-api-key` header.'
servers:
- url: https://stage.ema-api.com/ema-dev/firm/apiportal/ema
security:
- BearerAuth: []
  ApiKeyAuth: []
tags:
- name: Charges/Financial
  description: Charges/Financial details
paths:
  /fhir/v2/Account:
    get:
      tags:
      - Charges/Financial
      summary: Search for a patient’s account
      parameters:
      - name: patient
        in: query
        description: Account resources can be searched by patient id, which is a required field.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIR-JSON-RESOURCE'
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/FHIR-XML-RESOURCE'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /fhir/v2/ChargeItem/CHG|{id}:
    get:
      tags:
      - Charges/Financial
      summary: Get a specific ChargeItem
      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'
              example:
                resourceType: ChargeItem
                id: CHG|1722
                extension:
                - url: financialTransaction
                  extension:
                  - url: financialTransactionId
                    valueString: CHG|1722
                  - url: transactionStatus
                    valueString: Charged
                  - url: attendingProviderId
                    valueString: '8944076359'
                  - url: locationId
                    valueString: '826'
                  - url: businessUnitId
                    valueString: '325678903'
                  - url: totalCost
                    valueMoney:
                      value: 83.63
                      currency: USD
                  - url: financialTransactionDetail
                    extension:
                    - url: performingProviderId
                      valueString: '8944076359'
                    - url: quantity
                      valueDecimal: 1
                    - url: description
                      valueString: Test
                    - url: postingDate
                      valueDateTime: '2025-06-18T00:00:00+00:00'
                    - url: procedureDetail
                      extension:
                      - url: procedureDetailId
                        valueString: CHG|1722
                status: billable
                subject:
                  reference: https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Patient/375535
                  display: https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Patient/375535
                occurrenceDateTime: '2025-06-18T00:00:00+00:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /fhir/v2/ChargeItem/INBOUND|{id}:
    get:
      tags:
      - Charges/Financial
      summary: Get a specific inbound Charge for a Practice
      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'
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/FHIR-XML-RESOURCE'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /fhir/v2/ChargeItem/INBOUND:
    get:
      tags:
      - Charges/Financial
      summary: Get all Inbound Charges for a Practice
      responses:
        '200':
          description: Success
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIR-JSON-RESOURCE'
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/FHIR-XML-RESOURCE'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /fhir/v2/ChargeItem:
    get:
      tags:
      - Charges/Financial
      summary: Get All ChargeItems for a Practice
      parameters:
      - name: _count
        in: query
        description: Number of records to use as the page size for paginated search. The maximum page size for this Resource is 50
        required: false
        schema:
          type: string
      - name: context
        in: query
        description: 'Encounter reference url in format : /resoucrename/id or id.'
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: Page to be used for paginated search
        required: false
        schema:
          type: string
      - name: patient
        in: query
        description: 'Patient reference url in format : /resoucrename/id or id.'
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: Charge Item Type Search Parameter.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIR-JSON-RESOURCE'
              example:
                resourceType: Bundle
                id: a7f5fd64-b419-4a5d-8f08-70a8159c1feb
                meta:
                  lastUpdated: '2026-06-25T14:56:09.966+00:00'
                type: searchset
                total: 1
                link:
                - relation: self
                  url: https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/ChargeItem?_count=2
                - relation: next
                  url: https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/ChargeItem?_count=2&page=2
                entry:
                - fullUrl: https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/ChargeItem/CHG%7C1722
                  resource:
                    resourceType: ChargeItem
                    id: CHG|1722
                    extension:
                    - url: financialTransaction
                      extension:
                      - url: financialTransactionId
                        valueString: CHG|1722
                      - url: transactionStatus
                        valueString: Charged
                      - url: attendingProviderId
                        valueString: '8944076359'
                      - url: locationId
                        valueString: '826'
                      - url: businessUnitId
                        valueString: '325678903'
                      - url: totalCost
                        valueMoney:
                          value: 83.63
                          currency: USD
                      - url: financialTransactionDetail
                        extension:
                        - url: performingProviderId
                          valueString: '8944076359'
                        - url: quantity
                          valueDecimal: 1
                        - url: description
                          valueString: Test
                        - url: postingDate
                          valueDateTime: '2025-06-18T00:00:00+00:00'
                        - url: procedureDetail
                          extension:
                          - url: procedureDetailId
                            valueString: CHG|1722
                    status: billable
                    subject:
                      reference: https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Patient/375535
                      display: https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Patient/375535
                    occurrenceDateTime: '2025-06-18T00:00:00+00:00'
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/FHIR-XML-RESOURCE'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
      - Charges/Financial
      summary: Create Charges Into ModMedPM
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/FHIR-JSON-RESOURCE'
            examples:
              single-procedure-with-modifier:
                summary: Single procedure, fee schedule billing (most common) — laterality modifier
                value:
                  resourceType: ChargeItem
                  extension:
                  - url: financialTransaction
                    extension:
                    - url: attendingProviderId
                      valueString: '450861'
                    - url: locationId
                      valueString: 112416FAC000000001
                    - url: transactionId
                      valueString: SYN-010
                    - url: sendingFacility
                      valueString: chargetest
                    - url: receivingFacility
                      valueString: apiportal
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '11102'
                          display: Tangential biopsy of skin, single lesion
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: TANGENTIAL BIOPSY SKIN 1ST LESION
                      - url: postingDate
                        valueDateTime: '2026-06-29T14:30:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T14:30:00-05:00'
                          end: '2026-06-29T14:30:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: procedureCodeModifier
                        valueString: LT
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L57.0
                            display: Actinic keratosis due to ultraviolet radiation
                  status: billable
                  subject:
                    reference: Patient/450858
                  context:
                    reference: Encounter/362378
                  occurrenceDateTime: '2026-06-29T14:30:00-05:00'
                  reason:
                  - coding:
                    - system: I10
                      code: L57.0
                      display: Actinic keratosis due to ultraviolet radiation
                  supportingInformation:
                  - reference: Coverage/286892
              office-visit-with-ordering-provider:
                summary: E&M + procedure with ordering provider, fee schedule billing — multiple diagnoses, modifiers 25 and 59
                value:
                  resourceType: ChargeItem
                  extension:
                  - url: financialTransaction
                    extension:
                    - url: attendingProviderId
                      valueString: '450861'
                    - url: locationId
                      valueString: 112416FAC000000001
                    - url: transactionId
                      valueString: SYN-011
                    - url: sendingFacility
                      valueString: chargetest
                    - url: receivingFacility
                      valueString: apiportal
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '99213'
                          display: Office or other outpatient visit, established patient, moderate complexity
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: OFFICE VISIT ESTABLISHED PATIENT
                      - url: postingDate
                        valueDateTime: '2026-06-29T09:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T09:00:00-05:00'
                          end: '2026-06-29T09:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: procedureCodeModifier
                        valueString: '25'
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L57.0
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: D22.5
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: orderingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '11102'
                          display: Tangential biopsy of skin, single lesion
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: TANGENTIAL BIOPSY SKIN 1ST LESION
                      - url: postingDate
                        valueDateTime: '2026-06-29T09:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T09:00:00-05:00'
                          end: '2026-06-29T09:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: procedureCodeModifier
                        valueString: '59'
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: D22.5
                  status: billable
                  subject:
                    reference: Patient/450858
                  context:
                    reference: Encounter/362378
                  occurrenceDateTime: '2026-06-29T09:00:00-05:00'
                  reason:
                  - coding:
                    - system: I10
                      code: L57.0
                  - coding:
                    - system: I10
                      code: D22.5
                  - coding:
                    - system: I10
                      code: L82.1
                  supportingInformation:
                  - reference: Coverage/286892
              multi-procedure-with-business-unit:
                summary: Multiple procedures with businessUnitId, fee schedule billing — multiple diagnoses per line
                value:
                  resourceType: ChargeItem
                  extension:
                  - url: financialTransaction
                    extension:
                    - url: attendingProviderId
                      valueString: '450861'
                    - url: locationId
                      valueString: 112416FAC000000001
                    - url: businessUnitId
                      valueString: '1'
                    - url: transactionId
                      valueString: SYN-012
                    - url: sendingFacility
                      valueString: chargetest
                    - url: receivingFacility
                      valueString: apiportal
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '99213'
                          display: Office or other outpatient visit, established patient, moderate complexity
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: OFFICE VISIT ESTABLISHED PATIENT
                      - url: postingDate
                        valueDateTime: '2026-06-29T10:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T10:00:00-05:00'
                          end: '2026-06-29T10:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: procedureCodeModifier
                        valueString: '25'
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L57.0
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L82.1
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '17000'
                          display: Destruction of premalignant lesion, first lesion
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: DESTRUCTION PREMALIGNANT LESION 1ST
                      - url: postingDate
                        valueDateTime: '2026-06-29T10:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T10:00:00-05:00'
                          end: '2026-06-29T10:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L57.0
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L82.1
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '17003'
                          display: Destruction of premalignant lesion, each additional lesion
                      - url: quantity
                        valueDecimal: 4
                      - url: description
                        valueString: DESTRUCTION PREMALIGNANT LESION ADDL
                      - url: postingDate
                        valueDateTime: '2026-06-29T10:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T10:00:00-05:00'
                          end: '2026-06-29T10:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L57.0
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L82.1
                  status: billable
                  subject:
                    reference: Patient/450858
                  context:
                    reference: Encounter/362378
                  occurrenceDateTime: '2026-06-29T10:00:00-05:00'
                  reason:
                  - coding:
                    - system: I10
                      code: L57.0
                  - coding:
                    - system: I10
                      code: L82.1
              pathology-multi-line:
                summary: 'Pathology: explicit cost fields (totalCost/unitCost) — multiple service lines, per-line diagnosis'
                value:
                  resourceType: ChargeItem
                  extension:
                  - url: financialTransaction
                    extension:
                    - url: attendingProviderId
                      valueString: '450861'
                    - url: locationId
                      valueString: 112416FAC000000001
                    - url: transactionId
                      valueString: SYN-002
                    - url: sendingFacility
                      valueString: chargetest
                    - url: receivingFacility
                      valueString: apiportal
                    - url: totalCost
                      valueMoney:
                        value: 415.42
                        currency: USD
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '88305'
                          display: Tissue exam by pathologist
                      - url: unitCost
                        valueMoney:
                          value: 87.24
                          currency: USD
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: TISSUE EXAM BY PATHOLOGIST
                      - url: postingDate
                        valueDateTime: '2026-06-29T10:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T10:00:00-05:00'
                          end: '2026-06-29T10:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: L57.0
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '88305'
                          display: Tissue exam by pathologist
                      - url: unitCost
                        valueMoney:
                          value: 87.24
                          currency: USD
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: TISSUE EXAM BY PATHOLOGIST
                      - url: postingDate
                        valueDateTime: '2026-06-29T10:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T10:00:00-05:00'
                          end: '2026-06-29T10:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: D22.5
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '88342'
                          display: Immunohistochemistry, initial antibody staining procedure
                      - url: unitCost
                        valueMoney:
                          value: 129.85
                          currency: USD
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: IMMUNOHISTO ANTB 1ST STAIN
                      - url: postingDate
                        valueDateTime: '2026-06-29T10:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T10:00:00-05:00'
                          end: '2026-06-29T10:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: D22.5
                    - url: financialTransactionDetail
                      extension:
                      - url: performingProviderId
                        valueString: '450861'
                      - url: code
                        valueCoding:
                          system: CPT
                          code: '88341'
                          display: Immunohistochemistry, each additional single antibody staining procedure
                      - url: unitCost
                        valueMoney:
                          value: 111.09
                          currency: USD
                      - url: quantity
                        valueDecimal: 1
                      - url: description
                        valueString: IMMUNOHISTO ANTB ADDL SLIDE
                      - url: postingDate
                        valueDateTime: '2026-06-29T10:00:00-05:00'
                      - url: transactionPeriod
                        valuePeriod:
                          start: '2026-06-29T10:00:00-05:00'
                          end: '2026-06-29T10:00:00-05:00'
                      - url: transactionType
                        valueString: CG
                      - url: diagnosisDetail
                        extension:
                        - url: diagnosisCode
                          valueCoding:
                            system: I10
                            code: D22.5
                  status: billable
                  subject:
                    reference: Patient/450858
                  context:
                    reference: Encounter/362378
                  occurrenceDateTime: '2026-06-29T10:00:00-05:00'
                  reason:
                  - coding:
                    - system: I10
                      code: L57.0
                  - coding:
                    - system: I10
                      code: D22.5
        description: ChargeItem resource. The `extension.financialTransaction` block carries all billing data. See the named examples below for common submission patterns.
      responses:
        '200':
          description: Success
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIR-JSON-RESOURCE'
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/FHIR-XML-RESOURCE'
        '201':
          description: Created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIR-JSON-RESOURCE'
              example:
                resourceType: ChargeItem
                extension:
                - url: financialTransaction
                  extension:
                  - url: totalCost
                    valueMoney:
                      value: '123.00'
                      currency: USD
                  - url: attendingProviderId
                    valueString: EXAMPLE-ID
                  - url: locationId
          

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modernizing-medicine/refs/heads/main/openapi/modernizing-medicine-charges-financial-api-openapi.yml