openapi: 3.2.0
info:
  title: Real Provider Access Provider Access Bulk Member Match API
  description: FHIR Provider Access APIs
  version: 1.0.0
servers:
- url: https://sandbox-apigw.optum.com
tags:
- name: ProviderAccessBulkMemberMatch
paths:
  /oihub/fhirprovideraccess/v1/R4/{payerId}/{lob}/Group/$bulk-member-match:
    post:
      operationId: bulkMemberMatch
      tags:
      - ProviderAccessBulkMemberMatch
      security:
      - oAuth:
        - read_healthcheck
      parameters:
      - name: payerId
        in: path
        required: true
        schema:
          type: string
          example: '87726'
      - name: lob
        in: path
        required: true
        schema:
          type: string
          example: bh
      - name: x-optum-consumer-correlation-id
        in: header
        schema:
          type: string
          description: Unique transaction identifier
          example: uuid-123
      - name: environment
        in: header
        schema:
          type: string
          description: Environment name
          example: sandbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMemberMatchRequest'
            example:
              resourceType: Parameters
              id: provider-bulk-member-match-in
              meta:
                profile:
                - http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/provider-parameters-multi-member-match-bundle-in
              parameter:
              - name: MembersToMatch
                part:
                - name: MemberPatient
                  resource:
                    resourceType: Patient
                    id: patient-provider-1
                    text:
                      status: generated
                      div: <div xmlns="http://www.w3.org/1999/xhtml">Patient firstName lastName</div>
                    identifier:
                    - type:
                        coding:
                        - system: http://terminology.hl7.org/CodeSystem/v2-0203
                          code: MB
                      system: http://example.org/provider-emr/identifiers/patient
                      value: EMR-98765
                      assigner:
                        display: Provider 1 EMR System
                    name:
                    - use: official
                      family: Person
                      given:
                      - givenName
                      - givenName2
                    gender: female
                    birthDate: '1974-12-25'
                - name: CoverageToMatch
                  resource:
                    resourceType: Coverage
                    id: coverage-provider-1
                    text:
                      status: generated
                      div: <div xmlns="http://www.w3.org/1999/xhtml">Coverage information from insurance card</div>
                    identifier:
                    - type:
                        coding:
                        - system: http://terminology.hl7.org/CodeSystem/v2-0203
                          code: MB
                      system: http://example.org/health-plan
                      value: HP-12345678
                    status: active
                    subscriberId: SUB-987654321
                    beneficiary:
                      reference: Patient/patient-provider-1
                    relationship:
                      coding:
                      - system: http://terminology.hl7.org/CodeSystem/subscriber-relationship
                        code: self
                    period:
                      start: '2024-01-01'
                      end: '2024-12-31'
                    payor:
                    - identifier:
                        system: http://hl7.org/fhir/sid/us-npi
                        value: '1234567890'
                      display: Example Health Plan
                    class:
                    - type:
                        coding:
                        - system: http://terminology.hl7.org/CodeSystem/coverage-class
                          code: group
                      value: GRP-001
                    - type:
                        coding:
                        - system: http://terminology.hl7.org/CodeSystem/coverage-class
                          code: plan
                      value: PLAN-GOLD
                - name: Consent
                  resource:
                    resourceType: Consent
                    id: consent-provider-1
                    text:
                      status: generated
                      div: <div xmlns="http://www.w3.org/1999/xhtml">Provider attestation to treatment relationship</div>
                    status: active
                    scope:
                      coding:
                      - system: http://terminology.hl7.org/CodeSystem/consentscope
                        code: treatment
                    category:
                    - coding:
                      - system: http://terminology.hl7.org/CodeSystem/v3-ActCode
                        code: IDSCL
                        display: Information Disclosure
                    - coding:
                      - system: http://loinc.org
                        code: 64292-6
                        display: Release of information consent
                    patient:
                      reference: Patient/patient-provider-1
                    dateTime: '2024-11-14T10:30:00Z'
                    performer:
                    - reference: Practitioner/4
                      display: Dr. Susan Smith
                    sourceReference:
                      reference: DocumentReference/provider-attestation-doc-1
                    policy:
                    - uri: https://example.org/provider-attestation-policy
                    verification:
                    - verified: true
                      verifiedWith:
                        reference: Patient/patient-provider-1
                      verificationDate: '2024-11-14T10:30:00Z'
                    provision:
                      type: permit
                      period:
                        start: '2024-01-15'
                      actor:
                      - role:
                          coding:
                          - system: http://terminology.hl7.org/CodeSystem/v3-ParticipationType
                            code: IRCP
                        reference:
                          identifier:
                            system: http://hl7.org/fhir/sid/us-npi
                            value: '1982943213'
                          display: Dr. Susan Smith
                      - role:
                          coding:
                          - system: http://terminology.hl7.org/CodeSystem/v3-RoleClass
                            code: PROV
                        reference:
                          identifier:
                            system: http://hl7.org/fhir/sid/us-npi
                            value: '1982947230'
                          display: Provider 1
                      purpose:
                      - system: http://terminology.hl7.org/CodeSystem/v3-ActReason
                        code: TREAT
                      - system: http://terminology.hl7.org/CodeSystem/v3-ActReason
                        code: HPAYMT
                      - system: http://terminology.hl7.org/CodeSystem/v3-ActReason
                        code: HOPERAT
      responses:
        '200':
          description: Bulk member match response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkMemberMatchResponse'
              example:
                resourceType: Parameters
                id: provider-bulk-member-match-out
                meta:
                  profile:
                  - http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/provider-parameters-multi-member-match-bundle-out
                parameter:
                - name: MatchedMembers
                  resource:
                    resourceType: Group
                    id: provider-matched-group-001
                    text:
                      status: generated
                      div: <div xmlns="http://www.w3.org/1999/xhtml">Matched members group - members authorized for provider access</div>
                    contained:
                    - resourceType: Patient
                      id: provider-submitted-patient-1
                      identifier:
                      - type:
                          coding:
                          - system: http://terminology.hl7.org/CodeSystem/v2-0203
                            code: MR
                        system: http://example.org/provider-emr/identifiers/patient
                        value: EMR-98765
                        assigner:
                          display: Provider 1 EMR System
                      name:
                      - use: official
                        family: Person
                        given:
                        - givenName
                        - givenName2
                      gender: female
                      birthDate: '1974-12-25'
                    - resourceType: Patient
                      id: provider-submitted-patient-2
                      identifier:
                      - type:
                          coding:
                          - system: http://terminology.hl7.org/CodeSystem/v2-0203
                            code: MR
                        system: http://example.org/provider-emr/identifiers/patient
                        value: EMR-45678
                        assigner:
                          display: Provider 1 EMR System
                      name:
                      - use: official
                        family: Doe
                        given:
                        - John
                        - Michael
                      gender: male
                      birthDate: '1985-06-15'
                    identifier:
                    - system: http://hl7.org/fhir/sid/us-npi
                      value: '1982947230'
                      assigner:
                        display: Provider 1
                    type: person
                    actual: true
                    code:
                      coding:
                      - system: http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS
                        code: match
                        display: Matched
                    managingEntity:
                      identifier:
                        system: http://hl7.org/fhir/sid/us-npi
                        value: '1234567890'
                      display: Example Health Plan
                    characteristic:
                    - code:
                        coding:
                        - system: http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS
                          code: match
                          display: Matched
                      valueReference:
                        identifier:
                          system: http://hl7.org/fhir/sid/us-npi
                          value: '1982947230'
                        display: Provider 1
                      exclude: false
                      period:
                        start: '2024-11-14'
                    member:
                    - entity:
                        extension:
                        - url: http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters
                          valueReference:
                            reference: '#provider-submitted-patient-1'
                        reference: Patient/payer-patient-1001
                        display: GivenName LastName - Payer Record
                    - entity:
                        extension:
                        - url: http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters
                          valueReference:
                            reference: '#provider-submitted-patient-2'
                        reference: Patient/payer-patient-2002
                        display: John Michael Doe - Payer Record
                - name: NonMatchedMembers
                  resource:
                    resourceType: Group
                    id: provider-nomatch-group-001
                    text:
                      status: generated
                      div: <div xmlns="http://www.w3.org/1999/xhtml">Non-matched members group - members not found in payer system</div>
                    contained:
                    - resourceType: Patient
                      id: provider-submitted-patient-3
                      identifier:
                      - type:
                          coding:
                          - system: http://terminology.hl7.org/CodeSystem/v2-0203
                            code: MR
                        system: http://example.org/provider-emr/identifiers/patient
                        value: EMR-99999
                        assigner:
                          display: Provider 1 EMR System
                      name:
                      - use: official
                        family: Smith
                        given:
                        - GivenName
                        - GivenName2
                      gender: female
                      birthDate: '1990-03-20'
                    identifier:
                    - system: http://hl7.org/fhir/sid/us-npi
                      value: '1982947230'
                      assigner:
                        display: Provider 1
                    type: person
                    actual: true
                    code:
                      coding:
                      - system: http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS
                        code: nomatch
                        display: Not Matched
                    managingEntity:
                      identifier:
                        system: http://hl7.org/fhir/sid/us-npi
                        value: '1234567890'
                      display: Example Health Plan
                    member:
                    - entity:
                        extension:
                        - url: http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters
                          valueReference:
                            reference: '#provider-submitted-patient-3'
                        reference: '#provider-submitted-patient-3'
                        display: GivenName GivenName2 Smith - Not Found
                - name: ConsentConstrainedMembers
                  resource:
                    resourceType: Group
                    id: provider-consent-constraint-group-001
                    text:
                      status: generated
                      div: <div xmlns="http://www.w3.org/1999/xhtml">Consent-constrained members group - members who opted out of Provider Access API</div>
                    contained:
                    - resourceType: Patient
                      id: provider-submitted-patient-4
                      identifier:
                      - type:
                          coding:
                          - system: http://terminology.hl7.org/CodeSystem/v2-0203
                            code: MR
                        system: http://example.org/provider-emr/identifiers/patient
                        value: EMR-77777
                        assigner:
                          display: Provider 1 EMR System
                      name:
                      - use: official
                        family: Wilson
                        given:
                        - GivenName
                        - GivenName2
                      gender: male
                      birthDate: '1978-11-30'
                    identifier:
                    - system: http://hl7.org/fhir/sid/us-npi
                      value: '1982947230'
                      assigner:
                        display: Provider 1
                    type: person
                    actual: true
                    code:
                      coding:
                      - system: http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS
                        code: consentconstraint
                        display: Consent Constraint
                    managingEntity:
                      identifier:
                        system: http://hl7.org/fhir/sid/us-npi
                        value: '1234567890'
                      display: Example Health Plan
                    member:
                    - entity:
                        extension:
                        - url: http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters
                          valueReference:
                            reference: '#provider-submitted-patient-4'
                        reference: '#provider-submitted-patient-4'
                        display: GivenName GivenName2 Wilson - Opted Out
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                message: Bad Request
                statusCode: 400
        '401':
          description: UnAuthorized
          content:
            application/json:
              example:
                message: UnAuthorized
                statusCode: 401
        '406':
          description: Not Acceptable
          content:
            application/json:
              example:
                message: Not Acceptable
                statusCode: 406
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                message: Internal server error
                statusCode: 500
