openapi: 3.2.0
info:
  version: 2.0.0
  title: Rest-Service Campaigns 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: campaigns
  description: Contact preference campaigns that determine how and in what order a patient, facility, or user is contacted
paths:
  /campaigns:
    get:
      summary: List campaigns
      operationId: campaignsList
      tags:
      - campaigns
      parameters:
      - name: ref
        in: query
        description: The type of resource linked to this campaign
        schema:
          type: string
          enum:
          - patient
          - facility
          - user
      - name: refId
        in: query
        description: The ID of the resource linked to this campaign
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: name
        in: query
        description: The name of this campaign
        schema:
          type: string
      - name: channels
        in: query
        description: The opt-in preferences and order of channels to contact the resource linked to this campaign
        schema:
          type: array
          items:
            type: string
            enum:
            - sms
            - voice
            - email
      - name: active
        in: query
        description: Indicates whether this campaign should be used when sending messages for this resource
        schema:
          type: boolean
      - name: lastUpdatedBy
        in: query
        description: Indicates the last resource that updated this campaign
        schema:
          type: string
          enum:
          - patient
          - integrator
      - name: useRootAsFallback
        in: query
        description: If the patient has missing Campaigns for certain types, it will fallback to returning the root campaigns. Requires one and single patient _id
        schema:
          type: boolean
      responses:
        '200':
          description: List of campaigns
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                - page
                - size
                properties:
                  response:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/Campaign'
                  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 campaign
      operationId: campaignCreate
      tags:
      - campaigns
      requestBody:
        description: Optional description in *Markdown*
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Campaign'
      responses:
        '201':
          description: Successful creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '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'
  /campaigns/{campaignId}:
    get:
      summary: Get campaign by id
      operationId: campaignGet
      tags:
      - campaigns
      parameters:
      - name: campaignId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    put:
      summary: Update a campaign
      operationId: campaignUpdate
      tags:
      - campaigns
      parameters:
      - name: campaignId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      requestBody:
        description: A campaign (full or partial) to be published
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Campaign'
      responses:
        '200':
          description: Campaign updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
components:
  schemas:
    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.
    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.
    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.
    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.
    Campaign:
      type: object
      description: Represents an outreach campaign that targets a specific resource, such as a patient, facility, or user, and defines which contact channels like SMS, email, or voice should be attempted and in what order. It tracks whether the campaign is active, who last updated it, and optional external identifiers for syncing with third-party systems, and is used to drive automated patient engagement workflows like recall or referral outreach.
      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'
        ref:
          type: string
          enum:
          - patient
          - facility
          - user
        refId:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        name:
          type: string
        channels:
          type: array
          items:
            type: string
            enum:
            - sms
            - voice
            - email
        type:
          type: string
          enum:
          - inbound
          - outbound
        lastUpdatedBy:
          type: string
          enum:
          - patient
          - integrator
        active:
          schema:
            type: boolean
    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.
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT