openapi: 3.0.0
info: # working version: https://app.swaggerhub.com/apis/brock57/ClinSparkRecruit/1.0.0
  description: >-
    Allows for adding of volunteers, assignment and cancellation of
    appointments.
  version: 1.0.1-oas3
  title: ClinSpark Recruit
servers:
  - url: 'https://{customerId}.clinspark.com/api/v1/recruit'
    variables:
      customerId:
        default: community-dev
        description: Customer ID assigned by the service provider
  - url: 'https://{ngrokPrefix}.ngrok-free.app/clinspark/api/v1/recruit'
    variables:
      ngrokPrefix:
        default: 8232-73-217-91-70
        description: first part of ngrok-assigned id
paths:
  /updateVolunteer:
    post:
      tags:
        - recruit
      summary: Updates a new volunteer
      operationId: updateVolunteer
      parameters:
        - name: reasonForChange
          in: query
          description: Reason for Change
          required: true
          schema:
            type: string
      requestBody:
        description: JSON volunteer to add
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolunteerUpdate'
      responses:
        '200':
          description: 'Success: OK message.'
        '401':
          description: 'Unauthorized: Must add Basic Authentication headers'
        '422':
          description: >-
            Invalid request: There are input validation errors; look at the JSON
            response for details.
      security:
        - basicAuth: []
  /saveVolunteer:
    post:
      tags:
        - recruit
      summary: Saves a new volunteer
      operationId: saveVolunteer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Volunteer'
        description: JSON volunteer to add
        required: true
      responses:
        '200':
          description: 'Success: OK message.'
        '401':
          description: 'Unauthorized: Must add Basic Authentication headers'
        '422':
          description: >-
            Invalid request: There are input validation errors; look at the JSON
            response for details.
      security:
        - basicAuth: []
  /findActiveStudySites:
      get:
        tags:
          - recruit
        summary: Finds study sites that are actively recruiting
        parameters:
          - name: studyName
            in: query
            description: >-
              Case insensitive study name used to match study sites with the
              corresponding name
            required: false
            schema:
              type: string
          - name: siteId
            in: query
            description: >-
              ID of a given site; only study sites with the corresponding site
              will be returned
            required: false
            schema:
              type: number
              format: integer
          - name: siteName
            in: query
            description: >-
              Case insensitive site name used to match study sites with the
              corresponding name
            required: false
            schema:
              type: string
          - name: locationOid
            in: query
            description: >-
              Case sensitive location OID used to match study sites with the
              corresponding OID
            required: false
            schema:
              type: string
        responses:
          '200':
            description: successful operation
            content:
              application/json:
                schema:
                  type: array
                  items:
                    $ref: '#/components/schemas/StudySite'
          '401':
            description: 'Unauthorized: Must add Basic Authentication headers'
        security:
          - basicAuth: []
  /findUnassignedAppointments:
    get:
      tags:
        - recruit
      summary: Finds appointments for the given study site
      parameters:
        - name: studySiteId
          in: query
          description: ID of a given study site
          required: true
          schema:
            type: number
            format: integer
        - name: cohortName
          in: query
          description: >-
            Case insensitive cohort name used for a wild card search; only
            appointments that have an assigned cohort matching will be returned
          required: false
          schema:
            type: string
        - name: appointmentType
          in: query
          description: >-
            Case insensitive appointment typed used for a wild card search; only
            appointments that have an apointment type matching will be returned
          required: false
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecruitmentAppointment'
        '401':
          description: 'Unauthorized: Must add Basic Authentication headers'
      security:
        - basicAuth: []
  /volunteerStudySearch:
    get:
      tags:
        - recruit
      summary: >-
        Finds matching studies for the found volunteer using the advanced
        volunteer search. The advanced searches must be not be archived and must
        have a study associated while actively recruiting. If the advanced
        search also specifies a site, that site in question must match the
        volunteer. The boolean eligible property in the response array indicates
        whether or not a study match has occurred.
      parameters:
        - name: volunteerId
          in: query
          description: primary key of the volunteer
          required: false
          schema:
            type: integer
            format: integer
        - name: externalId
          in: query
          description: ID from source system
          required: false
          schema:
            type: string
        - name: emailAddress
          in: query
          description: Case insensitive email address
          required: false
          schema:
            type: string
        - name: mobilePhone
          in: query
          description: Will be converted to ISO format before a query takes place
          required: false
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VolunteerSearchResult'
        '401':
          description: 'Unauthorized: Must add Basic Authentication headers'
      security:
        - basicAuth: []
  /listVolunteerAppointments:
    get:
      tags:
        - recruit
      summary: >-
        Finds appointments for the given volunteer found by one of the
        parameters supplied
      parameters:
        - name: volunteerId
          in: query
          description: primary key of the volunteer
          required: false
          schema:
            type: integer
            format: integer
        - name: externalId
          in: query
          description: ID from source system
          required: false
          schema:
            type: string
        - name: emailAddress
          in: query
          description: Case insensitive email address
          required: false
          schema:
            type: string
        - name: mobilePhone
          in: query
          description: Will be converted to ISO format before a query takes place
          required: false
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecruitmentAppointment'
        '401':
          description: 'Unauthorized: Must add Basic Authentication headers'
      security:
        - basicAuth: []
  /assignAppointment:
    post:
      tags:
        - recruit
      summary: Allows for assigning a given appointment to a matching volunteer
      parameters:
        - name: recruitmentAppointmentId
          in: query
          description: ID from source system
          required: true
          schema:
            type: number
            format: integer
        - name: volunteerId
          in: query
          description: ID from the volunteer
          required: false
          schema:
            type: integer
        - name: externalId
          in: query
          description: ID from source system
          required: false
          schema:
            type: string
        - name: emailAddress
          in: query
          description: Case insensitive email address
          required: false
          schema:
            type: string
        - name: mobilePhone
          in: query
          description: Will be converted to ISO format before a query takes place
          required: false
          schema:
            type: string
        - name: appointmentNotes
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
        '401':
          description: 'Unauthorized: Must add Basic Authentication headers'
        '422':
          description: rendered if appointment could not be found
      security:
        - basicAuth: []
  /cancelAppointment:
    post:
      tags:
        - recruit
      summary: Allows for canceling a given appointment
      parameters:
        - name: recruitmentAppointmentId
          in: query
          description: ID from source system
          required: true
          schema:
            type: number
            format: integer
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
        '401':
          description: 'Unauthorized: Must add Basic Authentication headers'
        '422':
          description: rendered if appointment could not be found
      security:
        - basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    VolunteerAnswer:
      type: object
      properties:
        question:
          type: string
          example: Favorite web application?
          description: Verbatim custom volunteer question
        answer:
          type: string
          description: Answer format must match that defined by the custom question
    Volunteer:
      type: object
      properties:
        id:
          type: integer
          format: integer
        externalId:
          type: string
          example: '987123'
          description: Unique identifier in originating recruitment system
        title:
          type: string
          example: Mr
        firstName:
          type: string
          example: Joseph
        middleName:
          type: string
          description: >-
            can be an initial, if no value is provided a '-' will be stored with
            the volunteer reocord
        lastName:
          type: string
          example: Padres
        genderMale:
          type: boolean
        ethnicHispanic:
          type: boolean
          description: null indicates unknown
        otherRace:
          type: string
          description: additional race details if race type doesn't match
        dateOfBirth:
          type: string
          example: '1980-05-27'
          description: ISO DOB in form of yyyy-MM-dd
        nameSuffix:
          type: string
          description: jr, II
        nationality:
          type: string
        preferredLanguage:
          type: string
        address:
          type: string
        city:
          type: string
        region:
          type: string
          description: >-
            should match regions configured in the volunteer configuration
            component; ie state / province
        country:
          type: string
        postalCode:
          type: string
        homePhone:
          type: string
          description: >-
            tightly validated based on the general settings configured; should
            be as close to ISO format as possible with leading country code.
            https://github.com/google/libphonenumber is used for underlying
            validation
        workPhone:
          type: string
          description: see homePhone
        mobilePhone:
          type: string
          description: same rules apply as homePhone, but must be unique in database
        phoneNotes:
          type: string
          description: can be arbitrary notes to guide recruiters about making phone calls
        contactableByPhone:
          type: boolean
          description: volunteer's permission to be contacted by phone
          default: true
        contactableBySms:
          type: boolean
          description: volunteer's permission to be contacted by SMS
          default: true
        contactableByEmailCampaign:
          type: boolean
          description: volunteer's permission to be contacted by emails
          default: true
        nextOfKin:
          type: string
          description: >-
            notes generally about who to contact should there be a reason to do
            so in an emergency situation
        volunteerEmploymentStatus:
          type: string
          enum:
            - Unemployed
            - Student
            - EmployedPartTime
            - EmployedFullTime
            - Retired
        weightKilos:
          type: number
          format: double
          example: 123.45
        heightMeters:
          type: number
          format: double
          example: 2.12
        vegetarian:
          type: boolean
          description: null indicates unknown
        surgicallySterile:
          type: boolean
          default: false
        contraceptionType:
          type: string
          example: Abstinence
          description: should match a type configured in the volunteer configure component
        numberOfChildren:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 20
        menstruationStartAge:
          type: integer
          description: value should only be present for females
          minimum: 8
          maximum: 50
        menstruationEndAge:
          type: integer
          description: value should only be present for females
          minimum: 10
          maximum: 100
        lastPeriodStartDate:
          type: string
          example: '2024-05-27'
          description: In form of yyyy-MM-dd; value should only be present for females
        regularPeriodIntervalDays:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 100
        regularPeriodDurationDays:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 100
        currentlyPregnant:
          type: boolean
          description: value should only be present for females
          default: false
        currentlyBreastFeeding:
          type: boolean
          description: value should only be present for females
          default: false
        childBearingPotential:
          type: boolean
          description: value should only be present for females
          default: false
        allergies:
          type: boolean
          description: null indicates unknown
        emailAddress:
          type: string
          example: something@domain.com
          description: >-
            must be unique; strictly validated using Apache Commons Email
            Validator framework
        contactSource:
          type: string
          description: >-
            describes how a volunteer contact occurred; should match a source
            configured in the volunteer configure component
        generalPractitioner:
          type: string
          description: volunteer's physician
        generalPractitionerPhoneNumber:
          type: string
          description: volunteer's physician phone number
        generalPractitionerAddress:
          type: string
          description: volunteer's physician address
        siteName:
          type: string
          example: Base Site
          description: >-
            the name of the site that the volunteer should be associated with;
            if not provided, use siteId
        siteId:
          type: integer
          format: integer
          example: -1
          description: >-
            the id of the site that the volunteer should be associated with; if
            not provided, use siteName
        volunteerAnswers:
          type: array
          example:
            - question: Favorite web application?
              answer: Gmail
            - question: Favorite number?
              answer: '123'
            - question: Favorite decimal?
              answer: '123.4'
            - question: Favorite date?
              answer: '1969-07-20'
          description: >-
            array of simple objects with verbatim ClinSpark questions and
            corresponding answers
          items:
            $ref: '#/components/schemas/VolunteerAnswer'
        volunteerNotes:
          type: array
          example:
            - Volunteer travels often
            - Is afraid of needles
          description: Simple notes that move to a volunteer notes section
          items:
            type: string
        volunteerRaces:
          type: array
          example:
            - American Indian or Alaska Native
          description: Must match race names defined in ClinSpark
          items:
            type: string
        volunteerSubstanceUse:
          type: array
          example:
            - substanceUseCategory: Alcohol
              name: Beer
              useFrequency: Week
              useConsumption: '5'
              consumptionUnit: Glass/Bottle (.5L)
              substanceUseStatus: Social
              startDate: '2001'
              lastConsumed: '2021-07-21'
              substanceNotes: Enjoys heavy IPAs
          description: >-
            array of simple objects with verbatim ClinSpark questions and
            corresponding answers
          items:
            $ref: '#/components/schemas/VolunteerSubstanceUse'
    VolunteerUpdate:
      type: object
      properties:
        id:
          type: integer
          format: integer
        externalId:
          type: string
          example: '987123'
          description: Unique identifier in originating recruitment system
        title:
          type: string
          example: Mr
        firstName:
          type: string
          example: Joseph
        middleName:
          type: string
          description: >-
            can be an initial, if no value is provided a '-' will be stored with
            the volunteer reocord
        lastName:
          type: string
          example: Padres
        genderMale:
          type: boolean
        ethnicHispanic:
          type: boolean
          description: null indicates unknown
        otherRace:
          type: string
          description: additional race details if race type doesn't match
        dateOfBirth:
          type: string
          example: '1980-05-27'
          description: ISO DOB in form of yyyy-MM-dd
        nameSuffix:
          type: string
          description: jr, II
        nationality:
          type: string
        preferredLanguage:
          type: string
        address:
          type: string
        city:
          type: string
        region:
          type: string
          description: >-
            should match regions configured in the volunteer configuration
            component; ie state / province
        country:
          type: string
        postalCode:
          type: string
        homePhone:
          type: string
          description: >-
            tightly validated based on the general settings configured; should
            be as close to ISO format as possible with leading country code.
            https://github.com/google/libphonenumber is used for underlying
            validation
        workPhone:
          type: string
          description: see homePhone
        mobilePhone:
          type: string
          description: same rules apply as homePhone, but must be unique in database
        phoneNotes:
          type: string
          description: can be arbitrary notes to guide recruiters about making phone calls
        contactableByPhone:
          type: boolean
          description: volunteer's permission to be contacted by phone
          default: true
        contactableBySms:
          type: boolean
          description: volunteer's permission to be contacted by SMS
          default: true
        contactableByEmailCampaign:
          type: boolean
          description: volunteer's permission to be contacted by emails
          default: true
        nextOfKin:
          type: string
          description: >-
            notes generally about who to contact should there be a reason to do
            so in an emergency situation
        volunteerEmploymentStatus:
          type: string
          enum:
            - Unemployed
            - Student
            - EmployedPartTime
            - EmployedFullTime
            - Retired
        weightKilos:
          type: number
          format: double
          example: 123.45
        heightMeters:
          type: number
          format: double
          example: 2.12
        vegetarian:
          type: boolean
          description: null indicates unknown
        surgicallySterile:
          type: boolean
          default: false
        contraceptionType:
          type: string
          example: Abstinence
          description: should match a type configured in the volunteer configure component
        numberOfChildren:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 20
        menstruationStartAge:
          type: integer
          description: value should only be present for females
          minimum: 8
          maximum: 50
        menstruationEndAge:
          type: integer
          description: value should only be present for females
          minimum: 10
          maximum: 100
        lastPeriodStartDate:
          type: string
          example: '2024-05-27'
          description: In form of yyyy-MM-dd; value should only be present for females
        regularPeriodIntervalDays:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 100
        regularPeriodDurationDays:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 100
        currentlyPregnant:
          type: boolean
          description: value should only be present for females
          default: false
        currentlyBreastFeeding:
          type: boolean
          description: value should only be present for females
          default: false
        childBearingPotential:
          type: boolean
          description: value should only be present for females
          default: false
        allergies:
          type: boolean
          description: null indicates unknown
        emailAddress:
          type: string
          example: something@domain.com
          description: >-
            must be unique; strictly validated using Apache Commons Email
            Validator framework
        contactSource:
          type: string
          description: >-
            describes how a volunteer contact occurred; should match a source
            configured in the volunteer configure component
        generalPractitioner:
          type: string
          description: volunteer's physician
        generalPractitionerPhoneNumber:
          type: string
          description: volunteer's physician phone number
        generalPractitionerAddress:
          type: string
          description: volunteer's physician address
        siteId:
          type: integer
          format: integer
          example: -1
          description: >-
            the id of the site that the volunteer should be associated with; if
            not provided, use siteName
    VolunteerSubstanceUse:
      type: object
      properties:
        substanceUseCategory:
          type: string
          example: Alcohol
          enum:
            - Alcohol
            - Caffeine
            - Tobacco
            - Drugs
        name:
          type: string
          description: >-
            must be associated with the relevant category defined in the
            volunteer configure component
        useFrequency:
          type: string
          description: provides context to the useConsumption
          default: Week
          enum:
            - Day
            - Week
            - Month
            - Year
        useConsumption:
          type: string
          description: >-
            the amount of the substance consumed in the defined frequency;
            should be a number
          default: '5'
        consumptionUnit:
          type: string
          description: >-
            must be associated with the relevant category / name defined in the
            volunteer configure component
          default: Glass/Bottle (.5L)
        substanceUseStatus:
          type: string
          enum:
            - Social
            - Regular
            - Previous
        startDate:
          type: string
          description: >-
            yyyy-MM-dd; for partial dates, simply omit the fields 2009 would be
            2009, Jan of 2008 would be 2008-01, Feb 12 2007 would be 2007-02-12
        endDate:
          type: string
          description: see startDate
        lastConsumed:
          type: string
          description: see startDate
        substanceNotes:
          type: string
          description: general notes about the substance use
    RecruitmentAppointment:
      type: object
      properties:
        id:
          type: integer
          format: integer
        appointmentType:
          type: string
          example: Screening
          description: configured with study site details
        appointmentNumber:
          type: string
          example: A0001
        estimatedAppointmentDurationMinutes:
          type: integer
          format: int32
        appointmentNotes:
          type: string
        appointmentTime:
          type: string
          description: ISO date time in UTC
        cohort:
          $ref: '#/components/schemas/Cohort'
        recruitmentAppointmentStatus:
          type: string
          enum:
            - Unassigned
            - Assigned
            - CheckedIn
            - Failed
            - Success
        dateCreated:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
    Cohort:
      type: object
      properties:
        disabled:
          type: boolean
          default: false
        requireVolunteerRecruitment:
          type: boolean
          default: false
        name:
          type: string
          example: Cohort 1
        description:
          type: string
        subjectNumberAction:
          type: string
          enum:
            - SCREENING
            - LEAD_IN
            - RANDOMIZATION
            - APPOINTMENT
        dataLocked:
          type: boolean
          description: >-
            is data associated with the cohort locked for further data
            collection?
          default: false
        recruitmentActive:
          type: boolean
          description: is the cohort active for recruitment
        recruitmentMaleGoal:
          type: number
          format: int32
        recruitmentFemaleGoal:
          type: number
          format: int32
        recruitmentGoal:
          type: number
          format: int32
    VolunteerSearchResult:
      type: object
      properties:
        eligible:
          type: boolean
          description: true if the volunteer matches criteria of the volunteer search
          default: false
        name:
          type: string
          description: the name of the advanced search
        study:
          $ref: '#/components/schemas/Study'
        site:
          $ref: '#/components/schemas/Site'
        cohort:
          $ref: '#/components/schemas/Cohort'
    Site:
      type: object
      properties:
        id:
          type: integer
          format: integer
        archived:
          type: boolean
          description: is site archived?
          default: false
        name:
          type: string
          example: Grafton
        volunteerRegionLabel:
          type: string
          example: State
          description: allows for customizing a region (ie State, Province, etc)
        volunteerEnrollmentConfirmationStatement:
          type: string
          description: statement made during point of enrollment when staff is present
        heightUnits:
          type: string
          enum:
            - Meters
            - Centimeters
            - Inches
        weightUnits:
          type: string
          enum:
            - Kilo
            - Pound
        address:
          type: string
          description: street address
        city:
          type: string
        stateProvince:
          type: string
        postalCode:
          type: string
        country:
          type: string
        phoneNumber:
          type: string
        faxNumber:
          type: string
        timeZoneId:
          type: string
        investigatorId:
          type: string
        investigatorName:
          type: string
    Study:
      type: object
      properties:
        id:
          type: integer
          format: integer
        studyState:
          type: string
          enum:
            - DESIGN
            - ACTIVE
            - LOCKED
            - ARCHIVED
        name:
          type: string
        description:
          type: string
        protocolName:
          type: string
        epochs:
          type: array
          items:
            $ref: '#/components/schemas/Epoch'
    Epoch:
      type: object
      properties:
        disabled:
          type: boolean
          default: false
        name:
          type: string
          example: Treatment
        description:
          type: string
          example: Treatment
        cohorts:
          type: array
          items:
            $ref: '#/components/schemas/Cohort'
    StudySite:
      type: object
      properties:
        id:
          type: integer
          format: integer
        unassignedAppointmentCount:
          type: number
          format: int32
        appointmentTypes:
          type: array
          example:
            - Screening
            - OPV
          items:
            type: string
        locationOid:
          type: string
          example: '1'
        investigatorId:
          type: string
        investigatorName:
          type: string
        appointmentsRequireRecruitmentVolunteer:
          type: boolean
        appointmentsRequireRecruitmentVolunteerInCohort:
          type: boolean
        recruitmentDescription:
          type: string
        defaultAppointmentDurationMinutes:
          type: number
          format: int32
        recruitmentMaleGoal:
          type: number
          format: int32
        recruitmentFemaleGoal:
          type: number
          format: int32
        site:
          $ref: '#/components/schemas/Site'
        study:
          $ref: '#/components/schemas/Study'