openapi: 3.0.3
info:
  title: Walgreens Vaccine Scheduling API
  description: >-
    Allows developers to integrate vaccine and immunization appointment booking
    capabilities across all Walgreens locations in the United States and Puerto Rico.
    The API provides a complete end-to-end vaccine scheduling workflow: eligibility
    checking, timeslot availability, appointment holds, patient registration, and
    booking confirmation. Supports 19+ vaccine types including COVID-19, influenza,
    RSV, MMR, HPV, and travel immunizations.
  version: 1.0.0
  contact:
    url: https://developer.walgreens.com
  termsOfService: https://developer.walgreens.com/terms
servers:
  - url: https://services.walgreens.com
    description: Production
  - url: https://services-qa.walgreens.com
    description: Sandbox
tags:
  - name: Eligibility
    description: Vaccine eligibility checking
  - name: Appointments
    description: Appointment scheduling and management
  - name: Patients
    description: Patient registration for vaccine appointments
security:
  - apiKey: []
paths:
  /api/vaccine/scheduling/eligibility/v1:
    post:
      operationId: checkVaccineEligibility
      summary: Check Vaccine Eligibility
      description: >-
        Determines vaccination eligibility for a patient based on their state and
        date of birth. Returns a list of eligible and ineligible vaccines with
        eligibility details, age restrictions, warnings, and any pre-screening
        questions required before scheduling.
      tags:
        - Eligibility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EligibilityRequest'
            example:
              apiKey: "YOUR_API_KEY"
              affId: "YOUR_AFFILIATE_ID"
              state: "IL"
              dob: "1990-05-15"
      responses:
        '200':
          description: Vaccine eligibility results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityResponse'
        '400':
          description: Malformed request body
        '403':
          description: Invalid API key
        '500':
          description: Internal server error
  /api/vaccine/scheduling/timeslots/v1:
    post:
      operationId: getVaccineTimeslots
      summary: Get Vaccine Timeslots
      description: >-
        Retrieves available appointment timeslots for specified vaccines at Walgreens
        locations near a given zip code and coordinates. Returns locations with their
        available dates and time slots, vaccine product information, and distance from
        the specified position.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeslotsRequest'
            example:
              apiKey: "YOUR_API_KEY"
              affId: "YOUR_AFFILIATE_ID"
              state: "IL"
              zipCode: "60601"
              dob: "1990-05-15"
              vaccine: ["207"]
              appointmentAvailability:
                startDateTime: "2026-05-10"
              position:
                latitude: 41.8827
                longitude: -87.6233
      responses:
        '200':
          description: Available vaccine appointment locations and timeslots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeslotsResponse'
        '400':
          description: Malformed request body
        '403':
          description: Invalid API key
        '500':
          description: Internal server error
  /api/vaccine/scheduling/hold/v1:
    post:
      operationId: holdVaccineAppointment
      summary: Hold Vaccine Appointment
      description: >-
        Reserves a specific vaccine appointment timeslot at a Walgreens location,
        returning an engagement ID for use in subsequent patient registration and
        confirmation steps. The hold is temporary and must be confirmed to finalize
        the booking.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HoldRequest'
            example:
              apiKey: "YOUR_API_KEY"
              affId: "YOUR_AFFILIATE_ID"
              locationId: "store-5823"
              appointmentDate: "2026-05-10T09:30:00-05:00"
              slot: "09:30 am"
              channel: "Mobile"
              client: "MyHealthApp"
              engagementType: "Guest"
              vaccines:
                - code: "207"
                  productId: "covid-moderna-001"
                  rxRequired: false
      responses:
        '200':
          description: Appointment hold successful, returns engagement ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldResponse'
        '400':
          description: Malformed request body
        '401':
          description: Request unauthorized
        '403':
          description: Invalid API key
        '409':
          description: Cannot place hold for timeslot - slot unavailable
        '500':
          description: Internal server error
  /api/vaccine/scheduling/patient/v1:
    post:
      operationId: attachPatientToAppointment
      summary: Attach Patient to Appointment
      description: >-
        Registers patient personal information (PII) for a held vaccine appointment,
        linking the patient record to the engagement. Required before confirming
        the appointment. Supports SMS consent for appointment reminders.
      tags:
        - Patients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientRequest'
            example:
              apiKey: "YOUR_API_KEY"
              affId: "YOUR_AFFILIATE_ID"
              engagementId: "eng-12345-abc"
              partnerId: "MyHealthApp"
              firstName: "Jane"
              lastName: "Smith"
              dob: "1990-05-15"
              gender: "female"
              contact:
                phones:
                  - type: "Mobile"
                    number: "312-555-0123"
                    smsConsent: "Agree"
                emails:
                  - type: "Email"
                    address: "jane.smith@example.com"
      responses:
        '201':
          description: Patient successfully attached to appointment
        '400':
          description: Malformed request body
        '401':
          description: Request unauthorized
        '403':
          description: Invalid API key
        '409':
          description: Patient information already exists for this engagement
        '500':
          description: Internal server error
  /api/vaccine/scheduling/confirm/v1:
    patch:
      operationId: confirmVaccineAppointment
      summary: Confirm Vaccine Appointment
      description: >-
        Finalizes a vaccine appointment reservation, converting the held timeslot
        into a confirmed booking. Must be called after patient information has been
        attached to the engagement. Returns HTTP 204 on success.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmRequest'
            example:
              apiKey: "YOUR_API_KEY"
              affId: "YOUR_AFFILIATE_ID"
              engagementId: "eng-12345-abc"
      responses:
        '204':
          description: Appointment confirmed successfully
        '400':
          description: Malformed request body
        '401':
          description: Request unauthorized
        '403':
          description: Invalid API key
        '409':
          description: Cannot confirm appointment
        '500':
          description: Internal server error
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: apiKey
      description: API key obtained from Walgreens Developer Portal
  schemas:
    EligibilityRequest:
      type: object
      required:
        - apiKey
        - affId
        - state
        - dob
      properties:
        apiKey:
          type: string
          description: Your Walgreens API key
        affId:
          type: string
          description: Your affiliate identifier
        state:
          type: string
          description: Two-character US state code
          example: "IL"
        dob:
          type: string
          format: date
          description: Patient date of birth in YYYY-MM-DD format
          example: "1990-05-15"
    EligibilityResponse:
      type: object
      properties:
        state:
          type: string
          description: State code from request
        age:
          type: integer
          description: Patient age calculated from DOB
        dob:
          type: string
          description: Date of birth in MM/DD/YYYY format
        eligibleVaccineList:
          type: array
          items:
            $ref: '#/components/schemas/VaccineEligibility'
          description: List of vaccines the patient is eligible for
        inEligibleVaccineList:
          type: array
          items:
            $ref: '#/components/schemas/VaccineEligibility'
          description: List of vaccines the patient is not eligible for
    VaccineEligibility:
      type: object
      properties:
        vaccineCode:
          type: string
          description: Vaccine code identifier
          example: "207"
        displayName:
          type: string
          description: Human-readable vaccine name
          example: "COVID-19 Vaccine"
        eligible:
          type: boolean
          description: Whether patient is eligible for this vaccine
        vaccineType:
          type: string
          description: Category of vaccine
        vaccineDisplayOrder:
          type: integer
          description: Display ordering for UI
        multiDose:
          type: boolean
          description: Whether this vaccine requires multiple doses
        seriesNumber:
          type: string
          description: Series number for multi-dose vaccines
        group:
          type: string
          description: Vaccine group classification
        serviceId:
          type: string
          description: Internal service identifier
        restrictions:
          type: array
          items:
            $ref: '#/components/schemas/VaccineRestriction'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/VaccineWarning'
    VaccineRestriction:
      type: object
      properties:
        code:
          type: string
          description: Restriction code
        message:
          type: string
          description: Restriction message for display
        vaccineCode:
          type: string
          description: Associated vaccine code
        minimumAge:
          type: integer
          description: Minimum age for vaccine eligibility
        maximumAge:
          type: integer
          description: Maximum age for vaccine eligibility
    VaccineWarning:
      type: object
      properties:
        code:
          type: string
          description: Warning code
        message:
          type: string
          description: Warning message for display
        vaccineCode:
          type: string
          description: Associated vaccine code
        question:
          type: string
          description: Screening question text
        answers:
          type: array
          items:
            type: string
          description: Acceptable answers to the screening question
        minimumAge:
          type: integer
          description: Minimum age threshold for warning
        maximumAge:
          type: integer
          description: Maximum age threshold for warning
    TimeslotsRequest:
      type: object
      required:
        - apiKey
        - affId
        - state
        - zipCode
        - dob
        - vaccine
        - appointmentAvailability
        - position
      properties:
        apiKey:
          type: string
          description: Your Walgreens API key
        affId:
          type: string
          description: Your affiliate identifier
        state:
          type: string
          description: Two-character US state code
        zipCode:
          type: string
          description: Patient or search zip code
        dob:
          type: string
          format: date
          description: Patient date of birth in YYYY-MM-DD format
        vaccine:
          type: array
          items:
            type: string
          maxItems: 4
          description: Array of up to 4 vaccine code IDs
        appointmentAvailability:
          type: object
          required:
            - startDateTime
          properties:
            startDateTime:
              type: string
              format: date
              description: Start date for available appointments
            endDateTime:
              type: string
              format: date
              description: Optional end date for appointment range
        position:
          type: object
          required:
            - latitude
            - longitude
          properties:
            latitude:
              type: number
              format: double
              description: Search latitude coordinate
            longitude:
              type: number
              format: double
              description: Search longitude coordinate
    TimeslotsResponse:
      type: object
      properties:
        locations:
          type: array
          items:
            $ref: '#/components/schemas/VaccineLocation'
    VaccineLocation:
      type: object
      properties:
        locationId:
          type: string
          description: Unique location identifier
        name:
          type: string
          description: Store name
        storenumber:
          type: string
          description: Walgreens store number
        description:
          type: string
          description: Store description
        position:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
        address:
          type: object
          properties:
            line1:
              type: string
            line2:
              type: string
            city:
              type: string
            state:
              type: string
            country:
              type: string
            zip:
              type: string
        phone:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              number:
                type: string
        distance:
          type: number
          description: Distance in miles from search coordinates
        timeZone:
          type: string
          description: Location timezone
        appointmentAvailability:
          type: array
          items:
            $ref: '#/components/schemas/AppointmentAvailability'
    AppointmentAvailability:
      type: object
      properties:
        manufacturer:
          type: array
          items:
            type: object
            properties:
              productId:
                type: string
              vaccineCode:
                type: string
              vaccineName:
                type: string
              category:
                type: string
              prescriptionRequired:
                type: boolean
        date:
          type: string
          format: date
          description: Available date
        day:
          type: string
          description: Day of week
        slots:
          type: array
          items:
            type: string
          description: Available time slots (e.g. "09:30 am")
        numberOfSlotsAvailable:
          type: integer
          description: Total number of open slots for the date
    HoldRequest:
      type: object
      required:
        - apiKey
        - affId
        - locationId
        - appointmentDate
        - slot
        - channel
        - client
        - engagementType
        - vaccines
      properties:
        apiKey:
          type: string
          description: Your Walgreens API key
        affId:
          type: string
          description: Your affiliate identifier
        locationId:
          type: string
          description: Store location ID from timeslots response
        appointmentDate:
          type: string
          description: ISO format appointment date/time with timezone offset
          example: "2026-05-10T09:30:00-05:00"
        slot:
          type: string
          description: Time slot to hold
          example: "09:30 am"
        channel:
          type: string
          enum: ["Web", "Mobile"]
          description: Client channel type
        client:
          type: string
          description: Client application identifier
        engagementType:
          type: string
          enum: ["Guest"]
          description: Engagement type, always Guest
        vaccines:
          type: array
          items:
            type: object
            required:
              - code
              - productId
              - rxRequired
            properties:
              code:
                type: string
                description: Vaccine code
              productId:
                type: string
                description: Vaccine product identifier
              rxRequired:
                type: boolean
                description: Whether a prescription is required
        userResponses:
          type: array
          items:
            type: object
            properties:
              details:
                type: array
                items:
                  type: object
                  properties:
                    answer:
                      type: string
                    question:
                      type: string
    HoldResponse:
      type: object
      properties:
        engagementId:
          type: string
          description: Unique engagement identifier for subsequent steps
    PatientRequest:
      type: object
      required:
        - apiKey
        - affId
        - engagementId
        - partnerId
        - firstName
        - lastName
        - dob
        - gender
        - contact
      properties:
        apiKey:
          type: string
          description: Your Walgreens API key
        affId:
          type: string
          description: Your affiliate identifier
        engagementId:
          type: string
          description: Engagement ID from the hold response
        partnerId:
          type: string
          description: Client application name
        firstName:
          type: string
          description: Patient first name
        middleName:
          type: string
          description: Patient middle name (optional)
        lastName:
          type: string
          description: Patient last name
        dob:
          type: string
          format: date
          description: Patient date of birth in YYYY-MM-DD format
        gender:
          type: string
          enum: ["male", "female", "other", "unknown"]
          description: Patient gender
        contact:
          type: object
          properties:
            phones:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    example: "Mobile"
                  number:
                    type: string
                    description: Phone number in ###-###-#### format
                  smsConsent:
                    type: string
                    enum: ["Agree", "Disagree"]
                    description: SMS consent for appointment reminders
            emails:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    example: "Email"
                  address:
                    type: string
                    format: email
    ConfirmRequest:
      type: object
      required:
        - apiKey
        - affId
        - engagementId
      properties:
        apiKey:
          type: string
          description: Your Walgreens API key
        affId:
          type: string
          description: Your affiliate identifier
        engagementId:
          type: string
          description: Engagement ID from the hold response