Luma Health Patients API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Rest-Service Patients API
  x-logo:
    url: https://lumahealth-assets.s3.us-west-2.amazonaws.com/new_luma_logo_black.png
    backgroundColor: '#FFFFFF'
    altText: Luma Health
  description: OpenAPI [Basic Structure](https://swagger.io/docs/specification/basic-structure/)
servers:
- url: https://api.lumahealth.io/api/v2
security:
- Bearer: []
tags:
- name: patients
  description: Customer patients
paths:
  /patients:
    get:
      summary: Show a list of patients
      operationId: listPatients
      tags:
      - patients
      parameters:
      - name: culture
        in: query
        schema:
          type: string
          enum:
          - cn
          - hk
      - name: birthSex
        in: query
        schema:
          type: string
          enum:
          - M
          - F
          - UNK
      - name: race
        in: query
        schema:
          type: string
          enum:
          - american-indian-or-alaska-native
          - asian
          - black-or-african-american
          - native-hawaiian-or-other-pacific-islander
          - white
          - other-race
      - name: ethnicityGroup
        in: query
        schema:
          type: string
          enum:
          - hispanic-or-latino
          - not-hispanic-or-latino
      - name: suffix
        in: query
        schema:
          type: string
          enum:
          - II
          - III
          - IV
          - Jr.
          - Sr.
      - name: previousAddress
        in: query
        schema:
          type: string
      - name: lastProcessedAt
        in: query
        schema:
          type: string
          format: date-time
      - name: source
        in: query
        schema:
          type: string
          enum:
          - widget
          - integrator
          - ui
          - referring-provider
          - hub
      - name: widget
        in: query
        schema:
          type: string
          enum:
          - lumabot
      - name: mergedInto
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: createdBy
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          required: true
          minLength: 24
          maxLength: 24
      - name: updatedBy
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          required: true
          minLength: 24
          maxLength: 24
      - name: deletedBy
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: deletedAt
        in: query
        schema:
          type: string
          format: date-time
      - name: primaryCareProvider
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: balance
        in: query
        schema:
          type: number
      - name: balanceUpdatedAt
        in: query
        schema:
          type: string
          format: date-time
      - name: searchIds
        in: query
        schema:
          type: array
          items:
            type: string
      - name: randomName
        in: query
        schema:
          type: boolean
      - name: _id
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: name
        in: query
        schema:
          type: string
      - name: normalizedName
        in: query
        schema:
          type: string
      - name: firstname
        in: query
        schema:
          type: string
      - name: lastname
        in: query
        schema:
          type: string
      - name: middlename
        in: query
        schema:
          type: string
      - name: displayPhone
        in: query
        schema:
          type: string
      - name: displayStatus
        in: query
        schema:
          type: string
          default: pending
          enum:
          - active
          - pending
          - suspended
      - name: email
        in: query
        schema:
          type: string
      - name: safeId
        in: query
        schema:
          type: string
      - name: type
        in: query
        schema:
          type: string
          required: true
          enum:
          - doctor
          - staff
          - patient
          - guest
      - name: roles
        in: query
        schema:
          type: array
          items:
            type: string
      - name: organization
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: doNotContact
        in: query
        schema:
          type: boolean
          required: true
      - name: doNotContactMessage
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: groups
        in: query
        schema:
          type: array
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
      - name: stripeCustomerId
        in: query
        schema:
          type: string
      - name: stripeSubscriptionId
        in: query
        schema:
          type: string
      - name: salesforceId
        in: query
        schema:
          type: string
      - name: deleted
        in: query
        schema:
          type: number
          required: true
      - name: createdAt
        in: query
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        schema:
          type: string
          format: date-time
      - name: lastLogin
        in: query
        schema:
          type: string
          format: date-time
      - name: active
        in: query
        schema:
          type: number
          required: true
      - name: master
        in: query
        schema:
          type: boolean
      - name: language
        in: query
        schema:
          type: string
          default: en
      - name: user
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: setting
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: settings
        in: query
        schema:
          type: mixed
      - name: address
        in: query
        schema:
          type: string
      - name: city
        in: query
        schema:
          type: string
      - name: state
        in: query
        schema:
          type: string
      - name: country
        in: query
        schema:
          type: string
          required: true
          default: US
      - name: postcode
        in: query
        schema:
          type: string
      - name: gender
        in: query
        schema:
          type: string
          required: true
          default: unknown
          enum:
          - male
          - female
          - unknown
          - nonbinary
      - name: allowedIps
        in: query
        schema:
          type: array
          items:
            type: string
      - name: avatar
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: publicKey
        in: query
        schema:
          type: string
      - name: directMessagingEmail
        in: query
        schema:
          type: string
      - name: website
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/patientGlobalSearch'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/deletedParam'
      - $ref: '#/components/parameters/createdByParam'
      - $ref: '#/components/parameters/updatedByParam'
      - $ref: '#/components/parameters/createdAtParam'
      - $ref: '#/components/parameters/updatedAtParam'
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/populateParam'
      - $ref: '#/components/parameters/selectParam'
      - name: searchByNameOrDobOrPhoneNumber
        description: 'If this parameter is passed, we perform a search by name or DOB or Phone Number,

          limited by parameter ''limit'' and ignoring all other parameters.

          '
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Returns a list of patients
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                - page
                - size
                properties:
                  response:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/PatientResponse'
                  page:
                    type: integer
                    format: int32
                    minimum: 1
                  size:
                    type: integer
                    format: int32
                    minimum: 0
                additionalProperties: false
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: unexpected error - need to finalize the error codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create patients
      operationId: createPatients
      tags:
      - patients
      requestBody:
        description: Patients to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientRequestCreate'
      responses:
        '200':
          description: Returns the created patients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: unexpected error - need to finalize the error codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /patients/{patientId}:
    get:
      summary: Show a single patient
      operationId: getPatientById
      tags:
      - patients
      parameters:
      - name: patientId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Patient
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: unexpected error - need to finalize the error codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a patient
      operationId: patientUpdate
      tags:
      - patients
      parameters:
      - name: patientId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      requestBody:
        description: Patient proprieties to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientRequestUpdate'
      responses:
        '200':
          description: Waitlist updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    delete:
      summary: Delete a patient
      operationId: deletePatient
      tags:
      - patients
      parameters:
      - name: patientId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted patient
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /patients/{patientId}/contact-preferences:
    get:
      summary: Get patient contact preferences
      description: Returns the valid contacts for a patient as messenger would use them (after doNotContact, enabled channels, template support, etc.)
      operationId: getPatientContactPreferences
      tags:
      - patients
      parameters:
      - name: patientId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          minLength: 24
          maxLength: 24
      - name: template
        in: query
        required: false
        description: Message template for channel support (default patientGenericNotification)
        schema:
          type: string
          default: patientGenericNotification
      - name: campaignId
        in: query
        required: false
        description: Optional campaign ID for campaign-specific contact preferences (opt-out, channels)
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Patient contact preferences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientContactPreferencesResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        '404':
          description: Patient or campaign (when campaignId provided) not found
components:
  parameters:
    pageParam:
      in: query
      name: page
      required: false
      type: integer
      format: int32
      default: 1
      minimum: 1
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    createdAtParam:
      in: query
      name: createdAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was created.
    patientGlobalSearch:
      in: query
      name: patientGlobalSearch
      type: string
      required: false
      schema:
        type: string
      description: 'Search for a patient within the resource using the current parameters

        Luma Patient ID (patient._id),

        MRN (patient.medicalRecordNumber),

        Name combos(patient.firstname, patient.lastname) OR (patient.lastname,patient.firstname),

        All contact method (phone number and email - active OR not),

        ExternalID (patient.externalId.value),

        Date of Birth.

        '
    updatedAtParam:
      in: query
      name: updatedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was updated.
    updatedByParam:
      in: query
      name: updatedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who updated this object.
    createdByParam:
      in: query
      name: createdBy
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      required: false
      description: The ID of the user who created this object.
    populateParam:
      name: _populate
      in: query
      description: Response properties which will be replaced by the referenced objects, separated by commas.
      required: false
      type: string
      schema:
        type: string
    selectParam:
      name: _select
      in: query
      description: Response properties that should be returned, separated by commas.
      required: false
      type: string
      schema:
        type: string
    deletedParam:
      in: query
      name: deleted
      required: false
      type: number
      enum:
      - 0
      - 1
      schema:
        type: number
        enum:
        - 0
        - 1
      description: Flag for logical deletion where 1 means deleted.
    limitParam:
      name: limit
      in: query
      description: How many items to fetch per page
      required: false
      type: integer
      format: int32
      default: 500
      minimum: 1
      maximum: 1000
      schema:
        type: integer
        format: int32
        default: 500
        minimum: 1
        maximum: 1000
    userParam:
      in: query
      name: user
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the root account user.
  schemas:
    userParam:
      in: query
      name: user
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the root account user.
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    PatientContactPreferencesResponse:
      type: object
      description: This resource represents the set of contact methods Luma Health can currently use to reach a given patient, such as phone numbers and email addresses, along with whether each one is active or archived. It is built from the patient's outbound and external contact records, taking into account do-not-contact status and reasons like the patient being deceased or having asked not to be contacted, so that messaging only targets channels that are currently valid and permitted. It is used by messaging and reminder workflows to decide which contact to use before sending a communication.
      required:
      - validContacts
      properties:
        validContacts:
          type: array
          description: List of valid contacts as messenger would use them
          items:
            type: object
            properties:
              type:
                type: string
              value:
                type: string
              active:
                type: boolean
              archived:
                type: boolean
    idParam:
      in: query
      name: _id
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      required: false
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: Luma's internal ID of an object.
    updatedAtParam:
      in: query
      name: updatedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was updated.
    RolesByUser:
      type: object
      description: Object containing 2 keys, referringProvider and renderingProvider. The value for each key is an array. The content of the array should be the root account ids under the same organization, where this user has the role with the same name of the key.
      required: []
      properties:
        referringProvider:
          type: array
          description: List of root account IDs under an organization where the user has the role referringProvider
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        renderingProvider:
          type: array
          description: List of root account IDs under an organization where the user has the role renderingProvider
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
    updatedByParam:
      in: query
      name: updatedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who updated this object.
    createdAtParam:
      in: query
      name: createdAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was created.
    PatientRequestCreate:
      type: object
      required:
      - name
      - type
      - doNotContact
      - active
      - country
      - gender
      properties:
        culture:
          description: culture
          type: string
          enum:
          - cn
          - hk
        birthSex:
          description: birthSex
          type: string
          enum:
          - M
          - F
          - UNK
        race:
          description: race
          type: string
          enum:
          - american-indian-or-alaska-native
          - asian
          - black-or-african-american
          - native-hawaiian-or-other-pacific-islander
          - white
          - other-race
        ethnicityGroup:
          description: ethnicityGroup
          type: string
          enum:
          - hispanic-or-latino
          - not-hispanic-or-latino
        suffix:
          description: suffix
          type: string
          enum:
          - II
          - III
          - IV
          - Jr.
          - Sr.
        previousAddress:
          description: previousAddress
          type: string
        stats:
          type: object
          properties:
            counters:
              type: object
              properties:
                messagesSentToPatient:
                  description: stats.counters.messagesSentToPatient
                  type: number
                confirmedAppointments:
                  description: stats.counters.confirmedAppointments
                  type: number
                cancelledAppointments:
                  description: stats.counters.cancelledAppointments
                  type: number
                offersSent:
                  description: stats.counters.offersSent
                  type: number
                offersAccepted:
                  description: stats.counters.offersAccepted
                  type: number
                appointmentOffersReplied:
                  description: stats.counters.appointmentOffersReplied
                  type: number
            average:
              type: object
              properties:
                appointmentOfferReplyTime:
                  description: stats.average.appointmentOfferReplyTime
                  type: number
            metadata:
              type: object
              properties:
                lastAppointmentAt:
                  description: stats.metadata.lastAppointmentAt
                  type: string
                  format: date-time
            oldestAppointment:
              description: stats.oldestAppointment
              type: string
              format: date-time
        lastProcessedAt:
          description: lastProcessedAt
          type: string
          format: date-time
          default: '2022-03-31T12:01:59.227Z'
        source:
          description: source
          type: string
          enum:
          - widget
          - integrator
          - ui
          - referring-provider
          - hub
        widget:
          description: widget
          type: string
          enum:
          - lumabot
        mergedInto:
          description: ID of Patient
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        subscribers:
          description: subscribers
          type: array
          items:
            type: object
            properties:
              subscribed:
                description: subscribed
                type: boolean
              user:
                description: ID of User
                type: string
                pattern: '[0-9a-f]'
                minLength: 24
                maxLength: 24
              _id:
                description: _id
                type: string
                pattern: '[0-9a-f]'
                minLength: 24
                maxLength: 24
        outboundContact:
          description: outboundContact
          type: array
          items:
            type: object
            properties:
              provider:
                description: provider
                type: string
                enum:
                - mandrill
                - twilio
                - nexmo
                - sendgrid
                - plivo
                - bandwidth
                - ringcentral
                - awsses
                - interfax
              channel:
                description: channel
                type: string
                enum:
                - sms
                - voice
                - fax
                - email
                - whatsapp
              value:
                description: value
                type: string
              active:
                description: active
                type: boolean
              _id:
                description: _id
                type: string
                pattern: '[0-9a-f]'
                minLength: 24
                maxLength: 24
        primaryCareProvider:
          description: ID of Provider
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        recommendations:
          type: object
          properties:
            reminderTime:
              description: recommendations.reminderTime
              type: number
        balance:
          description: balance
          type: number
        balanceUpdatedAt:
          description: balanceUpdatedAt
          type: string
          format: date-time
        searchIds:
          description: searchIds
          type: array
          items:
            type: string
        randomName:
          description: randomName
          type: boolean
        name:
          description: name
          type: string
        normalizedName:
          description: normalizedName
          type: string
        firstname:
          description: firstname
          type: string
        lastname:
          description: lastname
          type: string
        middlename:
          description: middlename
          type: string
        displayPhone:
          description: displayPhone
          type: string
        displayStatus:
          description: displayStatus
          type: string
          default: pending
          enum:
          - active
          - pending
          - suspended
        email:
          description: email
          type: string
        safeId:
          description: safeId
          type: string
        type:
          description: type
          type: string
          enum:
          - patient
          - guest
        roles:
          description: roles
          type: array
          items:
            type: string
        rolesByUser:
          $ref: '#/components/schemas/RolesByUser'
        organization:
          description: ID of Organization
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        contact:
          description: contact
          type: array
          items:
            type: object
            properties:
              type:
                description: type
                type: string
                default: email
                enum:
                - inapp
                - sms
                - voice
                - email
                - fax
                - whatsapp
              value:
                description: value
                type: string
              active:
                description: active
                type: boolean
              archived:
                description: archived
                type: boolean
              archivedReason:
                description: archivedReason
                type: string
                default: none
                enum:
                - none
                - unreachable
                - do-not-contact
              archivedMessage:
                description: ID of Message
                type: string
                pattern: '[0-9a-f]'
                minLength: 24
                maxLength: 24
        doNotContact:
          description: doNotContact
          type: boolean
        doNotContactMessage:
          description: ID of Message
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        groups:
          description: groups
          type: array
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        stripeCustomerId:
          description: stripeCustomerId
          type: string
        twoFactorAuthSecret:
          type: object
          properties:
            enabled:
              description: twoFactorAuthSecret.enabled
              type: boolean
        stripeSubscriptionId:
          description: stripeSubscriptionId
          type: string
        salesforceId:
          description: salesforceId
          type: string
        lastLogin:
          description: lastLogin
          type: string
          format: date-time
        active:
          description: active
          type: number
        master:
          description: master
          type: boolean
        language:
          description: language
          type: string
          default: en
        address:
          description: address
          type: string
        city:
          description: city
          type: string
        state:
          description: state
          type: string
        country:
          description: country
          type: string
          default: US
        postcode:
          description: postcode
          type: string
        gender:
          description: gender
          type: string
          default: unknown
          enum:
          - male
          - female
          - unknown
          - nonbinary
        allowedIps:
          description: allowedIps
          type: array
          items:
            type: string
        avatar:
          description: ID of FileUpload
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        publicKey:
          description: publicKey
          type: string
        directMessagingEmail:
          description: directMessagingEmail
          type: string
        demoConfiguration:
          type: object
          properties:
            type:
              type: string
              enum:
              - default
        website:
          description: website
          type: string
        salesforceData:
          $ref: '#/components/schemas/SalesforceData'
        externalId:
          $ref: '#/components/schemas/ExternalId'
        secondaryExternalId:
          $ref: '#/components/schemas/ExternalId'
        dateOfBirth:
          type: object
          properties:
            year:
              description: dateOfBirth.year
              type: number
            month:
              description: dateOfBirth.month
              type: number
            day:
              description: dateOfBirth.day
            

# --- truncated at 32 KB (142 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/luma-health/refs/heads/main/openapi/luma-health-patients-api-openapi.yml