openapi: 3.2.0
info:
  version: 2.0.0
  title: Rest-Service Groups 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: groups
  description: Group of staff users
paths:
  /groups:
    get:
      summary: List groups
      operationId: groupsList
      tags:
      - groups
      parameters:
      - name: name
        in: query
        description: Descriptive label of a group. This is the only way to link a group in Luma with another in an external service, as the group doesn't have an "externalId" field.
        schema:
          type: string
      - name: facilities
        in: query
        description: The IDs of the facilities associated with this group.
        schema:
          type: array
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
      - name: type
        in: query
        description: Indicates if a group was created by users or by the system.
        schema:
          type: string
          enum:
          - user
          - system
      - $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'
      responses:
        '200':
          description: List of groups
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                - page
                - size
                properties:
                  response:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/GroupResponse'
                  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
    post:
      summary: Create group
      operationId: groupCreate
      tags:
      - groups
      requestBody:
        description: Optional description in *Markdown*
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupRequestCreate'
      responses:
        '201':
          description: Successful creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /groups/{groupId}:
    get:
      summary: Get group by id
      operationId: groupGet
      tags:
      - groups
      parameters:
      - name: groupId
        in: path
        required: true
        description: Groups' unique identifier in Luma's database.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    put:
      summary: Update a group
      operationId: groupUpdate
      tags:
      - groups
      parameters:
      - name: groupId
        in: path
        required: true
        description: Groups' unique identifier in Luma's database.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      requestBody:
        description: A group (full or partial) to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupRequestUpdate'
      responses:
        '200':
          description: Group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    delete:
      summary: Delete a group
      operationId: groupDelete
      tags:
      - groups
      parameters:
      - name: groupId
        in: path
        required: true
        description: Groups' unique identifier in Luma's database.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Deleted group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
components:
  schemas:
    GroupResponse:
      type: object
      description: A Group is a named collection of users and/or facilities within a Luma Health account, used to organize staff for tasks like routing and assignment. Groups can be created manually by an admin or generated automatically by the system, and each one can be scoped to all facilities or a specific subset. Other resources, such as chat activities, reference a Group when work needs to be routed to a whole team rather than a single staff member.
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        facilities:
          type: array
          description: The IDs of the facilities associated with this group.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        users:
          type: array
          description: DEPRECATED. Do not use this field. See the User resource and its "groups" property instead.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        type:
          type: string
          enum:
          - user
          - system
          description: Indicates if a group was created by users or by the system.
        name:
          type: string
          description: Descriptive label of a group. This is the only way to link a group in Luma with another in an external service, as the group doesn't have an "externalId" field.
    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
    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.
    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.
    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.
    GroupRequestCreate:
      type: object
      required:
      - name
      - facilities
      properties:
        facilities:
          type: array
          description: The IDs of the facilities associated with this group.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        users:
          type: array
          description: DEPRECATED. Do not use this field. See the "User" resource and use its "groups" array instead.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        name:
          type: string
          description: Descriptive label of a group. This is the only way to link a group in Luma with another in an external service, as the group doesn't have an "externalId" field.
        type:
          type: string
          default: user
          enum:
          - user
          - system
          description: Indicates if a group was created by users or by the system.
    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.
    GroupRequestUpdate:
      type: object
      properties:
        facilities:
          type: array
          description: The IDs of the facilities associated with this group.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        users:
          type: array
          description: DEPRECATED. Do not use this field. See the "User" resource and use its "groups" array instead.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        name:
          type: string
          description: Descriptive label of a group. This is the only way to link a group in Luma with another in an external service, as the group doesn't have an "externalId" field.
        type:
          type: string
          default: user
          enum:
          - user
          - system
          description: Indicates if a group was created by users or by the system.
    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.
  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.
    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
    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
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT