openapi: 3.2.0
info:
  title: SERVICE Claims API
  description: ''
  termsOfService: http://lynx-fh.com
  license:
    name: LynxFH
    url: http://lynx-fh.com
  version: <Insert version with key 'api.service.ver' within application.properties>
servers:
- url: https://sandbox.lynx-fh.co
security:
- bearerAuth: []
tags:
- name: Claims
paths:
  /claims/member/claim:
    put:
      tags:
      - Claims
      summary: Update a Claim
      description: 'API that allows a client to update certain elements of an already existing member claim.

        Only claims in the Submitted, PendingReview or NeedsReview statuses are able to be updated.'
      operationId: updateClaim
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PutMemberClaimRequest'
                file:
                  type: string
                  format: binary
                  description: upload receipt
              required:
              - data
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistClaimsResponse'
        '400':
          description: 'Bad request.

            - GBL-250: Unable to update member claim in current status

            - GBL-338: Sum of claim detail amounts does not match claim amount

            - GBL-278: Expense date cannot be a future date

            - GBL-279: Invalid claim amount

            - GBL-239: Claim amount exceeds available balance

            - GBL-275: Unsupported file type

            - GBL-276: File size exceeds maximum limit

            - GBL-277: Unable to validate file, please try again

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseResponse'
        '401':
          description: Not authorized
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseResponse'
    post:
      tags:
      - Claims
      summary: Create a Claim
      description: Allows a member to submit a Claim refund request for an out-of-pocket expense.
      operationId: createClaim
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PostMemberClaimRequest'
                file:
                  type: string
                  format: binary
                  description: upload receipt
              required:
              - data
              - file
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistClaimsResponse'
        '400':
          description: 'Bad request.

            - GBL-199: Member account has no effective date

            - GBL-200: Claims not allowed for future dated effective date

            - GBL-304: Service date is past the allowed reimbursement period

            - GBL-280: Claims cannot be submitted against an ADVISORY account

            - GBL-294: Claim reimbursement via ACH requires an external account

            - GBL-240: Cannot process ACH reimbursement, no linked external account

            - GBL-338: Sum of claim detail amounts does not match claim amount

            - GBL-278: Expense date cannot be a future date

            - GBL-279: Invalid claim amount

            - GBL-239: Claim amount exceeds available balance

            - GBL-275: Unsupported file type

            - GBL-276: File size exceeds maximum limit

            - GBL-277: Unable to validate file, please try again

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseResponse'
        '401':
          description: Not authorized
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseResponse'
  /claims/member/claim/detail:
    get:
      tags:
      - Claims
      summary: Member Claims Detail
      description: Retrieves details of a member claim for a given member
      operationId: memberClaimDetail
      parameters:
      - name: clientOrgName
        in: query
        description: The name of the client organization
        required: true
        schema:
          type: string
        example: Health_Plan_ABC_Division
      - name: clientMemberId
        in: query
        description: Unique client-side identifier for the member
        required: true
        schema:
          type: string
        example: 3f50436491
      - name: claimNumber
        in: query
        description: The claim number
        required: true
        schema:
          type: string
        example: C-1234
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetClaimDetailResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseResponse'
        '401':
          description: Not authorized
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseResponse'
  /claims/member/claim/list:
    get:
      tags:
      - Claims
      summary: Member Claims List
      description: Retrieves a list of all member claims for a given member
      operationId: memberClaims
      parameters:
      - name: clientOrgName
        in: query
        description: The name of the client organization
        required: true
        schema:
          type: string
        example: Health_Plan_ABC_Division
      - name: clientMemberId
        in: query
        description: Unique client-side identifier for the member
        required: false
        schema:
          type: string
        example: 3f50436491
      - name: claimStatus
        in: query
        description: The status of the claim
        required: false
        schema:
          type: string
          enum:
          - PendingReview
          - Approved
          - Rejected
          - NeedsReview
        example: NeedsReview
      - name: page
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 1
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 25
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetClaimsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseResponse'
        '401':
          description: Not authorized
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseResponse'
components:
  schemas:
    MemberBankAccountDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: UUID of the Member's external bank account
          example: 2aa614ba-5590-4c16-bdd0-3f03964ee274
      required:
      - id
    PersistClaimsResponse:
      type: object
      properties:
        claimNumber:
          type: string
          description: The claim number
          example: C-1234
        clientMemberId:
          type: string
          description: Unique client-side identifier for the member
          example: 3f50436491
      required:
      - claimNumber
      - clientMemberId
    GetClaimsResponse:
      type: object
      properties:
        clientOrg:
          $ref: '#/components/schemas/ClientOrgDto'
        memberClaims:
          type: array
          items:
            $ref: '#/components/schemas/MemberClaimDetailInfo'
    AiAdjudicationResultDTO:
      type: object
      properties:
        aiValidAmount:
          type: number
          description: Amount that the AI partner validated for the submitted claimdence.
          example: 10
        aiDenyReason:
          type: string
          description: Reason for the denial. Null if not denied.
          example: Silver AI did not recognize any eligible expenses on the receipt/invoice for this claim.
        aiRecommendation:
          type: string
          description: The AI'd recommendation for the claim.
          example: NeedsReview
        confidence:
          type: number
        suggestion:
          type: string
        flags:
          type: array
          items:
            type: string
        merchant:
          type: string
        expenseDate:
          type: string
          format: date-time
        claimAmount:
          type: number
        receiptTotal:
          type: number
        receiptMerchant:
          type: string
        receiptDate:
          type: string
          format: date-time
    MemberClaimDetailInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the claim
          example: 40cd232c-4b42-469c-81d1-d04bf3e95b98
        claimNumber:
          type: string
          description: The claim number
          example: C-1234
        memberAccount:
          $ref: '#/components/schemas/MemberAccountIdDto'
        reimbursementType:
          type: string
          description: ' Method of reimbursement (ACH or CHECK).'
          example: ACH
        status:
          type: string
          description: The status of the claim
          example: NeedsReview
        claimAmount:
          type: number
          description: Total amount of the claim
          example: 50
        approvedAmount:
          type: number
          description: The Approved Claim Amount
          example: 50
        expenseDate:
          type: string
          description: Date of Expense
          example: '2024-07-05'
        addDatetime:
          type: string
          description: Date and time of add
          example: '2024-07-05'
        aiRecommendation:
          type: string
          description: The AI'd recommendation for the claim.
          example: NeedsReview
        member:
          $ref: '#/components/schemas/MemberDto'
      required:
      - addDatetime
      - approvedAmount
      - claimAmount
      - claimNumber
      - expenseDate
      - id
      - memberAccount
      - reimbursementType
      - status
    ClientOrgDto:
      type: object
      properties:
        name:
          type: string
          description: The name of the client organization
          example: Health_Plan_ABC_Division
      required:
      - name
    BaseAddress:
      type: object
      properties:
        line1:
          type: string
          description: The first line of the address
          example: 10
        line2:
          type: string
          description: The (optional) second line of the address
          example: address line2
        city:
          type: string
          description: Address city
          example: Boston
        stateProvince:
          type: string
          description: 2-Character address state or province
          example: MA
        country:
          type: string
          description: Address country
          example: US
        postalCode:
          type: string
          description: Address zip code
          example: 02119
        postalCodeExtension:
          type: string
          description: Address zip code extension
          example: '0123'
      required:
      - city
      - country
      - line1
      - postalCode
      - stateProvince
    PostMemberClaimRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreateClaimRequestData'
        idempotency:
          $ref: '#/components/schemas/Idempotency'
          description: Unique identifier that represents the operation
          example: cf82639c-e3b6-4d51-9871-0e452a2b1566
      required:
      - data
      - idempotency
    MemberAccountDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the bank account
          example: 6ae73974-2bd1-0f0d-7316-bbfff8cdc91b
        type:
          type: string
          description: Type of account
          example: HSA
        availableAmount:
          type: number
          description: Available balance to spend for the account
          example: 50
      required:
      - availableAmount
      - id
      - type
    CreateClaimRequestData:
      type: object
      properties:
        clientOrg:
          $ref: '#/components/schemas/ClientOrgDto'
        member:
          $ref: '#/components/schemas/BaseMember'
        memberAccount:
          $ref: '#/components/schemas/MemberAccountIdDto'
        memberBankAccount:
          $ref: '#/components/schemas/MemberBankAccountDto'
        merchantName:
          type: string
          description: Name of the merchant related to the claim
          example: CVS Pharmacy, Boston MA
        description:
          type: string
          description: The short description for the claim
          example: Claim to reimburse the purchase of over the counter medicine
        expenseDate:
          type: string
          description: The date when the expense was incurred
          example: '2024-01-01'
        claimAmount:
          type: number
          description: Total amount of the claim
          example: 50
        reimbursementType:
          type: string
          description: Method of payment for Reimbursement (CHECK/ACH)
          example: CHECK
        category:
          type: string
          description: The category for the Claim
          enum:
          - OverTheCounter
          - Wellness
          - HealthyFood
          - RentPayment
          - UtilityPayment
          - MortgagePayment
          - Other
          - FitnessFacility
          - FitnessClass
          example: OverTheCounter
        items:
          type: array
          items:
            $ref: '#/components/schemas/MemberClaimItemDto'
        address:
          $ref: '#/components/schemas/BaseAddress'
        serviceType:
          type: string
      required:
      - claimAmount
      - clientOrg
      - expenseDate
      - member
      - memberAccount
      - reimbursementType
    ResponseException:
      type: object
      properties:
        errorCode:
          type: string
          description: The GBL error code that is populated when the exceptionSource is SYSTEM
        exceptionSource:
          type: string
          description: Characterizes the type of exception (JSON, SYSTEM, PARAMETER)
        exceptionMessage:
          type: string
          description: Additional information about the exception
    ExceptionBaseResponse:
      type: object
      properties:
        data:
          type: object
          description: 'null'
        exceptions:
          type: array
          items:
            $ref: '#/components/schemas/ResponseException'
    GetClaimDetailResponse:
      type: object
      properties:
        memberClaim:
          $ref: '#/components/schemas/MemberClaimDetailDto'
    MemberClaimsData:
      type: object
      properties:
        claimNumber:
          type: string
          description: The claim number
          example: C-1234
        member:
          $ref: '#/components/schemas/BaseMember'
        clientOrg:
          $ref: '#/components/schemas/ClientOrgDto'
        claimAmount:
          type: number
          description: Total amount of the claim
          example: 50
        expenseDate:
          type: string
          description: Date of Expense
          example: '2024-07-05'
        merchantName:
          type: string
          description: Name of the merchant related to the claim
          example: CVS Pharmacy, Boston MA
        category:
          type: string
          description: The category for the Claim
          enum:
          - OverTheCounter
          - Wellness
          - HealthyFood
          - RentPayment
          - UtilityPayment
          - MortgagePayment
          - Other
          - FitnessFacility
          - FitnessClass
          example: OverTheCounter
        description:
          type: string
          description: The short description for the claim
          example: Claim to reimburse the purchase of over the counter medicine
        items:
          type: array
          items:
            $ref: '#/components/schemas/MemberClaimUpdateDto'
      required:
      - category
      - claimAmount
      - claimNumber
      - clientOrg
      - description
      - expenseDate
      - member
      - merchantName
    Idempotency:
      type: object
      properties:
        idempotencyKey:
          type: string
          description: Unique identifier that represents the operation
          example: cf82639c-e3b6-4d51-9871-0e452a2b1566
    MemberAccountIdDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the bank account
          example: 6ae73974-2bd1-0f0d-7316-bbfff8cdc91b
      required:
      - id
    MemberClaimDetailDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the claim
          example: 40cd232c-4b42-469c-81d1-d04bf3e95b98
        claimNumber:
          type: string
          description: The claim number
          example: C-1234
        memberAccount:
          $ref: '#/components/schemas/MemberAccountDto'
        memberBankAccount:
          $ref: '#/components/schemas/MemberBankAccountDto'
        status:
          type: string
          description: The status of the claim
          example: NeedsReview
        claimAmount:
          type: number
          description: Total amount of the claim
          example: 50
        approvedAmount:
          type: number
          description: The Approved Claim Amount
          example: 50
        expenseDate:
          type: string
          description: Date of Expense
          example: '2024-07-05'
        statusReason:
          type: string
          description: Reason for the current status of the claim
          example: Reimburse OTC medicine
        reimbursementType:
          type: string
          description: ' Method of reimbursement (ACH or CHECK).'
          example: ACH
        merchantName:
          type: string
          description: Name of the merchant related to the claim
          example: CVS Pharmacy, Boston MA
        addDateTime:
          type: string
          description: Date and time of add
          example: '2023-04-24 18:20:12.629221'
        category:
          type: string
          description: The category for the Claim
          enum:
          - OverTheCounter
          - Wellness
          - HealthyFood
          - RentPayment
          - UtilityPayment
          - MortgagePayment
          - Other
          - FitnessFacility
          - FitnessClass
          example: OverTheCounter
        description:
          type: string
          description: The short description for the claim
          example: Claim to reimburse the purchase of over the counter medicine
        items:
          type: array
          items:
            $ref: '#/components/schemas/ClaimDetailItem'
        receipt:
          $ref: '#/components/schemas/ReceiptDto'
        member:
          $ref: '#/components/schemas/MemberDto'
        aiAdjudicationResult:
          $ref: '#/components/schemas/AiAdjudicationResultDTO'
      required:
      - addDateTime
      - approvedAmount
      - claimAmount
      - claimNumber
      - expenseDate
      - id
      - memberAccount
      - reimbursementType
      - status
      - statusReason
    PutMemberClaimRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MemberClaimsData'
        idempotency:
          $ref: '#/components/schemas/Idempotency'
          description: Unique identifier that represents the operation
          example: cf82639c-e3b6-4d51-9871-0e452a2b1566
      required:
      - data
      - idempotency
    ReceiptDto:
      type: object
      properties:
        receiptId:
          type: string
          description: The ID of the receipt
          example: R-1234
        receiptUrl:
          type: string
          description: The ID of the receipt
          example: R-1234
      required:
      - receiptId
      - receiptUrl
    MemberClaimItemDto:
      type: object
      properties:
        itemDescription:
          type: string
          description: Description of the item or service. e.g. Tums, Teeth Cleaning
          example: Tylenol
        amount:
          type: number
          description: The cost of the individual item.
          example: 10
      required:
      - amount
      - itemDescription
    MemberClaimUpdateDto:
      type: object
      properties:
        itemDescription:
          type: string
          description: Description of the item or service. e.g. Tums, Teeth Cleaning
          example: Tylenol
        amount:
          type: number
          description: The cost of the individual item.
          example: 10
        id:
          type: string
          format: uuid
          description: ID of the existing item detail. Omit for new items.
          example: 2efe0ba7-9e84-44d1-9c5a-d9cb2d64bbee
      required:
      - amount
      - itemDescription
    BaseMember:
      type: object
      properties:
        clientMemberId:
          type: string
          description: Unique client-side identifier for the member
          example: 3f50436491
      required:
      - clientMemberId
    ClaimDetailItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the claim detail record
          example: 914f6a4b-2da0-4223-86c3-0ec2ffb86865
        itemDescription:
          type: string
          description: Text description of the item or service
          example: Tums
        amount:
          type: number
          description: Amount for the individual item
          example: 40
    MemberDto:
      type: object
      properties:
        clientMemberId:
          type: string
          description: Unique client-side identifier for the member
          example: 3f50436491
        firstName:
          type: string
          description: First name
          example: John
        lastName:
          type: string
          description: Last name
          example: Smith
      required:
      - clientMemberId
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: searched
  source: https://docs.lynx-fh.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.lynx-fh.com/reference/createclaim-1.md
  - https://docs.lynx-fh.com/reference/memberclaimdetail-1.md
  - https://docs.lynx-fh.com/reference/memberclaims-1.md
  - https://docs.lynx-fh.com/reference/updateclaim-1.md
  merge:
    pages: 4
    deduped: 17
    conflicts_kept_first: 0