openapi: 3.0.0
info:
  description: >-
    Allows for adding of volunteers, assignment and cancellation of
    appointments.
  version: 1.0.0-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.io/clinspark/api/v1/recruit'
    variables:
      ngrokPrefix:
        default: 04f5b951df6d
        description: first part of ngrok-assigned id
paths:
  /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: int64
        - 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:
                  type: object
                  properties: {}
      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: int64
        - 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'
        '400':
          description: Invalid username supplied
        '404':
          description: User not found
      security:
        - basicAuth: []
  /listVolunteerAppointments:
    get:
      tags:
        - recruit
      summary: >-
        Finds appointments for the given volunteer found by one of the
        parameters supplied
      parameters:
        - 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'
        '400':
          description: Invalid username supplied
        '404':
          description: User not found
      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: int64
        - 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: object
        '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: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
        '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:
        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
          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
          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: int64
          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'
        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'
    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: int64
        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