components:
  schemas:
    Patient:
      type: object
      properties:
        resourceType:
          type: string
          example: Patient
        id:
          type: string
        text:
          $ref: '#/components/schemas/Narrative'
        identifier:
          type: array
          items:
            $ref: '#/components/schemas/IdentifierWithType'
        name:
          type: array
          items:
            $ref: '#/components/schemas/HumanName'
        gender:
          type: string
        birthDate:
          type: string
    Characteristic:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CodeableConcept'
        valueReference:
          $ref: '#/components/schemas/Reference'
        exclude:
          type: boolean
        period:
          $ref: '#/components/schemas/Period'
    Verification:
      type: object
      properties:
        verified:
          type: boolean
        verifiedWith:
          $ref: '#/components/schemas/Reference'
        verificationDate:
          type: string
    GroupMember:
      type: object
      properties:
        entity:
          type: object
          properties:
            reference:
              type: string
            display:
              type: string
            extension:
              type: array
              items:
                $ref: '#/components/schemas/Extension'
    Meta:
      type: object
      properties:
        profile:
          type: array
          items:
            type: string
    Extension:
      type: object
      properties:
        url:
          type: string
        valueReference:
          $ref: '#/components/schemas/Reference'
    Coverage:
      type: object
      properties:
        resourceType:
          type: string
        id:
          type: string
        text:
          $ref: '#/components/schemas/Narrative'
        identifier:
          type: array
          items:
            $ref: '#/components/schemas/IdentifierWithType'
        status:
          type: string
        subscriberId:
          type: string
        beneficiary:
          $ref: '#/components/schemas/Reference'
        relationship:
          $ref: '#/components/schemas/CodeableConcept'
        period:
          $ref: '#/components/schemas/Period'
        payor:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        class:
          type: array
          items:
            $ref: '#/components/schemas/CoverageClass'
    Consent:
      type: object
      properties:
        resourceType:
          type: string
        id:
          type: string
        text:
          $ref: '#/components/schemas/Narrative'
        status:
          type: string
        scope:
          $ref: '#/components/schemas/CodeableConcept'
        category:
          type: array
          items:
            $ref: '#/components/schemas/CodeableConcept'
        patient:
          $ref: '#/components/schemas/Reference'
        dateTime:
          type: string
        performer:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        sourceReference:
          $ref: '#/components/schemas/Reference'
        policy:
          type: array
          items:
            type: object
            properties:
              uri:
                type: string
        verification:
          type: array
          items:
            $ref: '#/components/schemas/Verification'
        provision:
          $ref: '#/components/schemas/Provision'
    CoverageClass:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CodeableConcept'
        value:
          type: string
    CodeableConcept:
      type: object
      properties:
        coding:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
    HumanName:
      type: object
      properties:
        use:
          type: string
        family:
          type: string
        given:
          type: array
          items:
            type: string
    Narrative:
      type: object
      properties:
        status:
          type: string
        div:
          type: string
    Period:
      type: object
      properties:
        start:
          type: string
        end:
          type: string
    Reference:
      type: object
      properties:
        reference:
          type: string
        display:
          type: string
        identifier:
          $ref: '#/components/schemas/Identifier'
    Provision:
      type: object
      properties:
        type:
          type: string
        period:
          $ref: '#/components/schemas/Period'
        actor:
          type: array
          items:
            $ref: '#/components/schemas/ProvisionActor'
        purpose:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
    ResponseParameter:
      type: object
      description: Response parameter containing Group
      properties:
        name:
          type: string
          enum:
          - MatchedMembers
          - NonMatchedMembers
          - ConsentConstrainedMembers
        resource:
          $ref: '#/components/schemas/Group'
    ParameterPart:
      type: object
      description: Nested part representing Patient/Coverage/Consent
      properties:
        name:
          type: string
          enum:
          - MemberPatient
          - CoverageToMatch
          - Consent
        resource:
          oneOf:
          - $ref: '#/components/schemas/Patient'
          - $ref: '#/components/schemas/Coverage'
          - $ref: '#/components/schemas/Consent'
    Identifier:
      type: object
      properties:
        system:
          type: string
        value:
          type: string
    ProvisionActor:
      type: object
      properties:
        role:
          $ref: '#/components/schemas/CodeableConcept'
        reference:
          $ref: '#/components/schemas/Reference'
    BulkMemberMatchRequest:
      type: object
      description: FHIR Parameters request for bulk member match
      properties:
        resourceType:
          type: string
          example: Parameters
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        parameter:
          type: array
          items:
            $ref: '#/components/schemas/Parameter'
    Parameter:
      type: object
      description: Input parameter entry
      properties:
        name:
          type: string
        part:
          type: array
          items:
            $ref: '#/components/schemas/ParameterPart'
    Group:
      type: object
      description: FHIR Group resource used for match result
      properties:
        resourceType:
          type: string
          example: Group
        id:
          type: string
        text:
          $ref: '#/components/schemas/Narrative'
        contained:
          type: array
          items:
            $ref: '#/components/schemas/Patient'
        identifier:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
        type:
          type: string
          example: person
        actual:
          type: boolean
          example: true
        code:
          $ref: '#/components/schemas/CodeableConcept'
        managingEntity:
          $ref: '#/components/schemas/Reference'
        characteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
        member:
          type: array
          items:
            $ref: '#/components/schemas/GroupMember'
    BulkMemberMatchResponse:
      type: object
      description: FHIR Parameters response containing grouped match results
      properties:
        resourceType:
          type: string
          example: Parameters
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        parameter:
          type: array
          items:
            $ref: '#/components/schemas/ResponseParameter'
    IdentifierWithType:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CodeableConcept'
        system:
          type: string
        value:
          type: string
        assigner:
          type: object
          properties:
            display:
              type: string
    Coding:
      type: object
      properties:
        system:
          type: string
        code:
          type: string
        display:
          type: string
  securitySchemes:
    oAuth:
      type: oauth2
      description: This API uses OAuth 2 with the client_credentials grant flow.
      flows:
        clientCredentials:
          tokenUrl: /apip/auth/v2/token
          scopes:
            read_txn: read transactions
            create_txn: submit a new transaction request
            read_coveragediscovery: read coverage discovery tasks
            create_coveragediscovery: submit a new coverage discovery task
            read_healthcheck: check the status of the system
x-readme:
  explorer-enabled: true
  proxy-enabled: true